Oak: How to run

Using Podman or Docker

Quickstart: Run in a container (pull already built image)
Run in a container (build from local checkout)
Run in a container (build from repo snapshot)
Run on myNode

Building from source

Build and run from source

Quickstart: Run in a container (pull already built image)

This is the fastest way to get an Oak Node container up and running. Note that no data will be persisted on-disk, so when you remove the container, you will lose all Oak configurations.

# Adjust these two lines to point to your LND
export OAK_LND_REST_API_URL=https://lnd-rest-api-endpoint:port
export LND_DIR=/path/to/lnd/data/dir

podman run --interactive --rm \
  --network host \
  --volume $LND_DIR:/lnd-dir:ro \
  --env OAK_LND_REST_API_URL \
  --env OAK_LND_MACAROON_PATH=/lnd-dir/data/chain/bitcoin/mainnet/admin.macaroon \
  --env OAK_LND_CERT_PATH=/lnd-dir/tls.cert \
  oak-node.net/oak

Once it started, the Oak UI is reachable at http://localhost:8000.

Note: for myNode, a separate container tag is available. See Run on myNode section below.

Run in a container (build from local checkout)

Use this approach if you want to build and run containers based on the locally checked-out source code, including any local patches or modifications.

This assumes that:

the Containerfile was retrieved together with the rest of the source code (e.g. not a standalone file)
the local machine has podman installed
the local machine has a data folder with the LND macaroon and certificate (lnd-dir)
the local machine has network access to LND

Build the image

From the root of the source code checkout, run

podman build \
  --file build-local.containerfile \
  --tag oak-local \
  .

Start an ephemeral container

This will start an interactive container and remove it on exit:

podman run --interactive --rm \
  --network host \
  --volume /local/path/to/lnd-dir:/lnd-dir:ro \
  --env OAK_LND_REST_API_URL=https://localhost:10080 \
  --env OAK_LND_MACAROON_PATH=/lnd-dir/admin.macaroon \
  --env OAK_LND_CERT_PATH=/lnd-dir/tls.cert \
  oak-local

The host-local LND data directory is mounted as read-only in the container under /lnd-dir. The macaroon and certificate paths given to Oak are therefore relative to it, for example:

/lnd-dir/data/chain/bitcoin/regtest/admin.macaroon
/lnd-dir/tls.cert

From within the container, the ports available on the host are reachable under localhost:port. For example, if the LND REST API is reachable under port 10080, the container can reach it under https://localhost:10080 .

From the host, the container's Web UI is reachable directly locally under http://localhost:8000.

Start / stop a persistent container

The same podman run command above, but without the --rm flag, will persist the container data after it exits.

Find the container ID with

podman ps --all

Start it again with

podman start --interactive --attach --latest

or replace --latest with the first few characters of the ID.

Mount volumes to persist Oak data and logs

Another approach is to mount local folders as container volumes, such that the Oak Node data and logs are saved in these folders on the host.

To do this, we first create a folder for the data and a subfolder for the logs:

mkdir -p temp-data-1/log

Next, we use podman unshare to give permissions for these folders to the container user with UID 1000, as that will be the user under which the Oak command will run:

podman unshare chown -R 1000:1000 temp-data-1

Finally, we run the container:

podman run --interactive \
  --network host \
  --volume /local/path/to/lnd-dir:/lnd-dir:ro \
  --volume temp-data-1:/oak/data \
  --volume temp-data-1/log:/oak/log \
  --env OAK_DATA_DIR=data \
  --env OAK_LND_REST_API_URL=https://localhost:10080 \
  --env OAK_LND_MACAROON_PATH=/lnd-dir/admin.macaroon \
  --env OAK_LND_CERT_PATH=/lnd-dir/tls.cert \
  oak-local:latest

Run in a container (build from repo snapshot)

Use this approach if you want to build and run containers based on a source code snapshot.

For this, you don't need to download or checkout the entire repo, you can instead download only the Containerfile and use it on its own.

Build the image

Create a new directory and change to it:

mkdir temp && cd temp

Download the latest build-repo.containerfile:

wget --content-disposition 'https://oak-node.net/file/build-repo.containerfile?ci=trunk&download'

Build an image from the latest trunk (or change the version argument to any other branch, tag or commit ID):

podman build \
  --build-arg version=trunk \
  --file build-repo.containerfile \
  --tag oak-repo-snapshot \
  .

Optionally, add another --buildarg user_id=1001 to build an image where Oak files are owned by a custom user ID. This otherwise defaults to 1000.

Start / stop a container

You can use the same commands as in the previous section, just change the image used.

Run on myNode

To run on myNode, ssh to it with the admin user, while port-forwarding the remote port 8000 to your local port 8000:

ssh -L 8000:localhost:8000 admin@mynode.local

Once connected, run a temporary Oak container with:

docker run --interactive --rm \
  --user 1001:1002 \
  --network host \
  --volume /mnt/hdd/mynode/lnd:/lnd-dir:ro \
  --env OAK_LND_REST_API_URL=https://localhost:10080 \
  --env OAK_LND_MACAROON_PATH=/lnd-dir/data/chain/bitcoin/mainnet/admin.macaroon \
  --env OAK_LND_CERT_PATH=/lnd-dir/tls.cert \
  --env OAK_ONION_SOCKS5_HOST=localhost \
  --env OAK_ONION_SOCKS5_PORT=9050 \
  oak-node.net/oak:latest

Oak will start at http://localhost:8000. Use Ctrl+C to stop it.

Note: this is an experimental setup to test the integration with myNode.

Also note the --rm flag will remove the container and its data when stopped.

Build and run from source

First, make sure you have rust installed. If you don't, a simple way to get it is via rustup.

Then download the code from the Releases page and extract it.

You can now build the Oak Node binary with cargo build or directly run from source with cargo run.