Install with Docker Compose

Install with Docker Compose

Important

Coming soon. The commercial Docker image is not published yet, so this path is not available for this release. Use the systemd package, which is the supported install path. This page shows how the Docker setup will work.

The Docker setup runs the same node as two containers from one image, vonode/vonode:

• vonode: the core. Host network, privileged (it needs TUN/XFRM, USB and ALSA), talks to the modules.
• vonode-gateway: the unprivileged, read-only SSH service the app connects to on TCP 2222.

The files are in the docker/ folder of the install package: setup.sh, docker-compose.yml and README.md.

1. Prepare the host

Same host, module and SIM requirements as the systemd install. Then:

sudo systemctl disable --now ModemManager
curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker
docker compose version        # must print a Compose v2 version

Docker Desktop on macOS or Windows is not supported.

2. Download and verify the package

Note

The first public release has not been published yet. When it is, it will appear on the Releases page; until then the download commands below will not work.

VERSION=vX.Y.Z        # replace with the release tag
BASE=https://github.com/vonode/vonode-releases/releases/download/$VERSION
curl -fLO $BASE/vonode_${VERSION}_linux_amd64_commercial.tar.gz
curl -fLO $BASE/vonode_${VERSION}_linux_amd64_commercial.tar.gz.sha256
sha256sum -c vonode_${VERSION}_linux_amd64_commercial.tar.gz.sha256
tar -xzf vonode_${VERSION}_linux_amd64_commercial.tar.gz
cd vonode_${VERSION}_linux_amd64_commercial/docker

3. Run setup.sh

sudo ./setup.sh --host node.example.com --image vonode/vonode@sha256:<digest>

• --host: the domain or IP the phone uses to reach the node. Without it, the script proposes the host's LAN address.
• --image: the verified vonode/vonode@sha256:<digest> from the release notes of a version that provides one. When the package already carries its verified image, leave it out. Mutable tags are refused unless you add --allow-tag. Without a default image and without --image, the script stops with exit code 2.

The script:

1. checks Linux/amd64, root, Docker and Compose, and warns when ModemManager is running;
2. lists the detected modules and their device nodes;
3. creates config/, data/ and logs/ (mode 0700, root), writes .env and docker-compose.override.yml, and on the first run copies the configuration template into config/config.yaml;
4. pulls the image, starts both containers and waits until both are healthy (about half a minute on a first start);
5. prints where the initial administrator password is (config/initial-admin-password, root only) and shows the pairing QR code.

Open TCP 2222 on the host firewall (sudo ufw allow 2222/tcp). Re-running sudo ./setup.sh keeps your configuration and data.

Files

File	Purpose
setup.sh	One-step setup; re-run it any time
docker-compose.yml	The two services, named volumes and bind mounts. Do not edit the managed values; .env carries them
.env (generated)	Image reference, SSH port, time zone, pairing address, device mode. Lines you add are kept
docker-compose.override.yml (generated)	The device mapping; rewritten on every run
config/, data/, logs/	Configuration, SQLite database and logs. Back them up together

Options

--image <ref>      --allow-tag      --host <address>   --port <n>   --public-port <n>
--admin-port <n>   --tz <zone>      --dir <path>       --bind-dev   --devices   --no-devices
--no-pull          --no-start       --no-pair          --uninstall  --purge   --yes

./setup.sh --help explains each one. Exit codes: 0 ok, 1 runtime failure, 2 bad usage, 3 host requirement not met.

Device mapping

Mode	What the core sees	When to re-run setup.sh
default (/dev bind)	The whole /dev, so hot-plugged and re-enumerated modules appear by themselves	Not needed for module changes
--devices	Only the module device nodes present at setup time (/dev/ttyUSB*, /dev/cdc-wdm*, plus /dev/net/tun and /dev/snd)	After plugging in, moving, replacing or resetting a module
--no-devices	Nothing (hosts without a module, tests)

The chosen mode is remembered in .env (VONODE_DEVICE_MODE).

Pairing

setup.sh shows the QR code at the end. For a new code later, in the docker/ folder:

sudo docker compose exec vonode /app/vonode pair -c /app/config/config.yaml -host node.example.com -port 2222

See Pairing the app.

Everyday operation

Task	Command
Status (both healthy)	sudo docker compose ps
Logs	sudo docker compose logs -f vonode
Added or moved a module	sudo ./setup.sh
Restart (up to two minutes)	sudo docker compose restart vonode
Stop, keep data	sudo ./setup.sh --uninstall
Remove everything	sudo ./setup.sh --uninstall --purge
Lost administrator password	sudo docker compose stop vonode, sudo docker compose run --rm --no-deps vonode reset-password -c /app/config/config.yaml, sudo docker compose start vonode

Warning

Never run docker compose down -v. The vonode_gateway-private volume holds the SSH host key that paired phones pin.

Upgrade

Put the new verified vonode/vonode@sha256:<digest> in .env (VONODE_IMAGE=...) or pass it with --image, then run sudo ./setup.sh. See Upgrading.