Files
deploy/README.md
T
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

99 lines
4.1 KiB
Markdown

# netOrk deploy
Installs and updates [netOrk](https://git.netork.io/NetOrk/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
```bash
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
```bash
./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](LICENSE).