Skip to content

Getting Started

This guide walks through the first deployment of Privitty Edge on a gateway using Docker.

Prerequisites

  • Docker 20.10+ with buildx (for multi-arch pulls, Docker handles this automatically)
  • Network egress to the Privitty relay (chat.privittytech.com by default)
  • A profile name for this gateway (e.g. factory-gw-01) — used as the display name
  • A license delivery URL from the Privitty admin portal (required for encrypted send operations)

Step 1 — Start the container

docker run -d \
  --name privitty-edged \
  --restart unless-stopped \
  -e PRIVITTY_PROFILE=factory-gw-01 \
  -e PRIVITTY_LICENSE_URL="https://plm.privittytech.com/v1/license/YOUR_TOKEN" \
  -p 127.0.0.1:7200:7200 \
  -v privitty-data:/var/lib/privitty \
  privitty/edge:latest
Flag Purpose
PRIVITTY_PROFILE Required. Gateway display name on first run
PRIVITTY_LICENSE_URL Recommended. Activates license during startup — no separate step
-p 127.0.0.1:7200:7200 Bind API to localhost on the host (recommended)
-v privitty-data:… Persist keys, database, blobs, and license

Inside the container

The daemon listens on 0.0.0.0:7200 by default so Docker port mapping works. The image CMD sets this automatically.

Docker Desktop volumes

On macOS/Windows, the entrypoint starts as root, chowns the named volume to UID 1000, then drops privileges. No manual volume init is needed on current images.

Step 2 — Wait for provisioning

On first start, the daemon:

  1. Prepares /var/lib/privitty (volume ownership on Docker Desktop)
  2. Creates the Delta Chat accounts directory
  3. Activates the license from PRIVITTY_LICENSE_URL (if no privitty.lic yet)
  4. Registers with the Privitty relay and receives credentials
  5. Runs IMAP/SMTP autodiscovery (10–30 seconds)
  6. Initializes encryption keys and starts the HTTP server

Watch the logs:

docker logs -f privitty-edged

Expected output (abbreviated):

[privitty-edged] Profile  : factory-gw-01
[privitty-edged] Accounts : /var/lib/privitty
Running as root — preparing /var/lib/privitty for UID 1000 (Docker volume init)
Dropped privileges to UID 1000
[privitty-edged] Activating license from delivery URL…
[privitty-edged] License activated (id=…, type=…, expires=…)
[privitty-edged] Provisioning via chatmail …
[privitty-edged] Account ready: abc123@chat.privittytech.com  (display: factory-gw-01)
[privitty-edged] License: active (id=…, type=…, max_devices=…)
HTTP server ready on http://0.0.0.0:7200

Profile vs e-mail address

PRIVITTY_PROFILE is your local display name, not the relay-assigned e-mail address. The relay assigns the actual address (e.g. abc123@chat.privittytech.com).

Step 3 — Verify health

curl -s http://127.0.0.1:7200/health | jq .

{
  "status": "ok",
  "service": "privitty-edged",
  "version": "0.1.0"
}

Step 4 — Get the account address

curl -s -X POST http://127.0.0.1:7200/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"get_config","params":[1,"addr"],"id":1}'

{"jsonrpc":"2.0","result":"abc123@chat.privittytech.com","id":1}

Save this address — peers use it to identify your gateway.

Step 5 — Verify license

If you passed PRIVITTY_LICENSE_URL at start, the license is already active. Confirm:

docker exec privitty-edged \
  privitty-edge --accounts /var/lib/privitty license status

Expected:

Status : active

If the container was started without a license URL, activate and restart:

docker exec privitty-edged \
  privitty-edge --accounts /var/lib/privitty \
  license activate "https://plm.privittytech.com/v1/license/YOUR_TOKEN"

docker restart privitty-edged

See License Management for sync, deactivate, and error handling.

Step 6 — Connect a peer and send a message

  1. Generate an invite on the gateway — Example B
  2. Share the invite link with the remote operator or cloud node
  3. Send an encrypted message once the peer has joined
# After resolving chat_id 7 with your peer:
curl -s -X POST http://127.0.0.1:7200/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"send_msg","params":[1,7,{"text":"Hello from the gateway"}],"id":2}'

Next steps