/docker-rippled

Run XRP Ledger (rippled) node in a Docker container

Primary LanguageShellMIT LicenseMIT

Rippled (node)

This container allows you to run a rippled node. No config required.

The server will keep a history of only 256 ledgers. You can change this value in the config (more about the config in this readme).

The container is configured to serve a public http websocket at port 80 and the local rpc admin service in the container at port 5005. Other ports (443, 6006, 51235) can be mapped but should be enabled in the config first.

This container is running on ubuntu:latest.

How to run

From Github

If you downloaded / cloned the Github repo you got yourself a few scripts to get started. In the ./go folder, the following scripts are available, run:

  • go/build to build the container image (tag: rippled)
  • go/up to create a new container named rippled and setup the port and persistent config (*1)
  • go/down to stop and remove the container rippled

The go/up command will mount the subfolder (in the cloned repo folder) config to the container; the rippled.cfg config and validators.txt will be loaded from this folder when rippled starts. If you stop/start or restart the container, the container will pickup your changes.

When starting the container the go/up script will map port 80 on your host to port 80 in the container. This is where rippled is configured to serve a websocket. If you want to run the websocket on another TCP port, you can enter the port after the go/up command, eg.:

go/up 8080

After spinning the container up, you will see the rippled log. You should see a lot of information show up within a few seconds. If you want to stop watching the log, press CTRL - C. The container will keep on running in the background.

If you want to build the image manually, use (you can change the tag):

docker build --tag rippled:latest .

From the Docker Hub

Use the image xrpllabsofficial/xrpld.

Because you only retrieved the container image from the Docker Hub, you have to manually create a container based on the image. When creating the container, please make sure you open port 80.

If you run the container with a mapping to /config/ (in the container) containing a rippled.cfg and validators.txt file, these will be used. If the mapping or these files aren't present, rippled will start with the default config.

This command launches your rippled container and the rippled websocket at port 80:

docker run -dit \
    --name rippled \
    -p 80:80 \
    -v /my/local/disk/xrpld-config/:/config/ \
    xrpllabsofficial/xrpld:latest

You can change the --name and make sure you specify a valid local full path for your volume source, instead of /my/local/disk/xrpld-config/.

You can fetch a working sample config from the Github repo.

Note on Apple M1 / M2 chips:

Run the container with --platform linux/amd64 to get it to work on your Mac M1 / M2.

Passing arguments/environment variables

Both environment variables passed with -e to docker run and arguments added at the end of the docker run command will be passed. E.g.:

docker run \
  -e TESTVAR=123123 \
  -it --name rippled -p $PORT:80 \
  -v $(pwd)/../config:/config/ \
  xrpllabsofficial/xrpld:latest \
  -a \
  --start

... will pass the environment variable TESTVAR with value, and the arguments -aaa and -c to rippled.

Alternatively, if you can't pass direct arguments, you can pass a string of arguments as an environment variable called ENV_ARGS, like this:

docker run \
  -e ENV_ARGS="-a --start" \
  -it --name rippled -p $PORT:80 \
  -v $(pwd)/../config:/config/ \
  xrpllabsofficial/xrpld:latest

So it's running

If you want to check the rippled-logs (container stdout, press CTRL - C to stop watching):

docker logs -f rippled

If you want to check the rippled server status:

docker exec rippled server_info

Check the value of complete_ledgers in the server info to see if the server has complete ledgers with transactions. When you launch the container it may take a few minutes for the server to sync.

If you started the container manually, you may have to change the name of the container (rippled) to the name you entered in your docker run command.

Connecting

You can now connect to the rippled websocket using a client like xrpl.js.

Updating

Update process

  1. Stop the container: docker stop rippled (if you named (--name) the container rippled)
  2. Remove the container: docker rm rippled
  3. Remove the image: docker rmi xrpllabsofficial/xrpld:latest (or if you built the container image based on the Github repo: use the image name you specified when building)
  4. Re-create the container; if you used Git: git pull and go/build - if you used the Docker Hub: just use the command from this Readme (From the Docker Hub), a new version of the image will be downloaded.

USE THE PATHS YOU SPECIFIED (-v argument) WHEN RECREATING THE CONTAINER IF YOU WANT TO KEEP YOUR CONFIG AND/OR DATA!

Building & publishing to Docker Hub:

version=1.11.0 # Sample
docker build --no-cache --tag xrpllabsofficial/xrpld:$version .
docker push xrpllabsofficial/xrpld:$version
docker tag xrpllabsofficial/xrpld:$version xrpllabsofficial/xrpld:latest
docker push xrpllabsofficial/xrpld:latest