docs/setup.md

# Setup & configuration

For the quick version — just running the app — see the root [README](../README.md#getting-started). This covers the rest: running without Docker, every configuration option, and the test suite.

## Run with Docker

The only requirement is Docker with the Compose plugin.

```bash
docker compose up -d
```

This runs a multi-stage build — a Node stage compiles the Vue frontend, then a PHP 8.3 + Apache stage (Alpine-based; apk's own prebuilt packages rather than compiling PHP from source, which is most of why the image is ~90MB rather than several times that) bakes in the PHP source and the built SPA — applies migrations, and serves the whole app at <http://localhost:8080>: the SPA at `/` (assets and all) and the REST API under `/api` (e.g. `curl http://localhost:8080/api/health`). Unknown paths fall back to the SPA shell for client-side routing.

- A **[Mailpit](https://mailpit.axllent.org/)** container (the maintained MailHog successor — one ~15 MB Go binary, messages kept in memory) also starts. The API sends all email to it; read it at <http://localhost:8025>. Set `MAIL_TRANSPORT=mail` or `=smtp` (with `MAIL_SMTP_*`) to send for real.
- The image is the artifact: PHP source and the compiled frontend are copied in at build time, not bind-mounted. Rebuild to pick up any code change: `docker compose up -d --build`. For iterating on the frontend, run the Vite dev server on the host instead (see [web/README.md](../web/README.md)).
- The SQLite database and the generated JWT signing key live in the `storage` named volume, mounted at `/var/www/storage`, so they survive `docker compose restart` / `down` + `up`.
- `docker compose down -v` removes the volume and gives you a clean database.
- Override settings via the environment or a `.env` file in the repo root (Compose substitutes `APP_DEBUG`, `JWT_SECRET`, `JWT_TTL` — see [docker-compose.yml](../docker-compose.yml)).

## Run without Docker

Requires PHP 8.1+ with the `pdo_sqlite` and `mbstring` extensions, plus [Composer](https://getcomposer.org/). On Fedora:

```bash
sudo dnf install php-cli php-pdo php-mbstring composer
```

### Setup

```bash
composer install
cp .env.example .env      # optional; sane defaults are used without it
composer migrate          # creates storage/database.sqlite and its tables
```

### Running

```bash
composer serve            # http://localhost:8080  (php -S localhost:8080 -t public)
```

Any web server can serve the API as long as the document root is `public/` and unknown paths fall through to `public/index.php`. `public/.htaccess` also serves a built frontend from `public/` (copy `web/dist/` there) and only falls back to `index.php` for `/api` and when no `index.html` is present.

The frontend itself still needs its own toolchain — see [web/README.md](../web/README.md).

## Configuration

All settings are optional environment variables (read from `.env` or the real environment). See [.env.example](../.env.example).

| Variable | Default | Purpose |
|----------|---------|---------|
| `APP_DEBUG` | `false` | Include exception details in error responses |
| `DATABASE_PATH` | `storage/database.sqlite` | SQLite file location |
| `JWT_SECRET` | auto-generated into `storage/secret.key` | Token signing key |
| `JWT_TTL` | `86400` | Token lifetime in seconds |
| `APP_ALLOW_REGISTRATION` | `true` | When `false`, a magic link is only ever sent to an existing address — an unknown one is silently ignored, so no new accounts get created |
| `MAGIC_LINK_RESEND_SECONDS` | `60` | Minimum gap before a magic link can be resent to the same address (sign-in or email-change). Docker Compose overrides this to `0`, so links resend immediately in development |
| `APP_URL` | `http://localhost:8080` | Base URL used to build magic links (`http://localhost:5173` for a host `npm run dev`) |
| `WEBAUTHN_RP_ID` | `APP_URL`'s host | Passkey relying party ID (domain). Must be `localhost` or a real domain over HTTPS — a LAN IP won't work |
| `WEBAUTHN_RP_NAME` | `Projects` | Passkey relying party display name, shown in the browser/OS prompt |
| `MAIL_TRANSPORT` | `mail` | `mail` (PHP `mail()`), `smtp`, or `log` (append to a file) |
| `MAIL_FROM` / `MAIL_FROM_NAME` | `no-reply@todo.test` / `Projects` | Envelope sender |
| `MAIL_LOG_PATH` | `storage/mail.log` | Where `log` transport writes |
| `MAIL_SMTP_HOST` / `_PORT` / `_USERNAME` / `_PASSWORD` / `_ENCRYPTION` | — / `587` / — / — / `tls` | Used only when `MAIL_TRANSPORT=smtp` |

Standalone, SMTP is opt-in and the API otherwise falls back to PHP's `mail()`. Under Docker Compose the default is `MAIL_TRANSPORT=smtp` pointed at the bundled Mailpit container (`mailpit:1025`, no auth/TLS); open <http://localhost:8025> to read what was "sent".

## Tests

```bash
composer install         # installs phpunit (require-dev)
vendor/bin/phpunit
```

Each test run applies every file in `migrations/*.sql` to a fresh SQLite database, so it always exercises the current schema from scratch.
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00			`# Setup & configuration`

Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			`For the quick version — just running the app — see the root [README](../README.md#getting-started). This covers the rest: running without Docker, every configuration option, and the test suite.`
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00
			`## Run with Docker`

			`The only requirement is Docker with the Compose plugin.`

			```bash
			`docker compose up -d`
			```

Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			This runs a multi-stage build — a Node stage compiles the Vue frontend, then a PHP 8.3 + Apache stage (Alpine-based; apk's own prebuilt packages rather than compiling PHP from source, which is most of why the image is ~90MB rather than several times that) bakes in the PHP source and the built SPA — applies migrations, and serves the whole app at <http://localhost:8080>: the SPA at `/` (assets and all) and the REST API under `/api` (e.g. `curl http://localhost:8080/api/health`). Unknown paths fall back to the SPA shell for client-side routing.
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00
Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			- A [Mailpit](https://mailpit.axllent.org/) container (the maintained MailHog successor — one ~15 MB Go binary, messages kept in memory) also starts. The API sends all email to it; read it at <http://localhost:8025>. Set `MAIL_TRANSPORT=mail` or `=smtp` (with `MAIL_SMTP_*`) to send for real.
			- The image is the artifact: PHP source and the compiled frontend are copied in at build time, not bind-mounted. Rebuild to pick up any code change: `docker compose up -d --build`. For iterating on the frontend, run the Vite dev server on the host instead (see [web/README.md](../web/README.md)).
			- The SQLite database and the generated JWT signing key live in the `storage` named volume, mounted at `/var/www/storage`, so they survive `docker compose restart` / `down` + `up`.
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00			- `docker compose down -v` removes the volume and gives you a clean database.
Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			- Override settings via the environment or a `.env` file in the repo root (Compose substitutes `APP_DEBUG`, `JWT_SECRET`, `JWT_TTL` — see [docker-compose.yml](../docker-compose.yml)).
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00
			`## Run without Docker`

Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			Requires PHP 8.1+ with the `pdo_sqlite` and `mbstring` extensions, plus [Composer](https://getcomposer.org/). On Fedora:
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00
			```bash
			`sudo dnf install php-cli php-pdo php-mbstring composer`
			```

			`### Setup`

			```bash
			`composer install`
			`cp .env.example .env # optional; sane defaults are used without it`
			`composer migrate # creates storage/database.sqlite and its tables`
			```

			`### Running`

			```bash
			`composer serve # http://localhost:8080 (php -S localhost:8080 -t public)`
			```

Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			Any web server can serve the API as long as the document root is `public/` and unknown paths fall through to `public/index.php`. `public/.htaccess` also serves a built frontend from `public/` (copy `web/dist/` there) and only falls back to `index.php` for `/api` and when no `index.html` is present.
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00
Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			`The frontend itself still needs its own toolchain — see [web/README.md](../web/README.md).`
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00
			`## Configuration`

Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			All settings are optional environment variables (read from `.env` or the real environment). See [.env.example](../.env.example).
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00
			`\| Variable \| Default \| Purpose \|`
			`\|----------\|---------\|---------\|`
			\| `APP_DEBUG` \| `false` \| Include exception details in error responses \|
			\| `DATABASE_PATH` \| `storage/database.sqlite` \| SQLite file location \|
			\| `JWT_SECRET` \| auto-generated into `storage/secret.key` \| Token signing key \|
			\| `JWT_TTL` \| `86400` \| Token lifetime in seconds \|
			\| `APP_ALLOW_REGISTRATION` \| `true` \| When `false`, a magic link is only ever sent to an existing address — an unknown one is silently ignored, so no new accounts get created \|
			\| `MAGIC_LINK_RESEND_SECONDS` \| `60` \| Minimum gap before a magic link can be resent to the same address (sign-in or email-change). Docker Compose overrides this to `0`, so links resend immediately in development \|
			\| `APP_URL` \| `http://localhost:8080` \| Base URL used to build magic links (`http://localhost:5173` for a host `npm run dev`) \|
			\| `WEBAUTHN_RP_ID` \| `APP_URL`'s host \| Passkey relying party ID (domain). Must be `localhost` or a real domain over HTTPS — a LAN IP won't work \|
			\| `WEBAUTHN_RP_NAME` \| `Projects` \| Passkey relying party display name, shown in the browser/OS prompt \|
			\| `MAIL_TRANSPORT` \| `mail` \| `mail` (PHP `mail()`), `smtp`, or `log` (append to a file) \|
			\| `MAIL_FROM` / `MAIL_FROM_NAME` \| `no-reply@todo.test` / `Projects` \| Envelope sender \|
			\| `MAIL_LOG_PATH` \| `storage/mail.log` \| Where `log` transport writes \|
			\| `MAIL_SMTP_HOST` / `_PORT` / `_USERNAME` / `_PASSWORD` / `_ENCRYPTION` \| — / `587` / — / — / `tls` \| Used only when `MAIL_TRANSPORT=smtp` \|

Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			Standalone, SMTP is opt-in and the API otherwise falls back to PHP's `mail()`. Under Docker Compose the default is `MAIL_TRANSPORT=smtp` pointed at the bundled Mailpit container (`mailpit:1025`, no auth/TLS); open <http://localhost:8025> to read what was "sent".
Reorganize docs: simple README + organized docs/ 2026-09-05 01:41:55 +01:00
			`## Tests`

			```bash
			`composer install # installs phpunit (require-dev)`
			`vendor/bin/phpunit`
			```

Un-hard-wrap all Markdown documentation 2026-09-05 02:29:08 +01:00			Each test run applies every file in `migrations/*.sql` to a fresh SQLite database, so it always exercises the current schema from scratch.