Full On-Premises

Overview

Full on-premises deployment runs all Navigara components in your infrastructure. Source code, analysis results, and all metadata stay within your network.

Architecture

A full deployment consists of three infrastructure components:

Linux VM: runs the Navigara application (backend, frontend, collector) via Docker Compose
Managed PostgreSQL: stores all application data including vector embeddings (requires pgvector extension)
LLM API endpoint: Anthropic, OpenAI, or Google Vertex AI API for AI-powered commit analysis
Navigara license key: JWT issued by Navigara that unlocks analysis features (see License Key)

Prerequisites

Linux VM

The VM runs all Navigara application containers via Docker Compose. Operating system: Ubuntu 24.04 LTS or Debian 13+ (other systemd-based Linux distributions may work but are not officially supported) Required software:

Docker Engine 24+
Docker Compose v2+

Managed PostgreSQL

A managed PostgreSQL instance with the pgvector extension enabled. All major cloud providers support this:

AWS: Amazon RDS for PostgreSQL with pgvector
GCP: Cloud SQL for PostgreSQL with pgvector
Azure: Azure Database for PostgreSQL with pgvector
Self-managed: PostgreSQL 18+ with pgvector extension installed

PostgreSQL version: 18 (required for native UUIDv7 support via uuidv7()) Required extension: pgvector (vector similarity search for knowledge graph analysis)

License Key

A full on-premises deployment requires a license key issued by Navigara. Contact your Navigara account representative with the domain you intend to host Navigara on (e.g. navigara.yourcompany.com) to obtain one. Set it as LICENSE_KEY in secrets/backend.env.

Treat LICENSE_KEY as a secret. Store it alongside your other credentials (vault or secret manager) and do not commit it to source control.

LLM API Endpoint

Navigara requires an LLM API endpoint for AI-powered commit analysis. Supported providers: Analysis uses two models. The knowledge agent classifies every commit and is most of the token spend, so it runs on a small fast model from LLM_MODEL_AGENT_KG. Summaries and the rest of the pipeline are low volume and run on the stronger model in LLM_MODEL. Leave LLM_MODEL_AGENT_KG unset and the knowledge agent falls back to LLM_MODEL.

Provider	`LLM_MODEL_AGENT_KG` (analysis)	`LLM_MODEL` (summaries)	Notes
Anthropic	`claude-haiku-4-5`	`claude-sonnet-5`	Recommended for the best quality/cost ratio
Google Vertex AI	`gemini-3.5-flash-lite`	`gemini-3.7-flash`	Good cost/performance ratio
OpenAI	`gpt-5.6-luna`	`gpt-5.6-terra`	Widely available

The endpoint must be reachable from the VM. For air-gapped environments, a locally hosted model with an OpenAI-compatible API (e.g. vLLM, Ollama) can be used. Contact support for guidance.

Anthropic (Recommended)
Google Vertex AI
OpenAI
Self-hosted (OpenAI-compatible)

LLM_PROVIDER=anthropic
LLM_MODEL=claude-sonnet-5
LLM_MODEL_AGENT_KG=claude-haiku-4-5
LLM_API_KEY=<your-anthropic-api-key>
LLM_API_URL=https://api.anthropic.com

LLM_API_URL is required. Claude Haiku 4.5 costs half as much per token as Claude Sonnet 5, and the knowledge agent is most of the traffic. Drop LLM_MODEL_AGENT_KG to run everything on Claude Sonnet 5 instead.For Azure AI Foundry, internal API gateways, or other Anthropic-Messages-API-compatible endpoints, set LLM_API_URL to that endpoint. Do not include /v1 in the URL; the SDK appends /v1/messages itself.

Vertex AI uses Google authentication instead of a static API key.1. Attach a workload identity with the Vertex AI User role to the deployment host.2. Set the following in the service file for each service that calls Vertex AI:

LLM_PROVIDER=genai
LLM_MODEL=gemini-3.7-flash
LLM_MODEL_AGENT_KG=gemini-3.5-flash-lite
GOOGLE_PROJECT=<your-gcp-project>
GOOGLE_LOCATION=global

