Spinning up Monica locally with seeded test data

[brycehans]

Easiest path is the Docker-based dev environment — it bundles MySQL so you don't have to provision a DB yourself.

1. Clone + env

git clone https://github.com/brycehans/monica.git monica && cd monica
cp .env.example .env

The dev container reads its own .env.dev via env_file: in the compose file (DB host mysql, db monica, user homestead / pass secret), so it works out of the box without further tweaks. The .env you just copied is for host-side php artisan commands; ignore it if you'll only drive Monica via the container.

2. Build front-end assets on the host

The dev compose mounts ./public/build:/var/www/html/public/build, so the container's Apache serves whatever the host last built. Run once before bringing the stack up — otherwise the mount overlays the image's baked-in assets with an empty directory and every blade page 500s on the missing manifest.json:

yarn install
yarn run prod

For ongoing iteration, yarn run watch rebuilds incrementally on file change; the container picks up the new bundle on the next request.

3. Bring up the stack

docker compose -f docker-compose.dev.yml up

That gives you:

• app on http://localhost:8082
• phpMyAdmin on :3000
• MailHog UI on :8025 (SMTP on :1025) — catches outbound mail so you can see reminder emails

If any of those ports are already taken (e.g. another Monica clone is already running), all five are overridable via env vars:

APP_PORT=8083 PHPMYADMIN_PORT=3001 MAILHOG_UI_PORT=8027 MAILHOG_SMTP_PORT=1027 STRIPE_MOCK_PORT=12112 \
  docker compose -f docker-compose.dev.yml up

4. (Non-Docker workflow only) Install PHP deps + key

Skip this section if you're using the Docker stack from step 3. The dev image already bakes in composer install, and the entrypoint auto-runs php artisan key:generate, migrations, and passport key generation on first boot. (yarn install + yarn run prod from step 2 cover the JS side either way — that step is required for both workflows now.)

If you're running Monica directly on the host instead, run these on the host:

composer install
php artisan key:generate

5. Seed the DB

php artisan setup:test

Inside the Docker app container, prefix with docker compose -f docker-compose.dev.yml exec app.

Logs in at admin@admin.com / admin0 with a populated account (20 fake contacts). Also creates a blank account at blank@blank.com / blank0 for empty-state screens.

---

That's it — log in via the browser and click around. Mail goes to MailHog at :8025 rather than the real internet, so reminder/notification flows are safe to trigger.