Self-Hosted Deployment

A self-hosted deployment runs the same product as the cloud service, in a Docker Compose stack on servers you control. Your users still sign in through the portal, and the stack checks in with the portal for licensing. Boards, sources, chat, and the database stay inside your network.

Important

Self-hosting is available on the Enterprise plan. Once your organization is on Enterprise, our team provisions and approves an on-premises deployment for it. The approval unlocks the Self-hosted page in the portal and lets your servers pull images.

How it works

The container images live in a private registry. Once running, the stack keeps working for up to 24 hours if the portal is unreachable.

Expand

If the subscription lapses, running containers keep running, but the portal refuses the next registry sign-in and you can't pull a new release until billing is resolved.

What you'll need

The images target linux/amd64. Docker Desktop on Apple Silicon runs them under emulation, which works for evaluation. Linux ARM64 servers are not supported.

Important

You bring your own PostgreSQL: the compose file doesn't run a database. Before you start the stack, prepare a reachable managed or self-run instance and its credentials.

Outbound access

The host needs HTTPS (port 443) to all three of these. A firewall that allows the first two and blocks the third makes a pull stall at 0%.

Get your deployment credentials

1. Our team provisions an on-premises deployment for your organization and approves it. Until then, the portal's Self-hosted page shows a contact card instead of the installer.
2. Sign in to portal.provenmap.com as an organization admin and open Self-hosted.
3. Select Create secret. Copy the App ID and the secret into your secrets manager.

Warning

The page shows the secret once. Recreate secret on the same page invalidates the old one for both the heartbeat and registry sign-in. After recreating it, update .env and run the sign-in script again.

Install

Installing takes about ten minutes on a host that meets the requirements.

When your deployment is approved, our team sends you the install kit: the compose file, nginx.conf, .env.template, the sign-in scripts, and the pre-flight script.

Linux / macOSWindows

1. Unpack the kit. Put its files in ~/provenmap.

BASHCopy

cd ~/provenmap

2. Check the host. The script verifies Docker, memory, disk, port 80, jq, and whether all three outbound hosts are reachable.

BASHCopy

bash preflight.sh

3. Configure. Copy the template, then set the three required values.

BASHCopy

cp -n .env.template .env
nano .env

BASHCopy

PMAP_APP_ID=cd_your_app_id
PMAP_APP_SECRET=ck_live_your_secret
PMAP_DATABASE_PASSWORD=YourSecurePassword123!
PMAP_DATABASE_HOST=db.internal.example.com

4. Sign in to the image registry. The script exchanges your credentials for 12 hours of pull access and, on first run, pins PMAP_VERSION to the current release.

BASHCopy

./registry-login.sh

TEXTCopy

  ok      Signed in to 833239388352.dkr.ecr.us-east-1.amazonaws.com
  ok      Pull access until 2026-09-02T21:14:09.000Z
  ok      Pinned PMAP_VERSION=1.4.8 in .env

5. Start the stack.

BASHCopy

docker compose -f docker-compose.production.yml pull
docker compose -f docker-compose.production.yml up -d

The first start downloads roughly 1 GB of images and takes two to three minutes.

Tip

Pull access lasts 12 hours. Run the sign-in script again before any docker compose pull. Starting or restarting containers you already have does not need it.

Verify the installation

docker compose -f docker-compose.production.yml ps
curl http://localhost/health
curl http://localhost/api/status

All three containers (provenmap-proxy, provenmap-web, and provenmap-server) report Up (healthy). The health check returns {"status":"ok"}, and the status endpoint reports "license": { "status": "active" } after the server checks in with the portal.

Open http://localhost (or your configured port), select Sign In, and sign in with your portal account. Every user needs a portal account and membership in your organization.

Configuration

Settings live in .env next to the compose file. Restart the affected container after a change: docker compose -f docker-compose.production.yml up -d --force-recreate server.

Required

There is no latest tag. Releases are immutable, and your deployment runs exactly the release named here until you change it.

Database

The server runs migrations automatically when it starts. They are forward-only and hold an advisory lock, so several restarts in a row are safe.

Optional

Chat and in-app insight generation use a model provider, connected once from Settings → Connectors. Plugin commands such as /analyze, /sync, and /insights do not require one.

You can move icon storage from the local filesystem to S3; see Organization Settings. Plugins and MCP clients point at your instance with PMAP_BASE_URL and PMAP_MCP_URL; see Authentication.

Note

On request, we provide trial credits for early usage before you connect your own model provider. We bill them to you, not your users.

Upgrade and roll back

The Self-hosted page in the portal shows the current release and whether your deployment is up to date. To upgrade, change PMAP_VERSION in .env:

cd ~/provenmap
./registry-login.sh        # prints "Release 1.4.9 is available; you are pinned to 1.4.8"
nano .env                  # PMAP_VERSION=1.4.9
docker compose -f docker-compose.production.yml pull
docker compose -f docker-compose.production.yml up -d

Back up the database first (below). Expect one to two minutes of downtime while containers restart.

To roll back, set PMAP_VERSION to the previous release and run the same pull and start. Database migrations don't roll back. If a release's migration fails, restore your pre-upgrade backup, pin the previous release, and contact us.

Note

We keep recent releases in the registry, not every release ever shipped. If your deployment is pinned to a release that has aged out, you can't pull it onto a new host. Upgrade before you migrate hosts, or contact support.

Back up

Two things hold state: your PostgreSQL database and the provenmap-data volume (sessions, cache, and the cached license).

Back the database up with your usual PostgreSQL process. From the host:

pg_dump -h db.internal.example.com -U provenmap provenmap | gzip > backups/db-$(date +%Y%m%d).sql.gz

Back the data volume up as a tar archive:

docker run --rm -v provenmap-data:/data -v "$(pwd)/backups:/backup" \
  alpine tar czf /backup/data-$(date +%Y%m%d).tar.gz /data

If you lose the data volume, the stack rebuilds it from the portal on the next start. Nothing rebuilds the database, so back it up daily and before every upgrade.

SSL and reverse proxies

The stack includes an nginx container on port 80. You have two options for HTTPS:

• Terminate TLS on your load balancer and forward to port 80. Nothing in the stack changes.
• Replace nginx.conf with your own configuration, or route straight to the containers from your existing proxy (Traefik, Caddy, HAProxy). Use this routing table:

Keep ports 3000 and 3001 off the public internet; only the proxy should reach them.

Troubleshooting

./registry-login.sh
docker compose -f docker-compose.production.yml pull

docker compose -f docker-compose.production.yml up -d --force-recreate server

curl -sI --max-time 10 https://s3.us-east-1.amazonaws.com/ | head -1

docker compose -f docker-compose.production.yml exec server \
  node -e "fetch(process.env.PMAP_PORTAL_URL + '/platform/health').then(r => console.log(r.status))"

What's next