Deploying a Siter Environment

This guide walks through deploying a Siter environment using Docker Compose. A standard deployment consists of five services:

Siter API — the backend application server
Siter UI — the frontend web application
PostgreSQL — the primary database (with PostGIS for spatial data)
Pufferfish API — the analysis engine for facility evaluation
MongoDB — the database backing the analysis engine

Prerequisites

Docker and Docker Compose installed on the host machine
Access to the Siter container registry (provided by the Siter team)
A valid Siter license (provided by the Siter team)

Base Docker Compose Configuration

Below is a base docker-compose.yaml you can use as a starting point. Copy this file and customize the environment variables for your deployment.

networks:
  siter:

services:
  # ── Siter API (backend) ──────────────────────────────────────────
  siter-api:
    image: <provided-by-siter-team>/siterapi:latest
    ports:
      - 5000:5000
    networks:
      - siter
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_URLS=http://0.0.0.0:5000
      - ConnectionStrings__SITER_DB=Host=siter-db;Port=5432;Database=siterdb;Username=siter;Password=CHANGE_ME
      - LoginTypes=20
      - multiTenant=true
      - corsUrls=["https://siter.example.com"]
      - AnalysisOptions__AnalysisUrl=http://pufferfish:26667
      - AnalysisOptions__DictionaryUrl=http://pufferfish:26667
      - jwt__AuthDomain=siter
      - jwt__AuthKey=CHANGE_ME_TO_A_LONG_RANDOM_STRING
      - jwt__AuthMinutes=480
    depends_on:
      siter-db:
        condition: service_healthy
      pufferfish:
        condition: service_started

  # ── Siter UI (frontend) ─────────────────────────────────────────
  siter-ui:
    image: <provided-by-siter-team>/siterui:latest
    ports:
      - 80:80
    networks:
      - siter

  # ── PostgreSQL + PostGIS (Siter database) ───────────────────────
  siter-db:
    image: postgis/postgis:18-3.6
    networks:
      - siter
    ports:
      - 5432:5432
    volumes:
      - siter-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=siterdb
      - POSTGRES_USER=siter
      - POSTGRES_PASSWORD=CHANGE_ME
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U siter -d siterdb"]
      interval: 5s
      timeout: 5s
      retries: 5

  # ── Pufferfish API (analysis engine) ────────────────────────────
  pufferfish:
    image: <provided-by-siter-team>/pufferfish:latest
    ports:
      - 26667:26667
    networks:
      - siter
    environment:
      - DB_IP=pufferfish-mongo
      - PINO_LOG_LEVEL=warn
    depends_on:
      - pufferfish-mongo

  # ── MongoDB (Pufferfish database) ──────────────────────────────
  pufferfish-mongo:
    image: mongo:8.2.2
    networks:
      - siter
    volumes:
      - pufferfish-data:/data/db

volumes:
  siter-data:
  pufferfish-data:

warning

Replace all CHANGE_ME values with secure, unique passwords before deploying. The jwt__AuthKey should be a long, random string used to sign authentication tokens.

Starting the Environment

docker compose up -d

On first startup, Siter will automatically run database migrations to initialize the schema. You can verify the services are running with:

docker compose ps

The API will be available at http://localhost:5000, the UI at http://localhost:80, and the Pufferfish analysis engine at http://localhost:26667.

Environment Variables Reference

All configuration in Siter follows the ASP.NET Core configuration model. Environment variables override values from config files and use double underscores (__) as separators for nested settings (e.g., AnalysisOptions__AnalysisUrl).

Core Application

Variable	Required	Default	Description
`ASPNETCORE_ENVIRONMENT`	No	`Production`	The application environment name.
`ASPNETCORE_URLS`	No	—	The URL(s) for Kestrel to listen on (e.g., `http://0.0.0.0:5000`).

Database Connection

The database connection can be configured as a full connection string or as individual components. If both are provided, the full connection string takes precedence.

Option A: Full connection string

Variable	Required	Default	Description
`ConnectionStrings__SITER_DB`	Yes*	—	Full PostgreSQL connection string (e.g., `Host=db;Port=5432;Database=siterdb;Username=siter;Password=pass`).

Option B: Individual components

Variable	Required	Default	Description
`SITER_DB_SERVER`	Yes*	—	Database server hostname or IP address.
`SITER_DB_USER`	Yes*	—	Database username.
`SITER_DB_PW`	Yes*	—	Database password.
`SITER_DB_DATA`	Yes*	—	Database name.

* One of Option A or Option B is required.

Database Behavior

Variable	Required	Default	Description
`SITER_NO_MIGRATIONS`	No	`false`	Set to `true` to disable automatic database migrations on startup. Useful for environments where migrations are applied separately.

Authentication

Variable	Required	Default	Description
`LoginTypes`	No	`0` (None)	Bitmask controlling which authentication methods are enabled. See Login Types below.
`jwt__AuthDomain`	Yes	—	The issuer and audience string used when generating and validating JWT tokens.
`jwt__AuthKey`	Yes	—	The secret key used to sign JWT tokens. Must be a long, random string.
`jwt__AuthMinutes`	No	`480`	How long (in minutes) JWT tokens remain valid before expiring.

LoginTypes is a bitmask (flags enum). Combine values by adding them together.

Value	Type	Description
`1`	Login	Reserved.
`2`	Windows	Windows/Kerberos authentication (NTLM/Negotiate).
`4`	Google	Google OAuth sign-in.
`8`	NoAuth	Auto-login without credentials. Development/testing only.
`16`	Microsoft	Microsoft Entra ID (Azure AD) sign-in.

Common configurations:

