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.
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
sshwith 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
- 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. - 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.
- Pulls the images and copies the matching compose files into
~/netork/. - Records the registry and version in
~/netork/.env, so that adocker composecommand typed on the host uses the same images. A failed pull leaves.envas it was. - 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.
- 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) orredis. - Verifies that the containers run exactly the images that were pulled.
- Applies database migrations.
- 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_scheduleholds the scheduler state.signal_cli_dataholds 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.