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

# Local environment and test data

> Configure local HMIS settings and keep development data separate from clinical data.

The committed `.env.example` is the source for available local variables. Copy it to `.env`, then change only the values required by your chosen runtime.

## Core local settings

| Variable           | Native default                | Docker value                     | Purpose                                              |
| ------------------ | ----------------------------- | -------------------------------- | ---------------------------------------------------- |
| `APP_ENV`          | `local`                       | `local`                          | Enables local behavior                               |
| `APP_DEBUG`        | `true`                        | `true`                           | Displays development errors; never use in production |
| `APP_URL`          | Local Laravel URL             | `http://localhost:8080`          | URL generation and passkey origin                    |
| `APP_KEY`          | Generated by `composer setup` | Generate a local key             | Encryption and signed values                         |
| `DB_CONNECTION`    | `sqlite`                      | Overridden to `pgsql` by Compose | Database driver                                      |
| `QUEUE_CONNECTION` | `database`                    | `database`                       | Queue backend                                        |
| `SESSION_DRIVER`   | `database`                    | `database`                       | Session backend                                      |
| `CACHE_STORE`      | `database`                    | `database`                       | Cache backend                                        |
| `MAIL_MAILER`      | `log`                         | `log`                            | Prevents delivery of real mail                       |

## Generate a key

For native setup:

```powershell theme={null}
php artisan key:generate
```

For a Docker-only setup after the image is built, print a key and place it in `.env`:

```powershell theme={null}
docker compose run --rm --no-deps app php artisan key:generate --show
```

Do not reuse a local key in staging or production.

## Test-data rules

* Use invented names, identifiers, addresses, barcodes, accession numbers, and study identifiers.
* Do not copy screenshots, database dumps, DICOM studies, HL7 messages, ASTM messages, or logs containing real patient data.
* Store reusable sanitized samples in the repository only after a second person confirms that direct and indirect identifiers are removed.
* Treat generated API tokens as secrets even when the database is disposable.
* Route development mail to logs or a local mail catcher.

<Warning>
  Never restore a production database or PACS volume to a workstation. Use an approved de-identification process before clinical data leaves the production boundary.
</Warning>

## Development seeding

`DatabaseSeeder` creates reference data and a known administrator account. It is designed for disposable development environments.

```powershell theme={null}
php artisan db:seed
```

For a retained local database, use the safer production-style sequence from [initial configuration](/platform/initial-configuration) instead.

## Changing branches

After switching application branches:

```powershell theme={null}
composer install
npm install
php artisan migrate
npm run build
php artisan optimize:clear
```

Use `docker compose ... up -d --build` instead when working in Docker Desktop.