Reading the repo

Opening the box…

How to set up monica (monicahq/monica) · gitmanual

Assembly instructions

monicahq/monica

Personal CRM. Remember everything about your friends, family and business relationships.

Node.jsVitePHPLaravel#crm#family#friends#hacktoberfest

Difficulty: Involved
Time: 30 min or more
Stars: ★ 25,704
Activity: Updated this month
License: AGPL-3.0
Open issues: 794
Got it running: Be the first
Looked up: 2 h ago

Saved setup from 2 h ago

Start here

Website ↗beta.monicahq.comThe project's own site.In the browser ↗Open in GitHub CodespacesThe repo ships a dev container, so nothing to install.

Will it work on my device?

Yes, it runs on macOS

You'll build it yourself with Node.js, PHP.
It also needs MariaDB, Redis, Memcached, Meilisearch, Mail catcher running (Docker handles this).

Checking for

8 steps on macOS

Clone the repository

Needs Git: xcode-select --install

git clone https://github.com/monicahq/monica.git
cd monica

2
Install the required runtimes
Node.js 22.13.1, PHP ^8.3
```
brew install mise
mise install
```
3
Configure environment variables
Fill in secrets: APP_KEY, REDIS_PASSWORD, MAIL_PASSWORD, MEILISEARCH_KEY, TYPESENSE_API_KEY, TELEGRAM_BOT_TOKEN, UPLOADCARE_PUBLIC_KEY, UPLOADCARE_PRIVATE_KEY
```
cp .env.example .env
```
4
Start backing services
Needs: MariaDB, Redis, Memcached, Meilisearch, Mail catcher
```
brew install --cask docker  # Docker Desktop
docker compose -f docker-compose.yml up -d
```
If you see Cannot connect to the Docker daemon: start Docker Desktop (or the Docker service) first.

Install dependencies

corepack enable
yarn install
composer install

Set up the database / app

php artisan key:generate
php artisan migrate

7
Run it
Run each command in its own terminal.
```
yarn dev
php artisan serve
```
8
Run the tests
```
yarn test
```

Did you get it running?

No reports for macOS yet.

Still stuck? Get a written guide

Claude reads the 13 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.

Parts list

1×Node.js 22.13.1runtime
1×PHP ^8.3runtime
1×yarn yarn@4.6.0package manager
1×composer package manager
1×MariaDB service
1×Redis service
1×Memcached service
1×Meilisearch service
1×Mail catcher service

43× settings in .env

APP_NAME
APP_ENV
APP_KEYsecret
APP_DEBUG
APP_URL
APP_DISABLE_SIGNUP
APP_SHOW_DELETION_NOTICE
DB_CONNECTION
DB_TEST_DRIVER
LOG_CHANNEL
CACHE_STORE
QUEUE_CONNECTION
SESSION_DRIVER
REDIS_HOST
REDIS_PASSWORDsecret
REDIS_PORT
MAIL_MAILER
MAIL_HOST
MAIL_PORT
MAIL_USERNAME
MAIL_PASSWORDsecret
MAIL_ENCRYPTION
MAIL_FROM_ADDRESS
MAIL_FROM_NAME
MAIL_REPLY_TO_ADDRESS
MAIL_REPLY_TO_NAME
SCOUT_DRIVER
SCOUT_QUEUE
FULL_TEXT_INDEX
MEILISEARCH_URL
MEILISEARCH_KEYsecret
TYPESENSE_HOST
TYPESENSE_API_KEYsecret
TELEGRAM_BOT_TOKENsecret
TELEGRAM_BOT_URL
TELEGRAM_BOT_WEBHOOK_URL
DEFAULT_STORAGE_LIMIT
UPLOADCARE_PUBLIC_KEYsecret
UPLOADCARE_PRIVATE_KEYsecret
LOCATION_IQ_API_KEYsecret
MAPBOX_API_KEYsecret
MAPBOX_USERNAME
MAPBOX_CUSTOM_STYLE_NAME

Share this manual

Good to know

Dev Container config found — you can open it in VS Code Dev Containers or GitHub Codespaces for a zero-setup environment.
Tool versions pinned in .tool-versions — mise install (or asdf install) installs them all.

package.json scripts (9)

devvite
buildvite build && vite build --ssr
previewvite preview
linteslint *.js resources
formatprettier --write '**/*.{js,vue,css,scss,json,yml,md}'
postinstallhusky install
testphp artisan migrate:fresh --database=testing && php artisan db:seed --database=testing && vendor/bin/phpunit && vendor/bin/phpstan && vendor/bin/psalm
docker:builddocker build --cache-from monica-next -t monica-next -f scripts/docker/Dockerfile . && docker image prune -f
docker:rundocker run --name monica -p 8080:80 monica-next

Files we read (13)

.devcontainer/devcontainer.json

.env.example

.github/workflows/deploy.yml

.github/workflows/docker.yml

.github/workflows/lint.yml

.github/workflows/lock.yml

.github/workflows/release.yml

.github/workflows/tests.yml

.tool-versions

README.md

composer.json

docker-compose.yml

package.json

Branch main · 2,093 files in the repo

Opening the box…

Start here

Yes, it runs on macOS

8 steps on macOS

Clone the repository

Install the required runtimes

Configure environment variables

Start backing services

Install dependencies

Set up the database / app

Run it

Run the tests

Did you get it running?

Still stuck? Get a written guide