# Project pack: Monica @ 32028ce

Facts about **Monica** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Monica is a private address book with a memory. Keep notes about friends and family: how you met, their children's names, their pets, gift ideas, money you lent and what you talked about last time. It emails you before birthdays and other dates, nudges you to stay in touch, and has a journal for your own life. It is for your eyes only, never a social network, and it runs on your own server. The pinned code is Monica 4, the stable version.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. A manual PHP + MySQL + web server install is documented but judged too heavy for a one-sitting non-technical setup. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://raw.githubusercontent.com/monicahq/monica/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/monicahq/monica
- Pinned commit: `32028ce3ce79cef38df5d27a297e5b20680f0065`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/monicahq/monica/archive/32028ce3ce79cef38df5d27a297e5b20680f0065.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://github.com/monicahq/monica/tree/4.x/docs
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just you or your household), you must offer them your source code under the same licence. Private use has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/monicahq/monica bespoke-monica
  cd bespoke-monica
  git checkout --detach 32028ce3ce79cef38df5d27a297e5b20680f0065
  # Prepare development requirements and local configuration first.
  # Setup notes: app on :8080, phpMyAdmin on :3000, MailHog on :8025 (settings in .env.dev)
  docker-compose -f docker-compose.dev.yml up --build
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  docker network create monica
  docker run -d --name monica-db --network monica -e MYSQL_RANDOM_ROOT_PASSWORD=true -e MYSQL_DATABASE=monica -e MYSQL_USER=homestead -e MYSQL_PASSWORD=secret -v monica-db:/var/lib/mysql mariadb:11
  docker run -d --name monica --network monica -e DB_HOST=monica-db -e APP_KEY="base64:$(openssl rand -base64 32)" -v monica-data:/var/www/html/storage -p 8080:80 monica
  # wait for the database setup to finish, then open http://localhost:8080 and register.
  # Copy APP_KEY from `docker inspect monica` and keep it safe. Change the database password before real use.
  ```
- Tools these commands use: Docker, or PHP 8.1+, Composer, a web server (Apache, Nginx or Caddy) and MySQL or MariaDB, Node.js 20 and Yarn 1 to build the front end, About 1.5 GB of RAM for builds and updates
- Develop: `docker-compose -f docker-compose.dev.yml up --build   # app on :8080, phpMyAdmin on :3000, MailHog on :8025 (settings in .env.dev)`
- Test: `yarn test   # migrates the 'testing' database, then runs phpunit, phpstan and psalm`
- Check/lint: `yarn lint   # eslint for the Vue and JavaScript code`
- Stack: php, javascript, vue (Laravel 9, Vue 2, Laravel Mix, Bootstrap 4, Laravel Passport, sabre/dav). Difficulty for a non-developer with an AI: **moderate**. A classic Laravel app. Pages are Blade templates in resources/views/ with Vue 2 components in resources/js/components/. Logic lives in app/Services/, web and API controllers in app/Http/Controllers/, models in app/Models/. Which sections show on a contact page, genders, contact field types, activity types and reminder rules are all settings.
Personal data: **yes**. Stored in: A MySQL or MariaDB database plus uploaded photos and documents in storage/ (the monica-data volume in Docker). Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/monica/32028ce/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/monica/32028ce/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/monica/32028ce/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/monica/32028ce/r3/SKILL.md)