Value	Methods	Use Case
`12`	Google + NoAuth	Development with quick login
`20`	Google + Microsoft	Production (typical)
`4`	Google only	Production (Google only)
`16`	Microsoft only	Production (Microsoft only)

Microsoft Entra ID (Azure AD) SSO

These are required when Microsoft login is enabled (LoginTypes includes 16). See the SSO Setup Guide for detailed instructions on configuring the Azure App Registration.

Variable	Required	Default	Description
`AzureAd__ClientId`	Conditional	—	The Application (client) ID from your Azure App Registration.
`AzureAd__RedirectUri`	Conditional	—	The redirect URI configured in your App Registration (must match exactly).
`AzureAd__Instance`	No	`https://login.microsoftonline.com/`	The Azure AD authority URL. Change for government clouds (e.g., `https://login.microsoftonline.us/`).
`AzureAd__TenantId`	No	`common`	The Azure AD tenant ID. Use `common` for multi-tenant, or a specific tenant GUID to restrict access.

Licensing

Variable	Required	Default	Description
`multiTenant`	No	`false`	Set to `true` for multi-tenant deployments where each customer/organization has its own license. Set to `false` for single-tenant deployments with one system-wide license.

Analysis Engine (Pufferfish)

The analysis engine (Pufferfish) provides automated facility evaluation capabilities. When running in the same Docker Compose stack, point these at the internal service name (e.g., http://pufferfish:26667).

Variable	Required	Default	Description
`AnalysisOptions__AnalysisUrl`	Yes	—	URL of the Pufferfish analysis engine (e.g., `http://pufferfish:26667`).
`AnalysisOptions__DictionaryUrl`	Yes	—	URL of the criteria dictionary service. Typically the same as the analysis URL.
`AnalysisOptions__UseWkt`	No	`false`	Set to `true` to transmit geometry data as WKT instead of WKB format.

CORS

Variable	Required	Default	Description
`corsUrls`	No	—	JSON array of allowed CORS origins. Must include the URL where your UI is hosted (e.g., `["https://siter.example.com"]`). Required when the UI and API are served from different origins.

Seed Administrator Account

On first startup, you can automatically create a system administrator account.

Variable	Required	Default	Description
`SITER_SA`	No	—	Creates a seed SA account. Format: `LOGIN::LOGIN_TYPE::DISPLAY_NAME`. The `LOGIN_TYPE` is the numeric value from the Login Types table (e.g., `user@example.com::16::Jane Doe` for a Microsoft account).

UI and Hosting

These are typically only needed in standalone or self-hosted deployments where the API serves the UI directly.

Variable	Required	Default	Description
`useDefaultFiles`	No	`false`	Set to `true` to have the API serve static UI files from `wwwroot`.
`wwwRoot`	No	—	Custom path to the static content folder (when `useDefaultFiles` is `true`).
`baseHref`	No	`/`	Base href for the Angular application.
`useResponseCompression`	No	`true`	Enables Brotli/Gzip response compression.

Telemetry and Debugging

Variable	Required	Default	Description
`EnableTelemetry`	No	`true`	Enables internal process statistics collection.
`echoRequests`	No	`false`	Logs all incoming HTTP requests to the console. Useful for debugging.
`SiterEnableDbContextSensitiveLogging`	No	`false`	Enables Entity Framework sensitive data logging. Do not enable in production as it may log passwords and other sensitive values.

PostgreSQL Container

These variables configure the PostgreSQL container itself (not the Siter application).

Variable	Required	Default	Description
`POSTGRES_DB`	Yes	—	Name of the database to create.
`POSTGRES_USER`	Yes	—	Database superuser name.
`POSTGRES_PASSWORD`	Yes	—	Database superuser password.

Pufferfish Container

These variables configure the Pufferfish analysis engine service.

Variable	Required	Default	Description
`DB_IP`	Yes	—	Hostname of the MongoDB instance (e.g., `pufferfish-mongo` when using the Docker Compose above).
`DB_PORT`	No	`27017`	Port of the MongoDB instance.
`PINO_LOG_LEVEL`	No	`warn`	Logging verbosity. One of `debug`, `info`, `warn`, `error`.
`VERSION`	No	`development`	Application version string (informational).

MongoDB Container

The MongoDB container used by Pufferfish requires no configuration by default. Data is persisted to the pufferfish-data volume.

Configuration Precedence

Siter loads configuration in the following order, where later sources override earlier ones:

appsettings.json (base defaults, built into the image)
appsettings.{ASPNETCORE_ENVIRONMENT}.json (environment-specific overrides)
Environment variables (the primary way to configure deployments)
Command-line arguments

For most deployments, environment variables in the Docker Compose file are the recommended configuration method.

Verifying Your Deployment

After starting the services, verify the deployment:

API health: Navigate to http://localhost:5000/swagger to confirm the API is running.
Database connectivity: Check the API container logs for the DB: log line confirming the connection string.
Analysis engine: Check the Siter API logs for the line listing supported criteria types — this confirms the API can reach Pufferfish. If the engine is unreachable, you'll see a warning — the application will still start but analysis features will be unavailable until the engine is accessible. You can also verify Pufferfish directly at http://localhost:26667.
Authentication: Navigate to the UI and confirm the expected login options appear.

Prerequisites​

Base Docker Compose Configuration​

Starting the Environment​

Environment Variables Reference​

Core Application​

Database Connection​

Database Behavior​

Authentication​

Login Types​

Microsoft Entra ID (Azure AD) SSO​

Licensing​

Analysis Engine (Pufferfish)​

CORS​

Seed Administrator Account​

UI and Hosting​

Telemetry and Debugging​

PostgreSQL Container​

Pufferfish Container​

MongoDB Container​

Configuration Precedence​

Verifying Your Deployment​