> For the complete documentation index, see [llms.txt](https://spice.docs.medtroniclabs.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/configuration.md).

# Configuration

This page lists the settings an implementer must provide to run SPICE. It does not list every variable: each service has more optional tuning settings, documented in its own README and `application` configuration file.

## How services are configured

* **Backend services and the FHIR server** read their settings from **environment variables**. The configuration files inside each image reference those variables (for example `${DATABASE_URL}`), and several have defaults for optional values.
* **Docker Compose** reads one `.env` file and passes the relevant variables to each container. A template named `env.example` is provided with the Compose setup. See [Docker Compose Install](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/docker-compose.md).
* **Kubernetes or other orchestrators**: provide the same variables through ConfigMaps (non-sensitive values) and Secrets (sensitive values).
* **`spice_web`** reads its settings at **build time** from a `.env` file (variables prefixed `REACT_APP_`). Changing them means rebuilding.
* **`report_web`** reads a `config.json` file **at runtime**, so one build can be reused across environments by replacing that file. It may contain public browser configuration only.
* **The Android app** gets its server URLs and keys at **build time** from a properties file. See [Mobile App](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/android.md).

Values in the tables below are placeholders. Replace everything in angle brackets.

## Database

SPICE uses three PostgreSQL databases. They can live on the same server or on separate servers.

| Variable                                                | Used by              | Purpose                                    | Example                                        |
| ------------------------------------------------------- | -------------------- | ------------------------------------------ | ---------------------------------------------- |
| `DATABASE_URL`                                          | All backend services | JDBC URL of the core database              | `jdbc:postgresql://<db-host>:5432/<core-db>`   |
| `DATABASE_USERNAME` / `DATABASE_PASSWORD`               | All backend services | Core database credentials                  | `<db-user>` / `<change-me>`                    |
| `DB_MAX_POOL_SIZE`                                      | All backend services | Maximum connections per service instance   | `10`                                           |
| `FHIR_DATASOURCE_URL`                                   | `fhir-server`        | JDBC URL of the FHIR database              | `jdbc:postgresql://<db-host>:5432/<fhir-db>`   |
| `FHIR_DATASOURCE_USERNAME` / `FHIR_DATASOURCE_PASSWORD` | `fhir-server`        | FHIR database credentials                  | `<db-user>` / `<change-me>`                    |
| `REPORT_DB_URL`                                         | `cfr-service`        | JDBC URL of the reporting database         | `jdbc:postgresql://<db-host>:5432/<report-db>` |
| `REPORT_DB_USERNAME` / `REPORT_DB_PASSWORD`             | `cfr-service`        | Reporting database credentials             | `<db-user>` / `<change-me>`                    |
| `REPORT_DB_CORE_SCHEMA`, `REPORT_DB_REPORT_SCHEMA`      | `cfr-service`        | Schema names inside the reporting database | `core`, `report`                               |

Schema creation is automatic for the core and FHIR databases (migrations run on startup of `user-service` and `fhir-server`). The reporting database schemas are created from SQL files; see [Docker Compose Install](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/docker-compose.md) and [Data Import & Migration](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/data-import-and-migration.md).

Remember that total connections are roughly *service instances × `DB_MAX_POOL_SIZE`*. Size the PostgreSQL `max_connections` setting (or add a connection pooler) accordingly.

## Cache (Redis)

| Variable                                                                                  | Purpose                           | Example         |
| ----------------------------------------------------------------------------------------- | --------------------------------- | --------------- |
| `REDIS_HOST`                                                                              | Redis host name                   | `<redis-host>`  |
| `REDIS_PORT`                                                                              | Redis port                        | `6379`          |
| `SPRING_REDIS_POOL_MAX_TOTAL`, `SPRING_REDIS_POOL_MAX_IDLE`, `SPRING_REDIS_POOL_MIN_IDLE` | Connection pool tuning (optional) | `50`, `10`, `5` |

Redis authentication is **not enabled by default**: the password lines are commented out in the shipped Compose file and service configuration. Keep Redis on a private network, or enable authentication in your own configuration.

## Message queue

`offline-service` uses a message queue for sync requests. Enable exactly one provider.

| Variable                                             | Purpose                                                                                     | Example                            |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------- |
| `IS_RABBITMQ_SQS_ENABLED`                            | Use RabbitMQ                                                                                | `true`                             |
| `IS_AWS_SQS_ENABLED`                                 | Use a cloud queue instead of RabbitMQ                                                       | `false`                            |
| `RABBIT_MQ_HOST` / `RABBIT_MQ_PORT`                  | RabbitMQ address                                                                            | `<rabbitmq-host>` / `5672`         |
| `RABBIT_MQ_USERNAME` / `RABBIT_MQ_PASSWORD`          | RabbitMQ credentials. The Compose setup also uses them to create the broker's default user. | `<mq-user>` / `<change-me>`        |
| `RABBIT_MQ_EXCHANGE_NAME`, `RABBIT_MQ_GROUP`         | Exchange and consumer group names                                                           | `SPICE_EXCHANGE`, `SPICE_GROUP`    |
| `RABBIT_PRODUCER_CHANNEL`, `RABBIT_CONSUMER_CHANNEL` | Spring Cloud Stream channel names                                                           | keep the values from `env.example` |

If you choose the cloud queue provider, also set the queue URL and name variables (`SQS_REQUEST_QUEUE_URL`, `SQS_RESPONSE_QUEUE_URL`, `SQS_REQUEST_QUEUE_NAME`, `SQS_RESPONSE_QUEUE_NAME`) and the region and access credentials listed in the next section.

## Object storage

| Variable                                                                                | Used by                                   | Purpose                                                                                     | Example                                    |
| --------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `STORAGE_PROVIDER`                                                                      | `spice-service`                           | Object storage provider (default `s3`)                                                      | `s3`                                       |
| `BUCKET_NAME`                                                                           | `spice-service`                           | Container (bucket) name                                                                     | `<bucket>`                                 |
| `SIGNATURE_BUCKET_FOLDER`, `IN_APP_ANALYTICS_BUCKET_FOLDER`, `LABTEST_BUCKET_FOLDER`    | `spice-service`                           | Folder (key prefix) per content type                                                        | `<folder>/`                                |
| `OFFLINE_STORAGE_PROVIDER`                                                              | `offline-service`                         | `s3` (default), another supported cloud provider, or `local` (filesystem, for testing only) | `local`                                    |
| `OFFLINE_STORAGE_LOCAL_PATH`                                                            | `offline-service`                         | Directory used when the provider is `local`                                                 | `/log/s3-local`                            |
| `S3_BUCKET_NAME`, `PRE_SYNC_BUCKET_FOLDER`, `CONSENT_FORM_BUCKET_FOLDER`                | `offline-service`                         | Container and folders for sync and consent files                                            | `<bucket>`, `pre-sync/`                    |
| `CFR_S3_BUCKET`, `CFR_S3_REGION` and the `CFR_S3_*_FOLDER` / `AWS_S3_*` folder settings | `cfr-service`                             | Report export location                                                                      | see `env.example`                          |
| `SERVER_REGION`                                                                         | Several services                          | Region identifier used by the storage client                                                | `<region>`                                 |
| `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, `AWS_REGION`                                        | `offline-service`, `notification-service` | Credentials for the object storage or cloud queue API                                       | `<access-key>`, `<secret-key>`, `<region>` |

## Authentication and sessions

| Variable                                | Used by                                                                 | Purpose                                                                                      | Example                      |
| --------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------- |
| `AUTH_SERVICE`                          | Services that validate users                                            | Base URL of `auth-service`                                                                   | `http://<auth-host>:8089`    |
| `AUTH_TOKEN_TIME_LIMIT_IN_MINUTES`      | All backend services                                                    | Login token lifetime. Keep identical across services.                                        | `240`                        |
| `FORGOT_PASSWORD_TIME_LIMIT_IN_MINUTES` | `user-service`                                                          | Validity of password reset links                                                             | `60`                         |
| `ALLOWED_ORIGINS`                       | All backend services                                                    | Comma-separated list of browser origins allowed by CORS. Use your real web application URLs. | `https://<web-host>`         |
| `DOMAIN_NAME`                           | All backend services                                                    | Domain used for cookies and links                                                            | `<your-domain>`              |
| `INTERNAL_ASSERTION_PRIVATE_KEY`        | `auth-service` only                                                     | Signing key (ES256, base64 PKCS#8) for the internal identity header passed between services  | `<generated>`                |
| `INTERNAL_ASSERTION_PUBLIC_KEY`         | Every other backend service and `fhir-server`                           | Matching public key (base64 X.509) used to verify that header                                | `<generated>`                |
| `JOB_USER_NAME` / `JOB_USER_PASSWORD`   | `offline-service`, `fhir-mapper` (`JOB_USER_NAME` also `spice-service`) | Credentials of the internal service account used for background and service-to-service calls | `<job-user>` / `<change-me>` |
| `APP_PASSWORD_HASHING_ENABLED`          | `user-service`                                                          | Enable stronger server-side password hashing (default `false`)                               | `false`                      |

Generate the internal key pair once, and distribute the public key to every service:

```bash
openssl ecparam -name prime256v1 -genkey -noout -out internal-assertion.pem
# private key (auth-service only)
openssl pkcs8 -topk8 -nocrypt -in internal-assertion.pem -outform DER | base64 | tr -d '\n'
# public key (all other services)
openssl ec -in internal-assertion.pem -pubout -outform DER | base64 | tr -d '\n'
```

The web clients hash the password in the browser before sending it, using a key you set at build time (`REACT_APP_PASSWORD_HASH_KEY` in `spice_web`; the Android app has an equivalent salt). Use the same value across every client of one installation, and do not reuse a value from another installation.

## Notification providers

Notifications are optional. Turn on only what you use.

| Variable                                                                                                                                      | Purpose                                                                                      | Example                            |
| --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `NOTIFICATION_SERVICE`                                                                                                                        | Base URL of `notification-service`, used by other services                                   | `http://<notification-host>:8084`  |
| `MAIL_SEND`                                                                                                                                   | Master switch for e-mail                                                                     | `true`                             |
| `MAIL_HOST`                                                                                                                                   | SMTP host                                                                                    | `<smtp-host>`                      |
| `MAIL_USER` / `MAIL_PASSWORD`                                                                                                                 | SMTP credentials                                                                             | `<smtp-user>` / `<change-me>`      |
| `MAIL_FROM`                                                                                                                                   | Sender address                                                                               | `noreply@<your-domain>`            |
| `ENABLE_SMS_NOTIFICATION`                                                                                                                     | Master switch for SMS                                                                        | `false`                            |
| `ENABLE_SMS_NOTIFICATION_*` and the matching provider credentials                                                                             | One flag and credential set per supported SMS gateway. Enable the one you contract with.     | see `env.example`                  |
| `SMS_RESET_PASSWORD_URL`, `EMAIL_APP_URL`                                                                                                     | Base URLs placed in reset links                                                              | `https://<web-host>`               |
| `SHEDLOCK_EMAIL_START`, `SHEDLOCK_EMAIL_STOP`, `SHEDLOCK_SMS_START`, `SHEDLOCK_SMS_STOP`, `SHEDLOCK_OUTBOUND_START`, `SHEDLOCK_OUTBOUND_STOP` | Lock durations (ISO-8601) that stop scheduled jobs running twice. **No defaults: set them.** | `PT30S`, `PT02M`, `PT24H`, `PT25H` |

## FHIR server connection

| Variable                                                            | Used by                       | Purpose                                                                                                                                                   | Example                                |
| ------------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `HAPI_SERVER_URL`                                                   | `fhir-mapper`, `cql-service`  | Base URL of the FHIR server, including `/fhir/`                                                                                                           | `http://<fhir-host>:8091/fhir/`        |
| `HAPI_IDENTIFIER_URL`                                               | `fhir-mapper`                 | Base URI used for identifier systems written to FHIR resources. Choose a URI you control and **keep it stable**: changing it later affects existing data. | `https://<your-domain>/`               |
| `FHIR_SERVICE`                                                      | Services that call the mapper | Base URL of `fhir-mapper` (not the FHIR server)                                                                                                           | `http://<mapper-host>:8092`            |
| `FHIR_SERVER_PORT`                                                  | `fhir-server`                 | Listening port                                                                                                                                            | `8091`                                 |
| `FHIR_SERVER_AUTH_ENABLED`                                          | `fhir-server`                 | Require a valid bearer token (default `true`). Never disable outside local testing.                                                                       | `true`                                 |
| `APP_VALIDATE_TOKEN_API`                                            | `fhir-server`                 | Auth service endpoint used to validate tokens                                                                                                             | `http://<auth-host>:8089/authenticate` |
| `HAPI_FHIR_CORS_ALLOWED_ORIGIN`, `HAPI_FHIR_CORS_ALLOW_CREDENTIALS` | `fhir-server`                 | CORS for the FHIR endpoint. Restrict the origin in production.                                                                                            | `https://<web-host>`, `false`          |

Partitioning settings (`FHIR_PARTITION_*`) are explained in [FHIR Server & Mapper](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/fhir-server-and-mapper.md). Leave them at their defaults unless that page tells you otherwise.

## URLs between services

Every service needs the base URLs of the services it calls. Inside a private network, use internal host names and plain HTTP. These variables must be set on each service that calls the target:

| Variable               | Points to              | Example                           |
| ---------------------- | ---------------------- | --------------------------------- |
| `AUTH_SERVICE`         | `auth-service`         | `http://<auth-host>:8089`         |
| `USER_SERVICE`         | `user-service`         | `http://<user-host>:8085`         |
| `ADMIN_SERVICE`        | `admin-service`        | `http://<admin-host>:8086`        |
| `SPICE_SERVICE`        | `spice-service`        | `http://<spice-host>:8087`        |
| `OFFLINE_SERVICE`      | `offline-service`      | `http://<offline-host>:8093`      |
| `NOTIFICATION_SERVICE` | `notification-service` | `http://<notification-host>:8084` |
| `FHIR_SERVICE`         | `fhir-mapper`          | `http://<mapper-host>:8092`       |
| `CQL_SERVICE`          | `cql-service`          | `http://<cql-host>:8094`          |
| `CFR_SERVICE`          | `cfr-service`          | `http://<cfr-host>:8050`          |

Public URLs are different: clients reach services through the reverse proxy, for example `https://<api-host>/spice-service/...`. Web applications use `REACT_APP_BASE_URL` (see below) and the Android app its build-time base URL.

## Web application settings

| Setting                                                                                                              | Application                | Purpose                                                          |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------- |
| `REACT_APP_BASE_URL`                                                                                                 | `spice_web`                | Public base URL of the API gateway                               |
| `REACT_APP_PASSWORD_HASH_KEY`                                                                                        | `spice_web`                | Client-side password hashing key (see above)                     |
| `REACT_APP_CRYPTR_SECRET_KEY`                                                                                        | `spice_web`                | Key for encrypting values kept in the browser. Set your own.     |
| `REACT_APP_CFR_WEB_URL`, `REACT_APP_INSIGHT_WEB_URL`                                                                 | `spice_web`                | Links to the reporting web application and dashboards (optional) |
| `REACT_APP_GA_TRACKING_ID`, `REACT_APP_ORG_SUCCESS_DELAY_TIME`, `REACT_APP_VERSION`                                  | `spice_web`                | Optional analytics id, UI delay and version label                |
| `baseUrl`, `spiceWebUrl`, `cryptrSecretKey`, `environment` (required); `publicUrl`, `analyticsTrackingId` (optional) | `report_web` `config.json` | Runtime configuration; the file may contain public values only   |

## Feature flags and behaviour switches

| Variable                                                                                | Used by                                           | Purpose                                                                                                                                                                                                                                                | Default                      |
| --------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
| `SWAGGER_ENABLED`                                                                       | All backend services                              | Expose API documentation pages                                                                                                                                                                                                                         | off. Keep off in production. |
| `SMART_ANC_ENABLED`                                                                     | `spice-service`, `offline-service`, `fhir-mapper` | Enable the antenatal clinical-rules module                                                                                                                                                                                                             | install-specific             |
| `PRE_SYNC_SERVE_ENABLED`, `PRE_SYNC_SCHEDULING_ENABLED`                                 | `offline-service`                                 | Serve and nightly-generate pre-built first-sync files                                                                                                                                                                                                  | `false`                      |
| `FHIR_PARTITION_MODE_ENABLED`                                                           | `fhir-mapper`, `cql-service`                      | Route FHIR writes to the FHIR server's district partitions. Keep consistent with the FHIR server's `FHIR_PARTITION_REQUEST_TENANT`; see [FHIR Server & Mapper](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/fhir-server-and-mapper.md) | `false`                      |
| `SUPERSET_ENABLE`, `SUPERSET_URL`, `SUPERSET_LOGIN_USERNAME`, `SUPERSET_LOGIN_PASSWORD` | `user-service`                                    | Optional link to an external BI tool                                                                                                                                                                                                                   | `false`                      |
| `AUDIT_LEGACY_WRITER_ENABLED`                                                           | All backend services                              | Compatibility switch for the older audit format                                                                                                                                                                                                        | `false`                      |

Programme-specific follow-up rules (`FOLLOWUP_*`, `*_RETRY_ATTEMPTS`, `*_CALL_ATTEMPTS`) tune follow-up and call-register timing in `spice-service`. They are provided in `env.example`; set values that fit your programme.

## Logging

* Services log to the console and to files under `/log` inside the container. Mount a volume there, or ship console output to your log platform.
* Log files rotate daily and are capped in size by each service's configuration.
* Management endpoints expose only `info` and `health`.
* Do not enable verbose request logging in production: requests contain personal health information.

## Secrets handling

* Never commit `.env` files, keys or passwords to source control. Only `env.example` (with empty values) belongs in the repository.
* Use unique, strong values for every password and key. Do not reuse values from examples, documentation or other installations. Generate separate secrets for each environment.
* In Kubernetes, use Secrets (or an external secrets manager) for every variable that holds a password, key or token, and restrict who can read them.
* Provide `INTERNAL_ASSERTION_PRIVATE_KEY` to `auth-service` only.
* Rotate credentials on a schedule and whenever staff with access leave. Rotating an internal key pair means redeploying the services that use it.
* Do not put secrets in `config.json` for `report_web`, in `REACT_APP_*` variables beyond those listed, or in the Android build: anything shipped to a browser or device can be extracted.

## Per-environment configuration

Keep one configuration set per environment (for example, a local or test environment and a production environment) and keep them separate:

* **Different secrets and keys** in each environment; never copy production data or credentials into a test environment.
* **Different URLs and `ALLOWED_ORIGINS`.** In production, list only your real web origins and use HTTPS.
* **Debug aids off in production:** `SWAGGER_ENABLED=false`, no HAPI tester pages exposed publicly.
* **Right-size pools and memory per environment** (`DB_MAX_POOL_SIZE`, JVM memory, FHIR server thread settings). See [Sizing & Operations](https://spice.docs.medtroniclabs.org/deploy/deployment-guide/sizing-and-operations.md).
* **Real providers only where needed:** use test SMTP and SMS sinks outside production so no real messages are sent.
* **Version-control your non-secret configuration** (ConfigMaps or an `.env` template) so environments can be reproduced and compared.
