Skip to main content

Run your own Zoop

Docker Compose runs the dashboard, API and PostgreSQL. The iPhone app collects recordings from your band; both clients use the same server-owned metrics.

You need Docker Engine with Compose v2, Git, and enough disk for your recordings. The first build compiles Rust and the web app. Prebuilt release images are not published yet. Linux amd64 is tested; Apple Silicon/arm64 validation is still pending.

Start​

git clone https://github.com/MakisChristou/zoop.git
cd zoop
./tools/setup.sh
docker compose up -d --build --wait
./tools/setup.sh --show-code

Open http://localhost:8080, enter the setup code, and create your admin account. Keep .env private: it contains generated database credentials and the setup code. Setup closes after the first account is created. Restarting does not reopen it.

The default port listens only on this machine. To connect a phone over your LAN, choose the server's LAN address when generating the configuration instead:

ZOOP_BIND=192.168.1.20 ./tools/setup.sh http://192.168.1.20:8080

Replace the example address with yours. If .env already exists, edit its ZOOP_ORIGIN and ZOOP_BIND instead; the setup command never overwrites it. ZOOP_PORT changes the host port. Reapply changes with docker compose up -d --wait.

Access and HTTP​

Zoop serves HTTP. You choose the network arrangement: local access, a VPN, or your own HTTPS reverse proxy. It does not manage DNS, certificates or router settings.

ZOOP_ORIGIN must be the exact URL users open, including any non-default port, without a path or trailing slash. Proxy the whole origin to the web container; it serves the dashboard and forwards API requests. Do not expose PostgreSQL or the API container separately. A proxy on another host or Docker network needs an explicit reachable ZOOP_BIND; the default loopback listener is host-local.

Browser sessions use HttpOnly, SameSite cookies and origin checks. HTTPS origins also use Secure cookies. HTTP carries passwords and health data unencrypted: use it only on a trusted network or through a VPN. HTTPS retains normal certificate validation; Zoop does not accept arbitrary self-signed certificates. Some browsers require HTTPS for clipboard access; on HTTP, open a shared link and copy its address.

Connect your iPhone​

Build the iPhone app, then enter the same server address and account credentials. Allow local-network access if iOS asks. The app supports HTTP and HTTPS self-hosted addresses. An App Store release is planned, not available.

Each band must belong to an account before uploads are accepted. You can enter its serial during setup or assign it later from the server:

docker compose exec api /usr/local/bin/zoop --config /etc/zoop/zoop.toml \
account bind-device --email owner@example.com --device YOUR_STRAP_SERIAL

Use the strap serial, not its Bluetooth UUID. Ownership is explicit; the server never gives an account somebody else's recordings automatically.

More accounts and password recovery​

There is no public sign-up. Create additional accounts with the operator command. Put the password in a local file readable only by you (chmod 600), then pass it through standard input:

docker compose exec -T api /usr/local/bin/zoop --config /etc/zoop/zoop.toml \
account create --email member@example.com --password-file - < /secure/path/password.txt

Use account reset-password with the same arguments to recover an account. This revokes its existing sessions and phone tokens. Add --admin only when creating an administrator. Admin statistics do not grant access to other users' health data. Emails are login identifiers; Zoop does not send email or require an SMTP server.

Back up and restore​

PostgreSQL stores accounts, original recordings, derived metrics and profile photos in the database Docker volume. docker compose down preserves it; down -v deletes it. Keep an encrypted copy of .env alongside your backups.

mkdir -p backups
./tools/backup.sh backups/zoop.dump

The dump is a consistent database snapshot, created with private permissions. The command refuses to overwrite a file. Choose a new filename for each backup; copy backups off the server and periodically test restoration.

Restore into a new installation, before starting its API:

./tools/setup.sh
docker compose up -d --wait database
./tools/restore.sh /path/to/zoop.dump
docker compose up -d --build --wait

Restore refuses a database containing tables. Existing accounts, ownership and recordings return with the dump; first-run setup remains closed. Apply your chosen origin and bind address to the new installation's .env before starting it.

Update and troubleshoot​

Back up first, check release notes, then check out the desired revision and run:

docker compose up -d --build --wait
docker compose ps
docker compose logs --tail 100 api web

Pending migrations run before the API starts. An application downgrade may be incompatible with a newer database: restore the matching backup into a separate installation instead of forcing an old binary onto it.

/health reports API liveness; /ready also checks worker readiness. A failed migration or health check prevents the stack from being reported ready. Logs can include device identifiers; redact them before sharing. If setup is unavailable on an existing database, use the operator commands rather than deleting accounts.