Skip to main content
This guide is the supported command-line installation path for an on-premises CaseBender deployment. It does not require public internet access after the container images have been made available in your environment.
Prefer a graphical workflow? The Desktop Installer uses the same first-run activation model.

​
Prerequisites

  • Linux, macOS, or Windows with WSL 2
  • Docker Engine 20.10+ and Docker Compose v2+
  • Node.js 20+ on the host (./casebender preflight, up, upgrade, and the canary check invoke Node; init does not)
  • OpenSSL
  • Cosign (bundle signature verification only; not required to run init or up)
  • 8 GB RAM minimum, 16 GB recommended (web, API, workers, PostgreSQL, Redis, and the bundled ClamAV scanner)
  • Ports 80 and 443 free on the host
  • For production: a DNS name and trusted TLS certificate for the CaseBender host
  • Internet access to download the public Community bundle and container images, or an approved process for mirroring the release’s exact image digests
The bundle does not include container images. ./casebender up pulls the pinned tags from the registry in release.env. If that registry requires authentication, run docker login for it before up. Do not copy credentials from this guide into an installation. CaseBender generates installation-specific secrets.

​
1. Download and verify the Community bundle

The CaseBender source repository is private and is not part of the customer installation process. The public, source-free bundle contains the production Compose definition, the casebender management command, preflight and canary checks, Nginx configuration, and pinned release metadata.

Download the latest Community on-premises bundle

Source-free Docker Compose installation bundle
Download the archive, checksum, and Sigstore verification bundle:
On macOS, use shasum -a 256 -c instead of each sha256sum -c. The signed archive contains the same release-manifest.json; compare it with the separately downloaded manifest and retain it with your deployment records. It records the exact source commit and signed digest for every container image in the release. The Community download does not currently include an offline image archive. For an air-gapped installation, mirror or export all seven exact image digests from release-manifest.json through your approved software-import process and load them into Docker or your internal registry before running ./casebender up --offline.

​
2. Initialize the installation

​
Default local volume

The first install uses local file storage. License (community or enterprise) does not change that. Initialize with no storage variables:
This writes STORAGE_PROVIDER=local, stores files on a named Docker volume at /data, and starts a bundled ClamAV scanner on the internal Compose network. An in-app banner notes that files live on this host. You can keep this after applying an enterprise license, or switch later to object storage.

​
Optional object storage

GCS uses GCS_BUCKET/GCS_PROJECT_ID with ADC. Azure uses AZURE_STORAGE_ACCOUNT/AZURE_CONTAINER with Managed Identity. A mounted STORAGE_CONFIG_FILE or inline STORAGE_CONFIG_JSON can define separate quarantine, records, and ephemeral profiles. MinIO is not a supported provider and is not embedded in Compose. Initialization:
  • reads the pinned image version and registry from the bundle’s release.env;
  • creates .env with unique authentication, database, Redis, and OpenSearch secrets while preserving the supplied storage configuration;
  • keeps secrets out of command output;
  • prepares the one-time local activation state; and
  • refuses to overwrite an existing .env or reset an installation.
Back up .env in your approved secret store. Never commit it or send it through email or chat. Then set the public HTTPS origin. init writes https://localhost, which is enough only for a local browser override. Sign-in cookies and later OAuth integrations need the real URL:
If web logs show Failed to connect to database while waiting for host db, this release is older than the Postgres service rename. Add the following to .env and to the web service environment in docker-compose.prod.yml, then run ./casebender up again:

​
3. Install TLS certificates

./casebender init already writes a temporary self-signed certificate at:
Replace those files with a certificate trusted by client devices before production use. Keep the self-signed pair only for isolated evaluation; browsers will warn until you install a trusted chain.

​
4. Run production preflight

