Documentation index

On-Premise Installation

Deployment Models

  1. Container stack - Workbench, PostgreSQL, and the reverse proxy run with Docker Compose. Use this for evaluation or approved smaller deployments where single-host availability is acceptable.
  2. Customer-managed PostgreSQL - The customer database team operates PostgreSQL, encryption, backup, monitoring, and high availability. The Workbench and reverse proxy run separately.

Supported Baseline

Use only vendor-supported components. The authorized release notes take precedence over this guide.

ComponentCustomer baseline
Host OSSupported Ubuntu LTS, Debian, RHEL, or Amazon Linux release receiving security updates
Container runtimeCurrent supported Docker Engine and Docker Compose plugin from the official repository
PostgreSQLPostgreSQL 17.10+ or 18.4+ on a supported minor release
Application runtimeSupplied container with Node.js 24 LTS
TLSCustomer-controlled RSA 4096-bit certificate and private key; TLS 1.2 or newer
BrowserCurrent managed Chrome, Edge, Firefox, or Safari

Obtain and Verify the Authorized Release

  1. Complete onboarding in the Project X IT client portal.
  2. Obtain the versioned package or container-registry entitlement, release manifest, hashes, image digest, release notes, and SBOM artifacts.
  3. Verify the package hash and container digest before extracting or pulling the release.
  4. Review the SBOM and release notes under the customer software-acceptance process.
  5. Store the release artifacts in an approved internal repository.

Do not substitute the tag latest, an unversioned archive, or an image from an unapproved registry.

Network Flows

SourceDestinationPurpose
Managed user networksWorkbench TCP 443Authenticated portal access
WorkbenchCustomer PostgreSQL TCP 5432Encrypted database connection
WorkbenchApproved identity, ERP, scanner, and cloud APIs TCP 443Read-only connectors selected by the customer
CollectorsWorkbench TCP 443Token-authenticated evidence upload
WorkbenchApproved SMTP relayAccount recovery and notifications
Customer administratorsProject X IT account portal TCP 443Hosted billing, license request, and renewal

Block direct Internet access to PostgreSQL. Restrict connector egress to approved provider endpoints.

Secrets and Certificates

  1. Generate a unique database password with at least 32 random characters.
  2. Generate ZTBIA_TENANT_RECOVERY_SECRET from at least 32 random bytes.
  3. Store secrets in a customer-approved secrets manager or root-restricted file.
  4. Install the RSA 4096-bit certificate as deployment/tls/server.crt.
  5. Install the matching private key as deployment/tls/server.key.
  6. Restrict private-key and license-file access to the service account.
  7. Never commit .env, license.json, database passwords, or private keys.

License Registration

  1. Sign in to the Project X IT client portal.
  2. Open Billing and select an enabled provider.
  3. Complete checkout on the provider-hosted page.
  4. Wait for the server-confirmed payment result.
  5. Request the 30-day trial or contracted license.
  6. Save the downloaded file as config/license.json.
  7. Mount the file read-only at /run/secrets/projectxit-workbench-license.json.

Customer evidence and payment credentials are not sent through the licensing exchange.

Container Stack

cd deployment
cp .env.example .env
# Replace every placeholder and pin the authorized release version or digest.
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 app

Open the configured WORKBENCH_PUBLIC_ORIGIN, create the first local owner through the protected setup flow, enroll MFA, and complete the acceptance checklist before enabling imports.

Customer-Managed PostgreSQL

  1. Provision PostgreSQL in the customer database platform.
  2. Enable encryption at rest with customer-controlled keys where available.
  3. Create a privileged schema-setup role and a separate least-privilege runtime role.
  4. Apply the SQL files in numeric order.

Windows:

.\scripts\apply_schema.ps1 -DatabaseUrl "postgresql://setup_user:password@db.example.com:5432/projectxit_workbench"

Linux:

./scripts/apply_schema.sh "postgresql://setup_user:password@db.example.com:5432/projectxit_workbench"
  1. Configure DATABASE_URL for the runtime role and require encrypted transport.
  2. Start the external-database stack:
docker compose -f docker-compose.external-db.yml config
docker compose -f docker-compose.external-db.yml pull
docker compose -f docker-compose.external-db.yml up -d

Acceptance Checklist Before Real Data