Skip to content

Self-host with Docker ​

The whole web app ​

The web app (workspaces, sending, templates, bulk send, webhooks, the signing page and these docs) runs with Docker Compose next to PostgreSQL, behind Traefik:

sh
git clone https://github.com/codevibe-technology/codevibe-sign.git
cd codevibe-sign/deploy
cp .env.example .env    # host name, Traefik, database, secrets, SMTP; PLAN_MODE=self-hosted
docker compose up -d --build

Before the first start, create the seal certificate as described in the deployment runbook, which also covers DNS, backups, a restore drill and upgrades.

The HTTP API on its own ​

apps/server builds a Docker image of the standalone service. It reads all of its configuration from environment variables, migrates the PostgreSQL database on start and stores files in a volume.

Build and run ​

From the repository root:

sh
docker build -f apps/server/Dockerfile -t codevibe-sign .
docker run -d --name sign -p 3000:3000 --env-file sign.env -v sign-data:/data codevibe-sign

The image runs as the unprivileged node user, stores files under /data and checks GET /health every 30 seconds. Put it behind a reverse proxy that terminates TLS.

Environment ​

VariableRequiredDefaultNotes
DATABASE_URLyesPostgreSQL, postgres:// or postgresql://.
PUBLIC_URLyesBase URL used in signing links. https, or http for localhost only.
API_KEYSyesComma-separated keys for your backend, each at least 32 characters.
SEAL_P12_BASE64yesYour sealing certificate and key as a base64 PKCS#12 file.
SEAL_P12_PASSPHRASEyesMay be empty, but must be set.
SMTP_HOSTyes
SMTP_FROMyesFor example Sign <sign@example.com>.
SMTP_PORTno587
SMTP_SECUREnoport is 465true for implicit TLS.
SMTP_USER, SMTP_PASSnoSet both or neither.
FILES_DIRno/data/filesWhere documents and sealed files are stored.
SEAL_REASONnoReason written into the PDF seal.
SEAL_LOCATIONnoLocation written into the PDF seal.
TICK_INTERVAL_SECONDSno60How often reminders, expiry and retries run (5 to 3600).
TRUST_PROXYnofalsetrue to read client IPs from X-Forwarded-For behind your proxy.
TRUSTED_PROXY_HOPSno1Proxies in front of the server; the client IP is that many entries from the right of X-Forwarded-For.
PORT, HOSTno3000, 0.0.0.0

All problems are reported together at start-up, by variable name only. Values are never printed.

A minimal sign.env:

sh
DATABASE_URL=postgres://sign:secret@db:5432/sign
PUBLIC_URL=https://sign.example.com
API_KEYS=replace-with-a-random-key-of-at-least-32-characters
SEAL_P12_BASE64=MIIK...
SEAL_P12_PASSPHRASE=
SMTP_HOST=smtp.example.com
SMTP_FROM=Sign <sign@example.com>

To turn a .p12 file into the base64 value: base64 -i seal.p12 | tr -d '\n'.

Operating it ​

  • Back up the PostgreSQL database and the files volume together. The audit log lives in the database and refers to files by key.
  • Keep the PKCS#12 file and its passphrase out of version control and logs. Anyone with the key can seal files in your name.
  • The service stops accepting requests, finishes in-flight requests and background jobs and closes its database connections on SIGTERM and SIGINT, so rolling restarts are safe.
  • Behind a reverse proxy, set TRUST_PROXY=true so rate limits and the audit log see the client's address rather than the proxy's.

Libraries under Apache-2.0, server and apps under AGPL-3.0. "Codevibe", "Codevibe Sign" and "Hrvibe" are trademarks of Codevibe Technology and are not covered by the licences.