Running Parity with Docker

Initial set-up

I started with the QNAP Container Station GUI, but quickly dropped to a command line to do most things. The GUI remains useful for quickly stopping and restarting containers, and for setting resources limits. You need to have Container Station installed in any case to access Docker from the command line, so install it from the App Center.

Via the QNAP GUI

For my very first install of Parity I used the QNAP GUI app. In Container Station, select Create Container and type "parity" in the search box. Available images will show up on the Docker Hub tab. Click "Create" next to "ethcore/parity". (Be cautious about installing any other image than from Ethcore - malicious versions that will steal your keys are not unknown.) You will be asked to select which version: select "stable-release" or "beta-release" from the drop-down list. After acknowledging the pop-up disclaimer click "Create" on the Create Container dialogue. Parity should now start running!

Back in the Container Station Overview tab you can click on the running container and see what it's up to. Clicking on the arrows next to Console will open up a new Web browser tab containing fuller output from the container's console. You should see Parity announcing its version, its ehash and then starting to sync.

Enabling warp sync, and other command-line options

The steps above will lead to Parity starting to sync from scratch which is going to take a while (maybe a couple of days). For v1.3.x ("stable", as of the time of writing) this is basically the only way. For v.1.4.x ("beta") you have the option of "warp" sync. To enable this, when the Create Container dialogue appears, enter /build/parity/target/release/parity --pruning fast --warp in the "Entrypoint" box. Warp sync will download a recent snapshot from peers to get up and running and then fill in the earlier blocks in the background.

Via the command line

The GUI option above gets tired very quickly. As an alternative to the above, you can also ssh into the QNAP as administrator and just type the following.

docker pull ethcore/parity:beta-release
docker run -d --name my_parity ethcore/parity:beta-release --pruning fast --warp

You can still monitor the container in the Container Station GUI.

Extracting the blockchain folder

At some point you're going to want to update the Docker image - I found that new images were released several times a week during the network attacks. I soon realised that if I just downloaded and ran a new image, I'd have to begin syncing all over again from scratch. Not an appealing prospect.

To avoid this, it is necessary to store the blockchain data outside the Parity container.

If you've got a well-synced chain in a container already then you need to extract it first. If you are starting from scratch you can skip this first step and just create an empty parity/ directory somewhere in the filesystem - ideally on your SSD if you have one. Mine is in /share/CACHEDEV2_DATA/parity/.

Extracting the blockchain from a container

This requires running a command line on the NAS.

First, use docker cp to copy the blockchain data out of the container onto the NAS's own filesystem. It's probably best to stop the Parity container to do this.

docker cp my_parity:/root/.parity /share/CACHEDEV2_DATA/parity

This copies the whole of the container's .parity directory, which includes the blockchain database directory, into a local directory on the NAS called /share/CACHEDEV2_DATA/parity.

Note that my_parity is the name assigned to the Parity container. Use your name here if you called it something different.

Mounting the blockchain directory back on to containers

Now when we run a Parity image, we can attach the NAS's copy of the blockchain to the container and Parity will start syncing from there rather than right from the beginning. This is done with the -v flag to docker run:

docker run -d --name my_parity -v /share/CACHEDEV2_DATA/parity:/root/.parity etchcore/parity:beta-release --pruning fast --warp

Memory usage in Docker

It's worth noting that Docker seems to overstate memory usage. All the Docker metrics I've found (e.g. docker stats, /sys/fs/cgroup/memory/docker/xxx/memory.usage_in_bytes, the Container Station GUI) apparently include cached memory (disk cache, not Parity cache) which doesn't really count towards total usage. The useful metric is Resident Set Size (RSS) which is the figure that the top command reports.

For the record, you can alse see the container's RSS in the output of cat /sys/fs/cgroup/memory/docker/xxx/memory.stat, where "xxx" is the docker container's hash value (from docker ps for example).

Using a Docker Compose file

It turns out that a convenient way of updating containers and storing configuration info is to use something called a compose file. These are called docker-compose.yml. One of the advantages is that Docker Compose can automatically check for newer image files in the repository and download them accordingly.

Here's a docker-compose.yml file that implements the configurations we've done so far as well as a couple of new ones.

version: '2'
services:
  parity:
    image: ethcore/parity:beta-release
    entrypoint: /build/parity/target/release/parity --cache-size 512 --pruning fast --warp
    network_mode: 'host'
    volumes:
      - /share/CACHEDEV2_DATA/parity:/root/.parity
    mem_limit: 1.5G

The new configurations added here are as follows.

• --cache-size 512 - allocate 512MB of cache for Parity to use as it sees fit.
• network_mode: host - use the QNAP's native network rather than Docker's bridged network mode. Gives a small speedup, but seems to be a bit controversial for some reason. Anyway, it works well for me.
• mem_limit: 1.5G - set the maximum RSS memory usage of the container to 1.5GB. This is plenty when the network is operating normally, even with the cache. If you eliminate the cache then 500M may be enough.

Now all we need to do to update to the newest version of ethcore/parity:beta-release is the following (make sure you are in the same directory as the compose file).

docker-compose pull
docker-compose up -d

If there is no update to be done, it won't do anything. If you've edited the compose file, or if the pull command found and downloaded a new image file, it will restart the container.