CI / check (pull_request) Successful in 1m39s
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.
99 lines
4.1 KiB
Markdown
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).
|