Install your VOTPort instance

Before you start

Have Docker with the Compose plugin, a DNS name pointing to your server, a TLS reverse proxy, and the image reference supplied for your release. Keep the version and sha256 digest together. The example below deliberately requires you to provide your release and credentials.

The service runs as UID and GID 1000. Create the mount directories on supported storage:

sudo install -d -o 1000 -g 1000 -m 0700 data
sudo install -d -o 1000 -g 1000 -m 0755 received outbound

The parent directories must also pass the storage safety checks.

Compose service

Create compose.yaml:

services:
  votport:
    image: "${VOTPORT_IMAGE:?Set the released image reference and digest}"
    restart: unless-stopped
    stop_grace_period: 5m
    user: "1000:1000"
    ports:
      - "127.0.0.1:8321:8080"
    environment:
      VOTPORT_PUBLIC_URL: "${VOTPORT_PUBLIC_URL:?Set the HTTPS address}"
      VOTPORT_ADMIN_PASSWORD: "${VOTPORT_ADMIN_PASSWORD:?Set a strong password}"
      VOTPORT_TRUSTED_PROXIES: "${VOTPORT_TRUSTED_PROXIES:?Set the proxy peer range}"
    volumes:
      - ./data:/data
      - ./received:/received
      - ./outbound:/outbound

Supply those values using your deployment's secret and environment management. A released image reference has the form ghcr.io/halideworks/votport:vX.Y.Z@sha256:<published-digest>. Replace both placeholders with your approved release. The local administrator password must contain at least 12 characters. An Argon2 PHC value in VOTPORT_ADMIN_PASSWORD_HASH can replace the plain password variable.

VOTPORT_PUBLIC_URL must use HTTPS outside loopback development. The service refuses an invalid public URL at startup.

HTTPS proxy

For Caddy running on the host:

drop.example.com {
    reverse_proxy 127.0.0.1:8321
}

Replace the hostname, configure its DNS, and validate/reload Caddy using your host's service management. If Caddy runs in another container, use a private container network and its service address instead of that container's loopback address.

Set VOTPORT_TRUSTED_PROXIES to the address range from which the proxy actually connects. Docker's gateway address can change when a network is recreated. The peer field on an admin_login_failed log event identifies the socket peer; ip is the interpreted client address. Verify that requests from different clients remain distinguishable after proxy configuration.

Start and verify

docker compose pull
docker compose up -d
docker compose logs --tail 100 votport
curl --fail http://127.0.0.1:8321/healthz

Open the HTTPS address and sign in. For a NAS receive root, first complete Storage > Receiving storage qualification using the direct receiving guide. Then create a test request and receive a small file. Issue a delivery for it and download it. Check the receipt and confirm that the file appeared on the intended persistent volume.

For native performance, also configure and forward the separate UDP ports for both send and receive. Publishing HTTPS alone provides browser access, not native QUIC connectivity. Follow the native networking guide and test from outside the facility.

Before onboarding users, configure sign-in, backups, monitoring, and the quotas and retention appropriate to your deployment.