oxen-core/contrib/docker

Dockerfile for end users

For users who take comfort in containerization.

Benefits

• Distro agnostic: run on any Linux distro with docker installed
• Security isolation: run untrusted software without fear
• Resource isolation: run oxend with a specific amount of CPU and memory
• Simplicity: get up and running with only a few commands

Quickstart

If you just want to build the container image and get oxend running:

$ sh build_base_container.sh
$ sh build_oxend_container.sh
$ docker run -d -p 22022:22022 --name oxend oxend:9.1.0

The blockchain and wallet won't be persisted beyond the containers lifetime, so you probably want to continue reading if you want to run the container long-term.

Usage details

Building the container

build_container.sh builds a Docker container image based on Ubuntu 20.04 using the most-recent oxen pre-compiled binaries. The RELEASE variable can be updated for any release version. Once built, the container image is stored locally:

$ docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
oxend               9.1.0               17046241ccc2        3 minutes ago       159MB

The image can be used to run the oxend container locally. The image can also be uploaded to a docker registry so that other users can use it without needing to build it.

Run the container

Run the container, storing the blockchain in Docker volume oxen-blockchain:

$ docker run --name oxend -d --mount "source=oxen-blockchain,target=/home/oxen/.oxen,type=volume" oxend:9.1.0

Same as above, but additionally mounting the wallet directory /home/<your_user>/Oxen to /wallet in the container:

$ docker run --name oxend -d --mount "source=oxen-blockchain,target=/home/oxen/.oxen,type=volume" \
                             --mount "source=/home/<your_user>/Oxen,target=/wallet,type=bind" oxend:9.1.0

Check on how the synchronization is going:

$ docker logs oxend

Limiting resource usage

On a shared server, it may be useful to limit the amount of resources the oxend container can consume. The recommended minimum specs are 4G memory, 2 CPUs, and 30G disk. The memory and CPUs can be limited easily in the run command:

$ docker run --name oxend -d --mount "source=oxen-blockchain,target=/home/oxen/.oxen,type=volume" \
                             --mount "source=/home/<your_user>/Oxen,target=/wallet,type=bind" \
			     --memory=4g --cpus=2 oxend:9.1.0

Note: the blockchain sync speed will be impacted by limiting the CPU allocation.

The disk capacity is mostly used to store the blockchain. It's large, and will grow (slowly) over time. To prevent it from consuming the OS partition, it is a good idea to use a separate partition for /var/lib/docker. Many VPS companies allow for attaching easily-resizable volumes to a VPS; such a volume can be used to grow the volume as needed.

Run the wallet CLI

These steps assume the oxend container was started with your walled directory bind mounted to /wallet inside the container.

To run against your local oxend:

$ docker exec -it oxend oxen-wallet-cli --wallet /wallet/wallets/<your_wallet_name>

To run against a public daemon:

$ docker exec -it oxend oxen-wallet-cli --wallet /wallet/wallets/<your_wallet_name> \
                                        --daemon-address public.loki.foundation:22023

Stopping the container

Stop the container from running:

$ docker stop oxend

After the container is no longer running, it can be deleted. Assuming you mounted the oxen-blockchain volume, the blockchain will not be deleted:

$ docker rm oxend

If you add the --rm flag to the docker run command, then the container will be automatically removed when it is stopped.

Removing the oxen-blockchain volume

The oxen-blockchain volume has its own lifecycle, and can be mounted as newer versions of the container become available. However, it can be deleted easily:

$ docker volume rm oxen-blockchain

Remember, you will need to resync the blockchain if you remove the oxen-blockchain volume.