Preflight blocks startup when installation secrets are missing or weak, Redis is unauthenticated, TLS files are absent, mutable image tags are used, the demo profile is selected, storage is missing or insecure, malware scanning is not configured, or a non-proxy service port is published. Local volume storage is the default (STORAGE_PROVIDER=local). Object-storage profiles must use canonical variables and HTTPS endpoints. Mounted storage profile files must be absolute paths, valid JSON, and inaccessible to group/other users (mode 0600).

​
5. Start CaseBender

This pulls only the pinned images identified by release.env; it does not clone or build the private source repository. If the matching images were loaded from the air-gapped archive, run:
Only Nginx ports 80 and 443 are published. PostgreSQL, Redis, OpenSearch, API, ingestion, worker, and processor services remain on the internal Compose network. Default local storage uses a named volume and bundled ClamAV on that same network. Optional object storage is customer-owned and external to the Compose stack. Monitor startup with the management command so local-storage Compose overlays are included:

​
6. Complete one-time activation

After ./casebender up reports that the installation is ready, obtain the short-lived activation code from the same host:
The code is at least 32 characters, expires after 30 minutes, allows five failed attempts, and cannot be reused after activation. Open /setup immediately:
The setup page is hosted by the on-premises instance. It does not contact a CaseBender public activation service and works in an air-gapped network. Enter the code, administrator email, display name, and a unique administrator password (at least 12 characters, with uppercase, lowercase, a digit, and a symbol). See First-run setup. If the code expires, run ./casebender activation-code again; the previous code is invalidated.
CaseBender does not create a shared production password. The legacy bootstrap mode is for temporary compatibility only and requires an explicit risk acknowledgement. Do not enable it for a new installation.

​
7. Verify the deployment

Then verify:
  • the administrator can sign in;
  • another organization cannot access its cases, alerts, tasks, attachments, or audit records;
  • API keys cannot request scopes beyond the owner’s permissions;
  • integration destinations use HTTPS and approved egress;
  • backup and restore procedures work.

​
Clean start on a new host

Use this sequence when replacing a legacy install with an empty product. It creates a new database, new encryption keys, and a new first administrator. Existing cases, users, and integrations are not imported.
  1. Leave the legacy directory untouched. Extract this bundle into a new directory so Docker Compose does not reuse the old project name or volumes.
  2. Confirm Node.js 20+ (node -v) and that ports 80 and 443 are free.
  3. ./casebender init (no storage variables for local volume + bundled ClamAV).
  4. Edit .env and set NEXTAUTH_URL, NEXTAPP_URL, and OAUTH_ALLOWED_ORIGINS to https://<your-dns>.
  5. Replace deploy/nginx/ssl/ with a trusted certificate, or accept a browser warning for evaluation only.
  6. ./casebender preflight then ./casebender up.
  7. ./casebender activation-code and open https://<your-dns>/setup.
Do not unpack over the legacy docker-compose.yml directory, and do not run ./casebender init where an existing .env or named volumes already belong to a live install. init refuses to overwrite .env; deleting that file to force init would generate new database passwords and encryption keys against any leftover volumes. If you still need the legacy data, stop and follow Migrate a Legacy Docker Compose Installation instead of this clean start.

​
Existing installations

When an existing CaseBender database is upgraded, the compatibility migration marks it ACTIVE. Existing users, passwords, roles, organizations, cases, and API keys remain unchanged. The setup page does not appear and seeding does not create or reset an administrator. Take a verified backup and follow Upgrading CaseBender before replacing images. If the current deployment uses a legacy docker-compose.yml with app, db, or embedded MinIO services, use Migrate a Legacy Docker Compose Installation instead of treating it as a routine upgrade. Preserve the existing .env, Compose project name, named volumes, attachment storage, and cryptographic keys. Never run ./casebender init against an existing installation.

​
On-premises private integrations

Outbound integrations require HTTPS and reject loopback, link-local, metadata, and private destinations by default. To permit a specific internal integration, add only its exact hostname to:
This setting is an allowlist, not a switch to permit all private networks.

​
Useful commands

Never use docker compose down -v on an installation that contains data.

​
Next steps