Christian Manivong e43e68553f
CI / check (pull_request) Successful in 1m39s
docs: write the README for people installing netOrk themselves
The repository is meant for customers who run netOrk on their own
hosts. Drop the development section, the internal build tags
(latest-dev, main-<sha>, feature-<name>), CI wording and issue
references from the README and deploy.env.example; only latest and
release numbers are documented.
2026-10-18 21:15:23 +02:00

netOrk deploy

Installs and updates netOrk on one or more of your own Docker hosts, from netOrk's published images.

The machine you run the deploy from needs this repository, ssh and a deploy.env. Each server pulls the images itself. The compose files come out of the image for the version being deployed, so they always match the images they start, and database migrations run from that same image.

Requirements

On the machine running the deploy:

  • bash
  • ssh with key-based access to every target

On every target server:

  • at least 4 GB of RAM. On a server with 74 devices, netOrk's containers took about 2.4 GB, and at least 0.9 GB stayed free. Larger tasks need that room.
  • Docker with the compose plugin
  • a directory ~/netork/ with netOrk's .env, which holds the database and application settings

Raspberry Pi and other arm64 hosts: a Raspberry Pi 3, 4, 5 or Zero 2 W with a 64-bit OS can be a target, from netOrk 0.34.0 on. Nothing changes in deploy.env: each host pulls the variant for its own platform. A version that has no arm64 image is refused before the host is touched.

Setup

cp deploy.env.example deploy.env
$EDITOR deploy.env

Set DEPLOY_ENV_FILE to keep the file somewhere else.

Variable Meaning
DEPLOY_SERVERS Space-separated default targets
UI_SERVER Targets that also run the web interface (netork-ui)
REGISTRY_HOST Registry to pull from; required
NETORK_VERSION Version to deploy (default latest)
REGISTRY_USER, REGISTRY_PASSWORD Registry login used on every server
REGISTRY_USER_<server>, REGISTRY_PASSWORD_<server>, NETORK_VERSION_<server> Per-server overrides. <server> has its dots replaced by underscores, e.g. _10_0_0_2
DEPLOY_LOCK_WAIT Seconds to wait for another deploy to the same host (default 900)

Usage

./deploy.sh                          # every server in DEPLOY_SERVERS
./deploy.sh 10.0.0.1                 # one server
./deploy.sh 10.0.0.1 10.0.0.2        # several, in parallel
./deploy.sh --version=0.37.0 10.0.0.1   # a specific version, this run only

NETORK_VERSION and --version take latest for the newest release or a release number such as 0.37.0.

The same command installs netOrk the first time and updates it later.

What a deploy does, per server

  1. Makes sure only one deploy runs on the host at a time. A second deploy to the same host waits, says who is deploying which version, and gives up after 15 minutes (DEPLOY_LOCK_WAIT) without touching the host.
  2. Logs in to the registry. The password travels over ssh's stdin, never on a command line. Then it checks that the version has an image for the host's platform and stops if it doesn't.
  3. Pulls the images and copies the matching compose files into ~/netork/.
  4. Records the registry and version in ~/netork/.env, so that a docker compose command typed on the host uses the same images. A failed pull leaves .env as it was.
  5. Restarts netOrk's containers on the new images. If that fails, it tries once more; if it fails again, it prints the container states and stops.
  6. Updates the helper services (apt-cacher-ng, signal-api) only when their definition changed, and removes services netOrk no longer ships. It never touches the database (postgres) or redis.
  7. Verifies that the containers run exactly the images that were pulled.
  8. Applies database migrations.
  9. Removes unused images.

If a step fails, that server's deploy stops and the other servers carry on. The script exits non-zero if any server failed and names those servers.

Operating notes

  • Never delete these Docker volumes:
    • celerybeat_schedule holds the scheduler state.
    • signal_cli_data holds netOrk's Signal device link. Losing it means pairing again by QR code.
  • Always deploy with this script. Do not point a local Docker client at a remote host (DOCKER_HOST=ssh://…): it resolves volume paths locally and breaks the remote containers.

License

MIT, see LICENSE.

S
Description
Deploys netOrk to Docker hosts from pre-built registry images
Readme MIT
207 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 62.8%
Shell 37.2%