3. Use a JSON key only when no workload identity is available. Create it with mode 0600 and mount it read-only into only the service that needs it. Set GOOGLE_APPLICATION_CREDENTIALS in that service file.

LLM_PROVIDER=openai
LLM_MODEL=gpt-5.6-terra
LLM_MODEL_AGENT_KG=gpt-5.6-luna
LLM_API_KEY=<your-openai-api-key>

Any model served behind an OpenAI-compatible API (e.g., vLLM, Ollama) can be used:

LLM_PROVIDER=openai
LLM_MODEL=<your-model-name>
LLM_API_KEY=<your-api-key>
LLM_API_URL=http://<your-host>:8000/v1

Your setup may not need LLM_API_KEY. Contact support for guidance on model selection.

Network Requirements

The VM must have outbound access to the following services. Ensure your firewall rules allow these connections:

Service	Purpose	Example endpoints
Git provider	Repository cloning and commit fetching	`github.com`, `gitlab.com`, or your self-hosted instance
Task management	Alignment scoring via issue/task data	`api.linear.app`, `*.atlassian.net`, or your self-hosted instance
LLM API	AI-powered commit analysis	`api.anthropic.com`, `api.openai.com`, or Vertex AI endpoints

If any of these services are unreachable, the corresponding Navigara features will not function. Git provider access is required for core functionality.

Hardware Requirements

Small (up to 500K commits)
Medium (up to 5M commits)
Large (up to 50M commits)

Suitable for small to mid-size engineering teams.

Component	CPU	Memory	Disk
Linux VM	16 vCPU	16 GB	500 GB SSD
PostgreSQL	16 vCPU	32 GB	500 GB SSD

Component	CPU	Memory	Disk
Linux VM	24 vCPU	24 GB	1 TB SSD
PostgreSQL	32 vCPU	64 GB	1 TB SSD

Component	CPU	Memory	Disk
Linux VM	48 vCPU	48 GB	2 TB SSD
PostgreSQL	64 vCPU	128 GB	2 TB SSD

Knowledge graph data and vector embeddings drive the disk requirement.

Installation

1. Prepare the VM

Install Docker from Docker’s own package repository.

Ubuntu
Debian

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Then allow your user to reach the Docker socket, and confirm the install. Log out and back in for the group change to take effect.

sudo usermod -aG docker $USER
docker compose version

Do not use the get.docker.com convenience script. Docker does not support it for production installs.

2. Verify the release

Navigara publishes, for every release, a signature, a software bill of materials (SBOM), and build provenance for each image. Verify them before you deploy. Install cosign, then verify each image at the digest you intend to run. Your account representative provides the digests for your release, and they are listed in step 5.

NAVIGARA_VERSION=0.15.7
REGISTRY=europe-docker.pkg.dev/navigara-images/public

cosign verify \
  --certificate-identity-regexp "^https://github.com/navigaracom/vision/\.github/workflows/release\.yml@refs/tags/v" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "$REGISTRY/vision-be@sha256:<backend-digest-from-step-5>"

A successful verification prints the signed claims. Repeat for vision-collector and vision-fe. Then read the provenance and the SBOM, which travel with the image:

docker buildx imagetools inspect "$REGISTRY/vision-be:$NAVIGARA_VERSION" \
  --format '{{ json .Provenance }}'

docker buildx imagetools inspect "$REGISTRY/vision-be:$NAVIGARA_VERSION" \
  --format '{{ json .SBOM }}'

Feed the SPDX SBOM to your own vulnerability scanner if your policy requires it.

If cosign verify reports no signatures found or no matching signatures, stop. Either the version you pinned predates image signing (install the current release instead), or the image is not the one Navigara published. Contact support before deploying it.

3. Configure the deployment

Create the deployment directory structure and docker-compose.yml:

mkdir -p /opt/navigara/caddy && cd /opt/navigara

This deployment is hardened by default. Keep the read_only, cap_drop, security_opt, resource limit, and network settings as written.

