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

# First production deployment

> Deploy HMIS safely, create foundational data, bootstrap the first administrator, and verify service health.

Perform the complete sequence in staging before production. Record every command, operator, timestamp, result, and deviation in the deployment record.

## Before deployment

* Approved commit and change record
* Environment variables reviewed by two authorized people
* DNS and TLS routes prepared
* Persistent volumes identified
* Off-site backup repository tested
* Maintenance, rollback, clinical, and security owners available
* `RUN_MIGRATIONS=false`

<Steps>
  <Step title="Create the initial recovery point">
    Capture the server or volume baseline and record its identifier. Even an empty first deployment needs a known recovery point for infrastructure configuration.
  </Step>

  <Step title="Deploy the approved commit">
    Trigger the Dokploy Compose deployment. Wait for `postgres` to become healthy and `app`, `queue`, and `scheduler` to remain running.

    Do not accept clinical traffic yet.
  </Step>

  <Step title="Stop production simulators">
    Stop `mock-analyzer` and `mock-modality` in Dokploy. Confirm neither has a domain or published network path. Repeat this check after every Compose redeployment.
  </Step>

  <Step title="Run migrations exactly once">
    Open a terminal for the `app` service:

    ```bash theme={null}
    php artisan migrate --force
    php artisan migrate:status
    ```
  </Step>

  <Step title="Seed foundational data explicitly">
    Run the required seeders by class and in this order:

    ```bash theme={null}
    php artisan db:seed --class=RoleSeeder --force
    php artisan db:seed --class=CountrySeeder --force
    php artisan db:seed --class=KenyaLocationSeeder --force
    php artisan db:seed --class=UserTypeSeeder --force
    php artisan db:seed --class=OrganizationSeeder --force
    php artisan db:seed --class=PayerSeeder --force
    php artisan db:seed --class=ServiceCatalogSeeder --force
    php artisan db:seed --class=MedicationScheduleSeeder --force
    ```

    Review the placeholder organization, branch, departments, clinics, payers, and services before go-live.
  </Step>

  <Step title="Create the first administrator">
    Run the interactive command so the password is not placed in shell history:

    ```bash theme={null}
    php artisan make:filament-user --panel=admin
    ```

    Enter the named administrator's real work email and a unique temporary password through the prompt.
  </Step>

  <Step title="Assign the super-administrator role">
    ```bash theme={null}
    php artisan shield:super-admin --panel=admin
    ```

    Select the user created in the previous step. Do not share this account.
  </Step>

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

    Confirm `op-visits:close-expired` is scheduled at `00:01` and the `queue` and `scheduler` containers remain running.
  </Step>

  <Step title="Clear and rebuild production caches">
    ```bash theme={null}
    php artisan optimize:clear
    php artisan optimize
    ```
  </Step>

  <Step title="Run smoke tests">
    Verify:

    * `https://{{HMIS_DOMAIN}}/up` returns `200`.
    * The administrator can sign in at `/admin`.
    * The administrator changes the temporary password and enables 2FA.
    * Branch selection and the main dashboard load.
    * Database writes, queue processing, scheduler state, storage, and mail work.
    * No repeating errors appear in application, queue, scheduler, proxy, or database logs.
  </Step>
</Steps>

<Warning>
  Never run `php artisan db:seed` without `--class` in production. The broad seeder creates a known `admin@example.com` / `password` account.
</Warning>

## Integration-specific release steps

Enable integrations only after the core HMIS checks pass. Use [Optional integrations](/platform/optional-integrations) for OIE, Orthanc, OHIF, API token, channel, endpoint, and acceptance requirements.

## Deployment evidence

Retain the commit, migration output, targeted seeder output, first-administrator identity, stopped simulator state, health results, backup identifier, log review, and approval to begin [initial configuration](/platform/initial-configuration).