# Docker deployment runbook — Ojodu LCDA HMIS

## Scope and warning

This is a repeatable staging/deployment scaffold. It has **not** been built or executed in this generation environment because Docker, Composer and a database server are unavailable. Do not use real patient data until the production readiness checklist is signed off.

The Compose stack contains:
- PHP 8.3-FPM application container (PDO MySQL and SQLite drivers)
- MySQL 8.4 database with a persistent named volume
- Nginx reverse-proxy/web container
- Persistent Laravel storage volume

The database is not published to the host. Nginx binds to `127.0.0.1` by default; put it behind a separately managed TLS reverse proxy/load balancer.

## Prerequisites

- Linux server with Docker Engine and Docker Compose v2
- DNS name and TLS certificate at the external reverse proxy
- Firewall allowing only the required HTTPS entry point
- Encrypted off-server backup destination

## First deployment

1. Extract the archive on the server and enter the project directory.
2. Create the environment file:

   ```bash
   cp .env.example .env
   ```

3. Edit `.env`. Set unique high-entropy values for `APP_KEY`, `DB_PASSWORD`, and `MYSQL_ROOT_PASSWORD`; set the public `APP_URL` to the HTTPS hostname; keep `APP_DEBUG=false`; retain `APP_ENV=production`. The database user password and MySQL root password must be different. Do not commit `.env`.
4. Generate a Laravel key if `APP_KEY` is still blank:

   ```bash
   docker compose build app
   docker compose run --rm --no-deps --entrypoint php app artisan key:generate --show
   ```

   Copy the displayed key into `.env` as `APP_KEY=base64:...`. Do not repeatedly rotate the key after encrypted sessions or data exist.
5. Build and start the containers:

   ```bash
   docker compose up -d --build
   docker compose ps
   docker compose logs --tail=100 app mysql nginx
   ```

6. Run database migrations and reference seed data explicitly:

   ```bash
   docker compose exec app php artisan migrate --seed --force
   ```

7. Create the first super administrator interactively. The password is entered through a hidden prompt, not a command-line argument:

   ```bash
   docker compose exec app php artisan hmis:make-super-admin admin@your-authority.example
   ```

8. Change the temporary password at first login, create facility accounts and assign least-privilege roles.
9. Configure the external TLS reverse proxy to forward to `127.0.0.1:8080` (or the chosen `HTTP_PORT`). Ensure Laravel receives correct HTTPS/proxy headers. Verify HTTPS, secure cookies, `/up`, login and logout.
10. Run the full test suite in staging:

    ```bash
    docker compose exec app php artisan test
    docker compose exec app php artisan route:list
    ```

## Operational commands

```bash
docker compose ps
docker compose logs -f app
docker compose exec app php artisan about
docker compose exec app php artisan migrate:status
docker compose exec app php artisan optimize:clear
docker compose restart app nginx
```

Do not run `migrate:fresh` against any environment containing data.

## Backup and restore

Create a database dump:

```bash
BACKUP_DIR=/secure/backup/path scripts/docker-backup.sh
```

Restore requires an explicit typed confirmation:

```bash
scripts/docker-restore.sh /secure/backup/path/ojodu_hmis_YYYYMMDDTHHMMSSZ.sql.gz
```

Back up the private `app_storage` Docker volume separately using an approved encrypted volume-backup process. Store database and document backups off-server, restrict access, define retention, and test restoration. A database dump alone does not back up uploaded documents.

## Important build reproducibility note

No `composer.lock` is currently included. The Dockerfile resolves Composer dependencies during image build to make the scaffold buildable, which is not sufficiently reproducible for a regulated production deployment. In a controlled CI environment, resolve and review dependencies, commit the generated `composer.lock`, then change the Dockerfile to use `composer install` against that lock file. Run dependency vulnerability review before release.

## Known limitations

- This Docker configuration has not been built or run here.
- External TLS termination, trusted-proxy configuration, SMTP, monitoring, alerting and off-site backup storage need deployment-specific configuration.
- The current application still needs database migrations, Laravel feature tests, security testing, clinical validation and privacy approval.