services:
  backend:
    image: ${BACKEND_IMAGE:?set BACKEND_IMAGE in .env to a digest-pinned reference}
    container_name: navigara-backend
    init: true
    env_file:
      - ./secrets/backend.env
    environment:
      DATABASE_MAX_CONNS: ${DATABASE_MAX_CONNS:-10}
      DATABASE_MIN_CONNS: ${DATABASE_MIN_CONNS:-2}
      GRPC_PORT: ${GRPC_PORT:-9090}
      HTTP_PORT: ${HTTP_PORT:-8080}
      LOG_LEVEL: ${LOG_LEVEL:-INFO}
      LLM_MAX_TOKENS: ${LLM_MAX_TOKENS:-8192}
      MIGRATIONS_PATH: ${MIGRATIONS_PATH:-db/migrations}
      FRONTEND_URL: https://${DOMAIN:?set DOMAIN in .env}
      PUBLIC_API_URL: https://${DOMAIN}/api
    # Uncomment for a Vertex AI service account key file
    # volumes:
    #   - ./vertex-ai-key.json:/etc/navigara/vertex-ai-key.json:ro
    read_only: true
    tmpfs:
      - /tmp:mode=1777,size=512m
    cap_drop:
      - ALL
    security_opt:
      - "no-new-privileges:true"
    deploy:
      resources:
        limits:
          cpus: "${BACKEND_CPUS:-4.0}"
          memory: ${BACKEND_MEMORY:-4g}
          pids: 512
    healthcheck:
      test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/${HTTP_PORT:-8080}"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 60s
    restart: unless-stopped
    networks:
      navigara-edge:
        priority: 100
      navigara-app:
        priority: 50
      navigara-collector:
        priority: 10

  collector:
    image: ${COLLECTOR_IMAGE:?set COLLECTOR_IMAGE in .env to a digest-pinned reference}
    container_name: navigara-collector
    init: true
    env_file:
      - ./secrets/collector.env
    environment:
      SERVER_ADDR: backend:${GRPC_PORT:-9090}
      COLLECTOR_NAME: ${COLLECTOR_NAME:-collector-1}
      MAX_WORKERS: ${COLLECTOR_MAX_WORKERS:-10}
      WORK_DIR: /tmp/git-analysis
    volumes:
      - collector-workdir:/tmp
      # Uncomment for a Vertex AI service account key file
      # - ./vertex-ai-key.json:/etc/navigara/vertex-ai-key.json:ro
    depends_on:
      backend:
        condition: service_started
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - "no-new-privileges:true"
    deploy:
      resources:
        limits:
          cpus: "${COLLECTOR_CPUS:-8.0}"
          memory: ${COLLECTOR_MEMORY:-8g}
          pids: 4096
    restart: unless-stopped
    networks:
      navigara-collector:
        priority: 100

  frontend:
    image: ${FRONTEND_IMAGE:?set FRONTEND_IMAGE in .env to a digest-pinned reference}
    container_name: navigara-frontend
    init: true
    environment:
      BACKEND_API_URL: ${BACKEND_API_URL:-http://backend:8080}
      NODE_ENV: ${NODE_ENV:-production}
    read_only: true
    tmpfs:
      - /app/.next/cache:mode=1777,size=256m
      - /tmp:mode=1777,size=64m
    cap_drop:
      - ALL
    security_opt:
      - "no-new-privileges:true"
    deploy:
      resources:
        limits:
          cpus: "${FRONTEND_CPUS:-2.0}"
          memory: ${FRONTEND_MEMORY:-1g}
          pids: 256
    depends_on:
      - backend
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3000"]
      interval: 15s
      timeout: 5s
      retries: 3
      start_period: 15s
    restart: unless-stopped
    networks:
      navigara-edge:
        priority: 100
      navigara-app:
        priority: 50

  caddy:
    image: ${CADDY_IMAGE:?set CADDY_IMAGE in .env to a digest-pinned reference}
    container_name: navigara-caddy
    init: true
    environment:
      DOMAIN: ${DOMAIN:?set DOMAIN in .env}
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    read_only: true
    tmpfs:
      - /tmp:mode=1777,size=64m
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    security_opt:
      - "no-new-privileges:true"
    deploy:
      resources:
        limits:
          cpus: "${CADDY_CPUS:-1.0}"
          memory: ${CADDY_MEMORY:-256m}
          pids: 128
    depends_on:
      - frontend
    restart: unless-stopped
    networks:
      navigara-edge:
        priority: 100

volumes:
  collector-workdir:
    name: navigara-collector-workdir
  caddy-data:
    name: navigara-caddy-data
  caddy-config:
    name: navigara-caddy-config

networks:
  navigara-edge:
    name: navigara-edge
    driver: bridge

  navigara-app:
    name: navigara-app
    driver: bridge
    internal: true

  navigara-collector:
    name: navigara-collector
    driver: bridge

The collector is attached to navigara-collector only, so it cannot reach Caddy or the frontend. A self-hosted database belongs on navigara-app.

4. Generate Root Private Key

Generate an Ed25519 key pair for admin root access. You will use the private key to generate login links in Product Setup.

PRIVKEY_PEM=$(openssl genpkey -algorithm Ed25519)
PUBKEY=$(echo "$PRIVKEY_PEM" | openssl pkey -pubout -outform DER | tail -c 32 | base64)
SEED=$(echo "$PRIVKEY_PEM" | openssl pkey -outform DER | tail -c 32 | base64)
umask 077
printf -- "-----BEGIN PRIVATE KEY-----\n%s\n-----END PRIVATE KEY-----\n" "$SEED" > admin_key.pem
chmod 0600 admin_key.pem
echo "Public key (use below): $PUBKEY"
echo "Private key saved to: admin_key.pem"

The admin_key.pem file is a root credential for your Navigara instance. Store it in a vault or password manager, and restrict access to named administrators.

5. Prepare Environment Files

Use .env only for non-secret Compose settings. Use a separate 0600 file for each service. Do not mount a secret file in the frontend.

File	Service	Minimum values
`.env`	Compose only	`NAVIGARA_VERSION`, `DOMAIN`, and optional image overrides
`secrets/backend.env`	Backend only	`DATABASE_URL`, `LICENSE_KEY`, `ADMIN_PUBLIC_KEY`, `COLLECTOR_API_KEY`, `PAGINATION_TOKEN_SECRET`, and enabled authentication, email, or LLM values
`secrets/collector.env`	Collector only	`COLLECTOR_API_KEY`, `LLM_PROVIDER`, `LLM_MODEL`, and the LLM credential or workload identity configuration
No file	Frontend	No secrets. Compose provides only `BACKEND_API_URL` and `NODE_ENV`.

Create the public Compose file. Pin every image by digest. Verify each digest as described in step 2 before you start the stack.

cat > .env <<'EOF'
NAVIGARA_VERSION=0.15.7
DOMAIN=navigara.yourcompany.com

BACKEND_IMAGE=europe-docker.pkg.dev/navigara-images/public/vision-be:0.15.7@sha256:551bd1c2ddd78a5497ceaf40fcb50de806ecc89e6d7bbf1719c47e22d04173de
COLLECTOR_IMAGE=europe-docker.pkg.dev/navigara-images/public/vision-collector:0.15.7@sha256:189a4d44ace2dbb15cb16795a5dc9e0e1597aaaf4a039b199fab4226d44e1849
FRONTEND_IMAGE=europe-docker.pkg.dev/navigara-images/public/vision-fe:0.15.7@sha256:6edbbeb6cde3d25f80ad870a8804bf5d1cbba5ca1874e1e242e57cca6ed56d96
CADDY_IMAGE=docker.io/library/caddy:2.11.4-alpine@sha256:5f5c8640aae01df9654968d946d8f1a56c497f1dd5c5cda4cf95ab7c14d58648

# BACKEND_CPUS=4.0
# BACKEND_MEMORY=4g
# COLLECTOR_CPUS=8.0
# COLLECTOR_MEMORY=8g
# FRONTEND_CPUS=2.0
# FRONTEND_MEMORY=1g
# CADDY_CPUS=1.0
# CADDY_MEMORY=256m
EOF

These digests are for 0.15.7. Your account representative provides the digests for every release. The commented resource limits match the Small hardware tier; raise them when you move to a larger tier. Create the secret files from your secret manager. Set restrictive permissions before writing them. Do not put a literal token in a shell command or shell history.

install -d -m 0700 secrets
install -m 0600 /dev/null secrets/backend.env
install -m 0600 /dev/null secrets/collector.env

The backend file needs this minimum configuration. Add optional values only for enabled features.

DATABASE_URL=postgresql://navigara:***@<postgres-host>:5432/navigara?sslmode=require
LICENSE_KEY=<read-from-secret-manager>
ADMIN_PUBLIC_KEY=<public-key-from-step-4>
COLLECTOR_API_KEY=<read-from-secret-manager>
PAGINATION_TOKEN_SECRET=<generated-unique-secret>
# LLM_PROVIDER=anthropic
# LLM_MODEL=claude-sonnet-5
# LLM_MODEL_AGENT_KG=claude-haiku-4-5
# LLM_API_KEY=<read-from-secret-manager>
# ENABLE_PASSWORD_AUTH=true
# PASSWORD_HASH_PEPPER=<random-string-of-32-bytes-or-more>
# GOOGLE_CLIENT_ID=<google-client-id>
# GOOGLE_CLIENT_SECRET=<read-from-secret-manager>
# MICROSOFT_CLIENT_ID=<microsoft-client-id>
# MICROSOFT_CLIENT_SECRET=<read-from-secret-manager>
# SMTP_HOST=smtp.your-provider.com
# SMTP_USERNAME=<smtp-user>
# SMTP_PASSWORD=<read-from-secret-manager>

With password auth you must also set PASSWORD_HASH_PEPPER to 32 bytes or more. The backend refuses to start without it, and you cannot rotate it. Generate PAGINATION_TOKEN_SECRET once with your secret manager and set it. Without it, the backend starts on a shared default value and only logs a warning, so your own checks must catch its absence. Use the same generated COLLECTOR_API_KEY value in secrets/backend.env and secrets/collector.env. The collector file contains only its connection and LLM configuration:

COLLECTOR_API_KEY=<same-value-from-secret-manager>
LLM_PROVIDER=anthropic
LLM_MODEL=claude-sonnet-5
LLM_MODEL_AGENT_KG=claude-haiku-4-5
LLM_API_KEY=<read-from-secret-manager>
# COLLECTOR_PRIVATE_KEY_PATH=/etc/navigara/keys/private.pem

Prefer an attached workload identity for Vertex AI. Do not use a static service-account JSON key. If no workload identity is available, mount a 0600 key file read-only into only the service that requires it.

At least one authentication method must be configured for users to log in to Navigara. Enable one or more of: password auth (ENABLE_PASSWORD_AUTH=true), Google OAuth (GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET), or Microsoft OAuth (MICROSOFT_CLIENT_ID + MICROSOFT_CLIENT_SECRET). Without at least one of these, only the root admin can access the instance via Product Setup.On 0.14.6 and earlier, configure OAuth. The invitation page offers only a sign-in form. An invited user who has no account cannot create one, so OAuth is the only way in. Later releases accept password signup from the invitation link.

Email (SMTP)

Navigara sends transactional email over SMTP: password resets, organization invitations, and the workspace-ready welcome message. Use any provider: Amazon SES, SendGrid, Postmark, Mailgun, Google Workspace, or an internal relay. Set SMTP_HOST, SMTP_USERNAME, and SMTP_PASSWORD. SMTP_PORT defaults to 587 (STARTTLS) and SMTP_FROM defaults to SMTP_USERNAME. For an IP-allowlisted internal relay that needs no credentials, set SMTP_HOST and leave the username and password empty. Use SMTP_TLS=ssl with SMTP_PORT=465 for providers that require implicit TLS.

Email is optional. Without SMTP_HOST, Navigara runs normally but sends no email. Password resets and invitations are not delivered, so you need an authentication method that does not depend on email: OAuth/SSO, or sharing the invitation link directly.

6. Configure PostgreSQL

Connect to your PostgreSQL instance as its administrative user and run the following. On a managed service that user is postgres on Cloud SQL, the master user on RDS, or your Azure administrator login.

CREATE DATABASE navigara;
CREATE USER navigara WITH PASSWORD '<strong-password>';

\c navigara

CREATE EXTENSION IF NOT EXISTS vector;

GRANT CONNECT, CREATE, TEMPORARY ON DATABASE navigara TO navigara;
GRANT CREATE, USAGE ON SCHEMA public TO navigara;
GRANT SELECT, INSERT, UPDATE, DELETE, REFERENCES, TRIGGER, TRUNCATE ON ALL TABLES IN SCHEMA public TO navigara;
GRANT SELECT, UPDATE, USAGE ON ALL SEQUENCES IN SCHEMA public TO navigara;

Then set DATABASE_URL in secrets/backend.env to use the navigara user:

DATABASE_URL=postgresql://navigara:<password>@<postgres-host>:5432/navigara?sslmode=require

Navigara runs database migrations automatically on startup; no manual schema setup is needed.

7. Configure Reverse Proxy (Caddy)

Navigara ships with Caddy as the reverse proxy. Caddy terminates TLS, provisions and renews certificates through Let’s Encrypt, and routes between the frontend, the backend API, and the gRPC services. Create the Caddyfile at caddy/Caddyfile. The site address comes from DOMAIN in your .env:

{$DOMAIN} {
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Frame-Options "SAMEORIGIN"
        X-Content-Type-Options "nosniff"
        X-XSS-Protection "1; mode=block"
        Referrer-Policy "strict-origin-when-cross-origin"
    }

    handle /api/metrics {
        respond 404
    }

    handle /api/debug/* {
        respond 404
    }

    handle_path /api/* {
        encode gzip

        header {
            Access-Control-Allow-Origin "https://{$DOMAIN}"
            Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
            Access-Control-Allow-Headers "Authorization, Content-Type, X-Api-Key"
            Access-Control-Max-Age "86400"
        }

        @options method OPTIONS
        respond @options 204

        reverse_proxy backend:8080
    }

    handle {
        encode gzip
        reverse_proxy frontend:3000
    }

    log {
        output stdout
        format json
    }
}

The /api/metrics and /api/debug/* routes are unauthenticated, so this Caddyfile returns 404 for both. Never expose them publicly.

8. Start Navigara

docker compose pull
docker compose up -d

Verify all services are running:

docker compose ps

Confirm the containment controls took effect. Each application container must run as user 1001 and hold no Linux capabilities:

for c in navigara-backend navigara-collector navigara-frontend; do
  printf '%s uid=%s caps=%s\n' "$c" \
    "$(docker exec "$c" id -u)" \
    "$(docker exec "$c" grep -m1 CapEff /proc/self/status | awk '{print $2}')"
done

Expect uid=1001 and caps=0000000000000000 for all three. Caddy runs with CAP_NET_BIND_SERVICE alone (0000000000000400), so it can bind ports 80 and 443. Only the reverse proxy should publish a host port:

docker ps --format '{{.Names}}\t{{.Ports}}'

9. Product Setup

Log in as root to create the first organization and invite users. Use the admin_key.pem you generated in step 4. Generate a Root Login The Python script below signs a one-time credential and hands it to your browser from a local page. The credential expires 60 seconds after it is signed and works only once. Requirements: PyJWT and cryptography, in a virtual environment. Ubuntu 24.04 and other modern distributions refuse pip install into the system Python. Debian and Ubuntu also need the python3-venv package.

python3 -m venv ~/.navigara-admin
~/.navigara-admin/bin/pip install PyJWT cryptography

Run the script below with ~/.navigara-admin/bin/python in place of python3.

#!/usr/bin/env python3
"""Generate a one-time root login for Navigara (on-prem)."""
import argparse, base64, http.server, secrets, threading, time, webbrowser
import jwt
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives import serialization

parser = argparse.ArgumentParser()
parser.add_argument("--key", required=True, help="Path to Ed25519 private key PEM file")
parser.add_argument("--domain", required=True, help="Your Navigara domain (e.g. navigara.yourcompany.com)")
args = parser.parse_args()

with open(args.key) as f:
    lines = [l.strip() for l in f if not l.startswith("-----")]
seed = base64.b64decode("".join(lines))
key = Ed25519PrivateKey.from_private_bytes(seed)
pem = key.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, serialization.NoEncryption())

host = args.domain.split(":")[0]
now = int(time.time())
token = jwt.encode({
    "jti": secrets.token_hex(16),
    "iss": "deployment-admin",
    "sub": "root",
    "aud": [host],
    "typ": "navigara.support.access.v1",
    "iat": now,
    "nbf": now,
    "exp": now + 60,
}, pem, algorithm="EdDSA")

target = f"https://{args.domain}/impersonate"
page = f"""<!doctype html><html><head><meta charset="utf-8">
<meta name="referrer" content="no-referrer"><title>Signing in to Navigara</title></head>
<body><form id="f" method="POST" action="{target}">
<input type="hidden" name="token" value="{token}">
<noscript><button type="submit">Continue to Navigara</button></noscript>
</form><script>document.getElementById("f").submit();</script></body></html>""".encode()

path = "/" + secrets.token_hex(16)
served = threading.Event()

class Handoff(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path != path or served.is_set():
            self.send_error(404)
            return
        served.set()
        self.send_response(200)
        self.send_header("Content-Type", "text/html; charset=utf-8")
        self.send_header("Cache-Control", "no-store")
        self.send_header("Referrer-Policy", "no-referrer")
        self.send_header("Content-Length", str(len(page)))
        self.end_headers()
        self.wfile.write(page)

    def log_message(self, *a):
        pass

server = http.server.HTTPServer(("127.0.0.1", 0), Handoff)
url = f"http://127.0.0.1:{server.server_port}{path}"
print(f"Signing in to {target}. If no browser opens, visit {url} within 60 seconds.")
threading.Thread(target=server.serve_forever, daemon=True).start()
webbrowser.open(url)
if not served.wait(60):
    raise SystemExit("credential expired before the browser collected it")
time.sleep(1)

Save this as impersonate.py and run it on the workstation that holds the private key, not on the server:

~/.navigara-admin/bin/python impersonate.py --key admin_key.pem --domain navigara.yourcompany.com

Your browser opens on the platform administration page, signed in as the root admin. Create your first organization and invite users. Root belongs to no organization and has no dashboard of its own.

Re-run the script whenever you need root access. Every run signs a new credential. A spent or expired credential cannot be reused.

Upgrading from 0.14.1 or earlier? Replace any older copy of this script. An older copy fails with “Sign-in links are no longer accepted” or “invalid or expired credential”.

A root session lasts 15 minutes, and signing in again ends the previous root session.

Backup and Restore

Database backup

Back up your PostgreSQL database regularly using pg_dump:

pg_dump -h <postgres-host> -U navigara -d navigara -Fc > navigara_backup_$(date +%Y%m%d).dump

Database restore

pg_restore -h <postgres-host> -U navigara -d navigara --clean navigara_backup.dump

The database contains all application state. Ensure backups are stored securely and tested regularly.

Monitoring and Health Checks

The backend exposes a health check endpoint. The application containers publish no host port, so reach it through the proxy:

Endpoint	Description
`GET https://<your-domain>/api/health`	Application and database health (returns gRPC health status)

The backend and frontend containers also carry a Compose health check, so docker compose ps reports their status locally. Use these with your monitoring system (Prometheus, Datadog, etc.) to track service availability.

Prometheus metrics stay on the container network. The proxy returns 404 for /api/metrics, because that route is unauthenticated. Scrape it from a container attached to navigara-edge, not from the host.

Upgrades

An upgrade is a change to the digests in your .env. Verify the new release before you run it, exactly as you did at install.

Back up the database. Migrations run automatically on startup.

pg_dump -h <postgres-host> -U navigara -d navigara -Fc > navigara_pre_upgrade.dump

Verify the new release, as in step 2.

cosign verify \
  --certificate-identity-regexp "^https://github.com/navigaracom/vision/\.github/workflows/release\.yml@refs/tags/v" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  "europe-docker.pkg.dev/navigara-images/public/vision-be@sha256:<new-digest>"

Update NAVIGARA_VERSION and all three image digests in .env, then restart.
cd /opt/navigara docker compose pull docker compose up -d

Your account representative provides the digests for each release. This page carries the digests for the current one.

Change the version and all three Navigara digests together. A digest left on the previous release silently keeps that component on the old image, and mixed versions are not supported.

Rolling back

Keep the previous release’s digests. A roll-back is the same procedure with the old values. Restore the database backup first if the newer release ran a migration; migrations do not run in reverse.

Emergency security releases

Navigara treats two classes of finding as emergencies. We ship a release for them on this clock, from the time we confirm the finding:

Class	Navigara publishes a release within	You should deploy within
A vulnerability under active exploitation, in Navigara or a component we ship	48 hours	72 hours of the release
A credential compromise affecting Navigara-issued material (signing keys, license keys, or registry credentials)	24 hours	24 hours of the release

We notify the technical contact on your account directly for both classes. For a credential compromise, also follow the instructions in the notice. It names what to rotate on your side and, if a signing key is involved, the new identity your cosign verify must expect. Always verify the image during a key-compromise event. All other findings follow the remediation targets in Security best practices → Updates and patching.

Troubleshooting

Issue	Solution
Analysis or collector features disabled	Verify `LICENSE_KEY` is set and matches your `DOMAIN`. Contact Navigara if your license has expired or needs to be reissued.
Database connection refused	Verify `DATABASE_URL` and that the PostgreSQL instance allows connections from the VM’s IP
pgvector extension missing	Run `CREATE EXTENSION IF NOT EXISTS vector;` on the database as its administrative user
LLM analysis failing	Verify `LLM_API_KEY` and that the VM can reach the LLM API endpoint
High disk usage	Check knowledge graph data growth; consider scaling to a larger instance tier
Migrations stuck	Clear the advisory locks against the database directly: `psql "$DATABASE_URL" -c "SELECT pg_advisory_unlock_all();"`, then restart the backend
`cosign verify` reports `no signatures found` or `no matching signatures`	The version you pinned predates image signing, or the image is not the one Navigara published. Install the current release; if that also fails, contact support before deploying.
A container restarts with a read-only filesystem error	The image needs a writable path this Compose file does not grant. Report it; do not remove `read_only`. Add a `tmpfs` entry for that path as a temporary measure.
Backend or frontend unreachable on `127.0.0.1`	Expected. Only the reverse proxy publishes host ports; reach the application through your domain.

Getting Started

Concepts

Integrations

Security

Deployment

Overview

Architecture

Prerequisites

Linux VM

Managed PostgreSQL

License Key

LLM API Endpoint

Network Requirements

Hardware Requirements

Installation

1. Prepare the VM

2. Verify the release

3. Configure the deployment

4. Generate Root Private Key

5. Prepare Environment Files

Email (SMTP)

6. Configure PostgreSQL

7. Configure Reverse Proxy (Caddy)

8. Start Navigara

9. Product Setup

Backup and Restore

Database backup

Database restore

Monitoring and Health Checks

Upgrades

Rolling back

Emergency security releases

Troubleshooting

​Overview

​Architecture

​Prerequisites

​Linux VM

​Managed PostgreSQL

​License Key

​LLM API Endpoint

​Network Requirements

​Hardware Requirements

​Installation

​1. Prepare the VM

​2. Verify the release

​3. Configure the deployment

​4. Generate Root Private Key

​5. Prepare Environment Files

​Email (SMTP)

​6. Configure PostgreSQL

​7. Configure Reverse Proxy (Caddy)

​8. Start Navigara

​9. Product Setup

​Backup and Restore

​Database backup

​Database restore

​Monitoring and Health Checks

​Upgrades

​Rolling back

​Emergency security releases

​Troubleshooting

Overview

Architecture

Prerequisites

Linux VM

Managed PostgreSQL

License Key

LLM API Endpoint

Network Requirements

Hardware Requirements

Installation

1. Prepare the VM

2. Verify the release

3. Configure the deployment

4. Generate Root Private Key

5. Prepare Environment Files

Email (SMTP)

6. Configure PostgreSQL

7. Configure Reverse Proxy (Caddy)

8. Start Navigara

9. Product Setup

Backup and Restore

Database backup

Database restore

Monitoring and Health Checks

Upgrades

Rolling back

Emergency security releases

Troubleshooting