> ## 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.

# Release and rollback

> Promote an approved HMIS release, run migrations safely, verify production, and recover from a failed deployment.

Every production release must have a tested staging deployment, a pre-release recovery point, a named operator, and a named rollback authority.

## Release record

Record the following before the maintenance window:

* Approved commit and source branch
* Application, migration, dependency, integration, and configuration changes
* Staging test evidence
* Expected downtime and communication owner
* Backup identifier and restore verification date
* Migration and targeted-seeder commands
* Smoke tests and clinical workflow checks
* Rollback decision deadline and owner

## Production release

<Steps>
  <Step title="Confirm the recovery point">
    Create and verify the pre-release database and volume backup. Do not proceed when the most recent restore evidence is missing or the off-site upload failed.
  </Step>

  <Step title="Enter maintenance mode">
    In the `app` service terminal:

    ```bash theme={null}
    php artisan down --retry=60 --refresh=15 --with-secret
    ```

    Store the generated bypass URL only in the release record and share it with the release team through the approved secret channel.
  </Step>

  <Step title="Deploy the approved commit">
    Deploy through Dokploy and watch build, proxy, application, queue, scheduler, and database logs. Keep `RUN_MIGRATIONS=false`.
  </Step>

  <Step title="Run migrations once">
    ```bash theme={null}
    php artisan migrate --force --isolated
    php artisan migrate:status
    ```

    Stop and escalate if a migration fails. Do not repeatedly rerun a partially applied data migration without reviewing its state.
  </Step>

  <Step title="Refresh permissions and approved integration data">
    ```bash theme={null}
    php artisan db:seed --class=RoleSeeder --force
    ```

    Run `PacsDemoSeeder` only when the approved release requires the supplied PACS endpoint update:

    ```bash theme={null}
    php artisan db:seed --class=PacsDemoSeeder --force
    ```
  </Step>

  <Step title="Restart background work and caches">
    ```bash theme={null}
    php artisan queue:restart
    php artisan optimize:clear
    php artisan optimize
    php artisan schedule:list
    php artisan queue:failed
    ```
  </Step>

  <Step title="Reapply the simulator control">
    Stop `mock-analyzer` and `mock-modality`, confirm neither has a domain, and check the firewall. A Compose deployment can restart them.
  </Step>

  <Step title="Run pre-open smoke tests">
    Test `/up`, administrator and staff authentication, branch selection, a database write, file storage, queue processing, scheduler state, mail, and every affected clinical or integration workflow.
  </Step>

  <Step title="Leave maintenance mode">
    ```bash theme={null}
    php artisan up
    ```

    Repeat the external health and authentication checks without the maintenance bypass.
  </Step>

  <Step title="Observe and close">
    Monitor errors, latency, queue depth, resource use, storage, and integrations through the agreed observation window. Attach results to the release record.
  </Step>
</Steps>

## Rollback decision

Rollback the application when the candidate cannot pass health, authentication, data integrity, or critical workflow checks within the approved window. Stop traffic first and retain logs and failed-state evidence.

<Tabs>
  <Tab title="No migration or data change">
    Select the previous tested deployment or commit in Dokploy, redeploy it, clear caches, restart the queue, stop simulators, and repeat smoke tests.
  </Tab>

  <Tab title="Backward-compatible migration">
    Prefer the previous application image only when the migration was explicitly designed to support it. Leave the schema in place and create a forward fix.
  </Tab>

  <Tab title="Clinical data written on new schema">
    Do not run `migrate:rollback` by default. Preserve the data, place the system in maintenance mode, and use an reviewed forward-fix migration. Restore the pre-release backup only when the incident owner confirms the acceptable data-loss window and clinical reconciliation plan.
  </Tab>
</Tabs>

<Warning>
  Never regenerate `APP_KEY`, delete volumes, run `migrate:fresh`, or restore a database over the live database as a rollback shortcut.
</Warning>

## Post-rollback reconciliation

* Compare transactions created during the release window with source documents and connected systems.
* Reconcile queued, failed, duplicated, or externally acknowledged messages.
* Confirm the exact restored or retained database point.
* Record the incident timeline, decision, user impact, corrective action, and next release controls.