> ## Documentation Index
> Fetch the complete documentation index at: https://hmis-docs.derrickmugabwa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment model

> Required separation and promotion rules for local, staging, and production HMIS environments.

HMIS uses three environments. Promote the same tested commit from local development to staging and then to production.

| Property    | Local                                     | Staging                                      | Production                         |
| ----------- | ----------------------------------------- | -------------------------------------------- | ---------------------------------- |
| Purpose     | Development and disposable demonstrations | Release validation and integration rehearsal | Live hospital operations           |
| Runtime     | Native Windows or Docker Desktop          | Dokploy                                      | Dokploy                            |
| Data        | Synthetic only                            | Synthetic or irreversibly de-identified      | Live clinical data                 |
| `APP_ENV`   | `local`                                   | `staging`                                    | `production`                       |
| `APP_DEBUG` | `true`                                    | `false`                                      | `false`                            |
| Domains     | `localhost`                               | Dedicated non-production domains             | Approved production domains        |
| Secrets     | Local `.env`, never committed             | Unique Dokploy variables                     | Unique Dokploy variables           |
| Simulators  | Allowed                                   | Allowed for acceptance testing               | Must be stopped and inaccessible   |
| Backups     | Optional                                  | Required before release tests                | Nightly encrypted off-site backups |

## Promotion contract

<Steps>
  <Step title="Validate locally">
    Run the affected automated tests, build the frontend, and exercise the changed workflow with synthetic data.
  </Step>

  <Step title="Deploy the exact commit to staging">
    Run migrations, targeted seeders, smoke tests, and any laboratory or radiology acceptance cycle required by the change.
  </Step>

  <Step title="Approve the release">
    Record the commit, migration status, backup identifier, acceptance evidence, operator, rollback owner, and maintenance window.
  </Step>

  <Step title="Promote to production">
    Deploy the approved commit without rebuilding from an unreviewed branch. Follow the [release runbook](/platform/operations/release-and-rollback).
  </Step>
</Steps>

## Separation requirements

* Use different databases, volumes, domains, API tokens, APP\_KEY values, mail destinations, and device credentials in every environment.
* Do not restore production data into local or staging unless the data is irreversibly de-identified and the transfer is approved.
* Prevent staging mail and notifications from reaching real patients or staff.
* Give staging integrations distinct facility, instrument, PACS, and OIE identifiers.
* Preserve the production `APP_KEY`; losing or replacing it can make encrypted application data unreadable.

<Warning>
  Never copy a local `.env` into Dokploy. Build the staging and production variable sets from the documented matrix and generate new secrets for each environment.
</Warning>

## Release evidence

Retain the following with each production deployment:

* Approved commit or image identifier
* Database migration status before and after deployment
* Pre-release backup identifier and restore status
* Automated test and staging acceptance results
* Production smoke-test results
* Known issues and rollback decision point
* Names of the release operator and clinical approver