Developers

Configuration reference

Every environment variable and command-line option.

Procera is configured in three places:

1. The server: command-line options and PROCERA_* environment variables, read at start-up. These are for whoever runs the installation.
2. The system console (/system): email delivery, quotas and platform floors, changed in the app by system administrators and recorded in the system audit log.
3. Workspace Settings (Admin › Settings): everything about how one workspace works, changed by its owner and admins and recorded in its audit log.

See also: Install with Docker Compose and First-time setup.

1. Server options and environment variables

The procera binary has five commands:

Every option can be given as a flag or as its environment variable; a flag wins. An empty variable counts as not set. Logs are JSON lines on standard error; standard output is reserved for command output.

procera serve

procera migrate

procera healthcheck

Database roles

Run deploy/sql/00-roles.sql once per database, as a superuser, before the first migration. It creates:

• procera_migrator: owns the schema and runs migrations. Never used by the running server.
• procera_app: the runtime role. Not an owner, no BYPASSRLS, data changes only, so row-level security always applies.
• procera_discovery: cannot log in. Owns only a few cross-workspace lookup functions that return ids.

It also creates the citext and ltree extensions. Set the two login roles' passwords yourself (the Compose stack does this from deploy/.env).

Endpoints for monitoring

Variables used by the Compose files only

deploy/compose.yml also reads these from deploy/.env. The server never sees them directly.

2. Settings in the app

System console

System administrators sign in and open System console (from Choose a workspace, or /system). Two-step verification is required. Changes are recorded in System audit.

Platform floors set the minimum every workspace must meet. A workspace can be stricter but never looser: a looser value is rejected when saved, and existing looser values are clamped and shown as Platform minimum in workspace Settings. Keys with floors today: auth.mfa.required_roles, auth.mfa.allowed_methods, auth.password.min_length, auth.password.breach_check, auth.session.idle_timeout, auth.session.absolute_timeout, auth.stepup.window, api.tokens.max_ttl, access.admin_content_access_log, retention.governance_record.keep_for, files.max_size, files.scan.required. There is no console page for floors yet: set them through the system API (GET /sysapi/v1/settings, PUT /sysapi/v1/settings/{key} with {"value": …, "reason": "…"}), signed in as a system administrator.

Workspace Settings

Workspace owners and admins open Admin › Settings. Each setting shows its effective value and where it comes from (default, profile, workspace, department or platform minimum). The categories:

Single sign-on (OpenID Connect)

In Admin › Single sign-on, copy the redirect URL (<PROCERA_PUBLIC_URL>/api/v1/auth/sso/callback) into a new OpenID Connect web application at your provider (Okta, Microsoft Entra ID, Google Workspace, Keycloak and others), then enter its issuer URL, client ID, client secret and the email domains it vouches for. Procera checks the provider's /.well-known/openid-configuration before saving. Members whose verified email is in a trusted domain can then choose Sign in with SSO; they must already be members (invite them as usual). Require it turns off passwords for everyone except workspace owners, who keep password + two-step verification so a provider outage can't lock you out. A provider on a private network must be listed in PROCERA_EGRESS_ALLOW. Decisions and limits: docs/22 A-50.

Some settings can be overridden per department. The configuration profile chosen when the workspace was created only sets the starting values. The full catalogue is in docs/20.

3. Security notes

Reverse proxy and TLS

The procera server speaks plain HTTP and does not serve the web app. Put a reverse proxy in front that:

• terminates TLS (HTTPS is required outside local trials; see cookies below);
• serves the built web app (npm run build in web/ produces web/dist) and falls back to index.html for unknown paths, because the app uses browser history routing;
• forwards /api/, /sysapi/, /healthz, /readyz and /version to the server, on the same origin as the web app;
• replaces X-Forwarded-For with the real client address. Procera trusts the first address in that header for sign-in rate limits and audit records, so a proxy that appends to a client-supplied header lets clients pick their own address. Don't expose the server port directly.

The Compose stack's web container (Caddy) does all of this. If you run your own proxy, a minimal Caddy setup:

procera.example.com {
	encode zstd gzip
	@api path /api/* /sysapi/* /healthz /readyz /version
	handle @api {
		reverse_proxy 127.0.0.1:8080
	}
	handle {
		root * /srv/procera/web/dist
		try_files {path} /index.html
		file_server
	}
}

Caddy gets the certificate automatically, and it replaces client-sent X-Forwarded-For unless you configure trusted_proxies.

A minimal nginx setup (certificates from your usual tooling):

server {
    listen 443 ssl;
    http2 on;
    server_name procera.example.com;
    ssl_certificate     /etc/ssl/procera/fullchain.pem;
    ssl_certificate_key /etc/ssl/procera/privkey.pem;

    root /srv/procera/web/dist;
    location ~ ^/(api|sysapi)/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;   # replace, don't append
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    location ~ ^/(healthz|readyz|version)$ {
        proxy_pass http://127.0.0.1:8080;
    }
    location / {
        try_files $uri /index.html;
    }
}

server {
    listen 80;
    server_name procera.example.com;
    return 301 https://$host$request_uri;
}

Set PROCERA_PUBLIC_URL=https://procera.example.com to match.

Cookies and sessions

• The refresh cookie is HttpOnly, SameSite=Strict, Secure and named with the __Host- prefix, so browsers send it only over HTTPS, only to the exact host, and never on cross-site requests. Cookie endpoints also require a custom request header, which blocks cross-site form posts.
• PROCERA_INSECURE_COOKIES=true drops Secure and the prefix so a plain-HTTP setup works. Use it only for local development and tests.
• Session length, idle timeout and the step-up window are workspace settings (Sign-in & security), bounded by platform floors.

Master key

• Generate it with procera keygen, store it in a secret manager, and back it up apart from database backups. Losing it makes the encrypted data unreadable: workspace keys, stored files, two-step secrets and the saved SMTP password.
• Don't change it on an existing installation: there is no root-key rotation command yet. Each workspace's key can be rotated with Rotate key under Admin › Encryption.
• External key management (KMS/HSM) is designed but not built yet; the key is read from the environment.

SMTP TLS modes

The saved SMTP password is encrypted under the system key and never shown again. A password in PROCERA_SMTP_URL lives wherever your environment is stored, so protect that file.

Other hardening

• The container image runs as a non-root user on a distroless base (no shell).
• Keep Postgres off the public network. The Compose stack publishes only the web container.
• Turn on ClamAV (PROCERA_CLAMD_ADDR) before people upload files.
• Keep /readyz internal if you don't want its database and cache status visible; the bundled Caddyfile forwards it.

Source: docs/guides/configuration.md