Deploy a persistent instance

A persistent SMART Flint instance combines the service, PostgreSQL, a master encryption key, an externally reachable HTTPS origin, and a selected administrative authentication mode. The guided Docker installer is the most direct path. An explicit repository Compose setup is available for operators who manage their own reverse proxy and deployment configuration.

Version 0.1 requires deployment-specific security review and real vendor/customer verification before handling live clinical data. A working synthetic launch or a successful installation is separate evidence from a qualified real EHR integration.

Option A: guided Docker deployment

Download the source and satisfy the installer prerequisites, then run:

bash ./install.sh

On Windows use .\install.ps1. Choose Deploy SMART Flint. Select local username/password accounts or organization OIDC sign-in, then choose one HTTPS arrangement:

Arrangement	What you supply	What the installer does
Existing HTTPS proxy (external)	A real HTTPS origin and a reverse proxy forwarding to the loopback backend	Generates the private installation, starts service/database, checks internal readiness and public HTTPS separately
Automatic HTTPS (caddy)	Public DNS pointing to the host and inbound ports 80/443	Configures Caddy certificate issuance/renewal and preserves its state

The installer does not create DNS records, open firewall/router ports, install Docker, or change system certificate trust. Caddy mode is for a real public hostname, not localhost or private names.

A noninteractive local-account deployment behind an existing proxy looks like:

bash ./install.sh --mode deploy --directory "$HOME/.smart-flint-production" \
  --public-url https://flint.your-domain.com --tls external --auth local --port 3011 \
  --non-interactive --no-open

Replace the example hostname. Supply secrets through the wizard or a private configuration file, not shell arguments. The installation directory contains credentials, setup instructions, Compose configuration, and the authoritative private installation plan. Protect and back up the directory; preserve the matching master key separately from database backups.

Option B: repository Compose deployment

From a trusted source checkout, create a new production configuration:

npm install
npm run configure -- --base-url=https://flint.your-domain.com --auth-mode=local
docker compose up --build -d

The configure command writes a private mode-600 .env, generates credentials, and refuses to overwrite an existing file. Select --auth-mode=oidc for organization sign-in. Configure the corresponding provider values before startup.

The repository Compose file binds the service to 127.0.0.1:3001 by default, bundles the production console with that service, keeps PostgreSQL internal, and sets DEMO_MODE=false. Point your HTTPS proxy at that loopback service. The repository Compose deployment is distinct from the installer-generated sandbox, where console/API share port 3010.

Configuration reference

Setting	Purpose
BASE_URL	Externally reachable HTTPS service origin used for launch and callback URLs
CONSOLE_URL	Public console origin, normally the same as BASE_URL
ENCRYPTION_KEY	Base64-encoded 32-byte random master key; keep it durable and private
POSTGRES_PASSWORD	URL-safe PostgreSQL password for the repository Compose stack
DATABASE_URL	Connection string when using your own supported PostgreSQL deployment
ADMIN_AUTH_MODE	Explicit local or oidc; new generated configurations default to local
ADMIN_BOOTSTRAP_ENABLED	Explicit first-owner setup permission; disable after owner handoff
ADMIN_TOKEN	Temporary bootstrap credential, at least 32 characters, used only during explicit setup
ADMIN_OIDC_ISSUER, ADMIN_OIDC_CLIENT_ID	Exact dedicated administrative provider registration
ADMIN_OIDC_AUTH_METHOD, ADMIN_OIDC_CLIENT_SECRET	Provider client authentication settings; secrets remain private
ADMIN_OIDC_ALLOWED_ORIGINS	Additional explicitly approved provider endpoint origins
ALLOW_PRIVATE_NETWORKS	Enable only for approved private upstream endpoints; connection allowlists still apply
RETENTION_HOURS	Retained clinical activation context; default 24 hours
OPERATIONS_LOGGING	Fixed redacted operational events; enabled by default in production

The administrative session cookie requires the console and runtime to share hostname and URL scheme; different ports may be used. For separate public hostnames, proxy administrative routes through the console hostname and use a consistent public origin. Review the administration guide for the exact OIDC callback and identity requirements.

Complete first-owner setup

Use Initial deployment setup with the temporary bootstrap credential, then create the first enabled Platform administrator under Settings & API → Users & access. Local accounts use a named username and passphrase. OIDC accounts use the exact provider issuer and subject; matching an email address grants no access.

The first usable owner automatically retires production bootstrap access. Sign in as that owner, remove the bootstrap credential from deployment configuration, and set ADMIN_BOOTSTRAP_ENABLED=false. The guided installer may create the first local owner interactively. If deferred, its private setup-secrets.json contains the temporary credential; the installer prints the file location rather than its value.

Verify and operate

Check GET /ready through the intended service route. Configure health checks against readiness, which validates database and stored signing-envelope access; GET /health reports process liveness separately. Review the configured public origin, sign-in, role assignments, and installation worksheet before a fresh synthetic or vendor-sandbox launch.

Plan certificate renewal, egress controls, off-host encrypted backups, retention, capacity monitoring, and a rehearsed recovery procedure. Local activation sessions last at most eight hours; upstream renewal does not extend that maximum. Operational events expire after 30 days. Protect custom proxy logs from clinical URLs and authorization query strings.

Before upgrades, back up and verify recovery using the operations runbook. Installer resume preserves the saved image lock and configuration; it does not automatically upgrade a deployment. Never replace an encryption key simply to start an existing database: the stored encrypted records require their matching key.

Source references: installation, development and deployment, Compose configuration, and operations.