.. | ||
build_base_container.sh | ||
build_oxend_container.sh | ||
Dockerfile.oxen-ubuntu | ||
Dockerfile.oxend | ||
README.md |
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.