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

# Deployment troubleshooting

> Diagnose common Dokploy, Laravel, database, queue, scheduler, storage, TLS, and integration failures.

Start with the deployment identifier, container state, health checks, recent logs, disk usage, and database health. Work in staging when reproducing a non-urgent issue.

<AccordionGroup>
  <Accordion title="The application container is unhealthy">
    1. Confirm `postgres` is healthy and `DB_PASSWORD` matches both services.
    2. Review `app` logs for configuration, permissions, migration, or database errors.
    3. Run `php artisan about --only=environment` in the `app` terminal.
    4. Check `APP_KEY`, storage permissions, and free disk space.
    5. Do not enable `APP_DEBUG` in production; reproduce detailed errors in staging.
  </Accordion>

  <Accordion title="HMIS returns 502 or 504">
    Confirm `app` is running, its health check passes, the Dokploy domain targets service `app` port `80`, and the proxy redeployed after a domain change. Review proxy and Apache logs and check CPU, memory, and database latency.
  </Accordion>

  <Accordion title="TLS certificate is missing or invalid">
    Confirm DNS resolves to the current server, ports `80` and `443` reach Dokploy, the domain is attached to the correct Compose service, and no conflicting router uses the same hostname. Redeploy the Compose service after changing its domain.
  </Accordion>

  <Accordion title="Migrations fail">
    Stop the release, retain the exact output, and inspect `php artisan migrate:status`. Do not run `migrate:fresh`, delete the migration table, or repeatedly execute a partially applied data migration. Use the pre-release recovery point or a reviewed forward fix according to the release decision.
  </Accordion>

  <Accordion title="The first administrator cannot access the panel">
    Confirm the user exists, `RoleSeeder` completed, and `shield:super-admin --panel=admin` assigned `super_admin` to the correct user. Confirm the account uses the intended email and has not been disabled.
  </Accordion>

  <Accordion title="Queued work is not processing">
    Check the `queue` container, database connectivity, and `php artisan queue:failed`. Restart gracefully with `php artisan queue:restart`. Investigate the exception before retrying failed clinical or integration jobs to prevent duplicates.
  </Accordion>

  <Accordion title="Scheduled visits are not closing">
    Confirm the `scheduler` container is running and `php artisan schedule:list` shows `op-visits:close-expired` at `00:01`. Verify timezone, logs, database access, and whether schedule execution was paused.
  </Accordion>

  <Accordion title="Uploads or generated files fail">
    Check `app-storage`, free disk space, container storage permissions, and the `public/storage` link. Run `php artisan storage:link --force` only after confirming the configured disk and target are correct.
  </Accordion>

  <Accordion title="OIE Administrator is unreachable">
    Distinguish browser access from the desktop Administrator client. The browser route uses service port `8080` through Dokploy; the desktop client uses loopback-bound HTTPS `8443` through a VPN or SSH tunnel. Do not expose all OIE listener ports to solve an administration problem.
  </Accordion>

  <Accordion title="OHIF opens with a white page">
    Review browser and OHIF Nginx logs, confirm the domain targets `ohif` port `80`, and verify the supplied Nginx configuration includes `gzip_static on;`. Confirm DICOMweb proxy paths reach Orthanc internally.
  </Accordion>

  <Accordion title="Orthanc cannot write a study">
    Check `orthanc-storage` capacity and permissions, Orthanc PostgreSQL health, DICOM firewall rules, AE titles, and modality definitions. Stop acquisition if storage integrity is uncertain.
  </Accordion>

  <Accordion title="A backup or restore check fails">
    Treat the installation as outside its recovery objective. Preserve job output, check repository credentials and capacity, create a new verified backup after correction, and schedule an isolated restore. Do not prune the last known good recovery point.
  </Accordion>

  <Accordion title="Mock services restarted in production">
    Stop `mock-analyzer` and `mock-modality`, confirm no domains or firewall paths exist, and record the event. Recheck after every Compose deployment until profiles are implemented in the application repository.
  </Accordion>
</AccordionGroup>

## Safe evidence collection

Collect the smallest relevant time window and sanitize patient identifiers, tokens, passwords, hostnames, IP addresses, study data, and message payloads before sharing. Record the deployment commit, service, timestamp with timezone, request/message identifier, and exact error.

## Escalation package

* Environment and deployment identifier
* Start time, impact, and affected workflows
* Sanitized error and relevant log window
* Container and health state
* Recent migration/configuration/deployment changes
* Actions already attempted and their results
* Current backup status and rollback constraints