Deploying Monica

Introduction

Monica is an open-source personal relationship management (PRM) system designed to help you organize and remember the important details about the people in your life. Unlike traditional CRMs focused on sales, Monica is built for personal relationships, helping you remember birthdays, track conversations, and maintain meaningful connections with friends and family.

Built with Laravel and Vue.js, Monica provides a clean, intuitive interface for documenting interactions, setting reminders, and storing information about your contacts. The self-hosted nature ensures your personal data remains private and under your control.

Key highlights of Monica:

Contact Management: Store detailed information about people in your life
Relationship Tracking: Document connections between contacts
Activity Logging: Record conversations, calls, and activities
Reminders: Never forget birthdays, anniversaries, or follow-ups
Notes and Documents: Attach notes, files, and photos to contacts
Journal: Keep a personal diary integrated with contacts
Gift Ideas: Track gift ideas and giving history
Tasks: Manage contact-related tasks and to-dos
Debt Tracking: Record money lent or borrowed
Life Events: Document important milestones
Groups: Organize contacts into categories
API Access: Integrate with other applications
Privacy-Focused: Self-hosted with no data sharing

This guide covers deploying Monica on Klutch.sh, setting up the database, and configuring your personal CRM.

Why Deploy Monica on Klutch.sh

Deploying Monica on Klutch.sh provides excellent advantages:

Simplified Deployment: Klutch.sh automatically builds and deploys Monica. Push to GitHub, and your personal CRM deploys automatically.

Persistent Storage: Attach volumes for database, uploads, and configuration that persist across updates.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your personal data.

GitHub Integration: Connect your repository for automatic deployments.

Environment Variable Management: Securely store database credentials and application secrets.

Custom Domains: Use your own domain for a personalized experience.

Always-On Availability: Access your relationship data from anywhere, anytime.

Prerequisites

Before deploying Monica on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and containerization
MySQL/MariaDB database (can be provisioned on Klutch.sh)
(Optional) SMTP credentials for email reminders
(Optional) A custom domain

Understanding Monica Architecture

Monica is a standard Laravel application:

Laravel Backend: Handles all business logic, API, and authentication.

Vue.js Frontend: Provides the interactive user interface.

MySQL Database: Stores contacts, activities, reminders, and all user data.

Queue Worker: Processes background jobs like email sending.

Scheduler: Triggers reminder notifications and maintenance tasks.

Preparing Your Repository

Repository Structure

monica-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile:

FROM monica:latest

# Environment configuration
ENV APP_KEY=${APP_KEY}
ENV APP_URL=${APP_URL}
ENV APP_ENV=production
ENV APP_DEBUG=false

# Database configuration
ENV DB_CONNECTION=mysql
ENV DB_HOST=${DB_HOST}
ENV DB_DATABASE=${DB_DATABASE}
ENV DB_USERNAME=${DB_USERNAME}
ENV DB_PASSWORD=${DB_PASSWORD}

# Mail configuration
ENV MAIL_MAILER=${MAIL_MAILER:-smtp}
ENV MAIL_HOST=${MAIL_HOST}
ENV MAIL_PORT=${MAIL_PORT:-587}
ENV MAIL_USERNAME=${MAIL_USERNAME}
ENV MAIL_PASSWORD=${MAIL_PASSWORD}
ENV MAIL_FROM_ADDRESS=${MAIL_FROM_ADDRESS}

# Optional configuration
ENV DEFAULT_MAX_STORAGE_SIZE=${DEFAULT_MAX_STORAGE_SIZE:-512}
ENV CHECK_VERSION=false

# Expose port
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

Environment Variables Reference

Variable	Required	Default	Description
`APP_KEY`	Yes	-	Laravel encryption key
`APP_URL`	Yes	-	Public URL of your Monica instance
`DB_HOST`	Yes	-	MySQL database host
`DB_DATABASE`	Yes	-	Database name
`DB_USERNAME`	Yes	-	Database username
`DB_PASSWORD`	Yes	-	Database password
`MAIL_HOST`	No	-	SMTP server host
`MAIL_PORT`	No	587	SMTP port
`MAIL_USERNAME`	No	-	SMTP username
`MAIL_PASSWORD`	No	-	SMTP password
`MAIL_FROM_ADDRESS`	No	-	Sender email address
`DEFAULT_MAX_STORAGE_SIZE`	No	512	Max upload storage in MB

Deploying Monica on Klutch.sh

Generate Application Key

Create a Laravel application key:

php artisan key:generate --show

Or generate a base64 string:

echo "base64:$(openssl rand -base64 32)"

Provision MySQL Database

Set up a MySQL/MariaDB instance for Monica.

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Monica deployment"
git remote add origin https://github.com/yourusername/monica-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a project named “monica” or “personal-crm”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

In deployment settings:

Select HTTP as the traffic type
Set the internal port to 80

Set Environment Variables

Configure your environment:

Variable	Value
`APP_KEY`	Your generated Laravel key
`APP_URL`	`https://your-app-name.klutch.sh`
`DB_HOST`	Your MySQL host
`DB_DATABASE`	`monica`
`DB_USERNAME`	Your database user
`DB_PASSWORD`	Your database password

Attach Persistent Volumes

Add volumes for persistent data:

Mount Path	Recommended Size	Purpose
`/var/www/html/storage`	10 GB	Uploads and cache

Deploy Your Application

Click Deploy to build and launch Monica.

Run Database Migrations

After deployment, run migrations:

php artisan migrate

Create Your Account

Navigate to https://your-app-name.klutch.sh/register to create your account.

Using Monica

Adding Contacts

Click Add Contact
Enter basic information:
- Name
- Gender
- Birthday
- How you met
Save and add more details later

Contact Information

Each contact can include:

Work Information: Company, job title
Contact Info: Phone, email, social profiles
Addresses: Home, work, other locations
Food Preferences: Favorites and allergies
Pets: Names and species
Custom Fields: Any additional data

Logging Activities

Record interactions with contacts:

Open a contact’s profile
Click Add Activity
Select activity type (call, email, meeting, etc.)
Add date and description
Include other participants if applicable

Setting Reminders

Never forget important dates:

Navigate to contact profile
Click Add Reminder
Set date and frequency
Add description
Choose notification method

Relationships

Document connections between contacts:

Open a contact profile
Go to Relationships section
Click Add Relationship
Select type (partner, child, friend, etc.)
Link to another contact

Features Overview

Journal

Keep a personal diary:

Write daily entries
Link entries to contacts
Track moods and weather
Rate your day

Gift Ideas

Manage gift giving:

Record gift ideas for contacts
Track gifts given and received
Note occasions and preferences

Debt Tracking

Manage money lent or borrowed:

Record debts with amounts
Track partial payments
Set repayment reminders

Documents

Attach files to contacts:

Upload photos
Store documents
Link to memories

Data Import/Export

Importing Contacts

Import from other sources:

Navigate to Settings > Import
Upload CSV or vCard file
Map fields to Monica fields
Review and import

Exporting Data

Export your data:

Go to Settings > Export
Choose format (JSON, SQL)
Download backup

API Access

Integrate with other tools:

Generate API token in settings
Use REST API for automation
Build custom integrations

Troubleshooting

Email Reminders Not Sending

Verify SMTP configuration
Check mail queue processing
Review Laravel logs

Slow Performance

Ensure adequate database resources
Check cache configuration
Review query performance

Upload Failures

Verify storage permissions
Check upload size limits
Review PHP configuration

Clear browser cookies
Check session configuration
Verify database connectivity

Additional Resources

Conclusion

Monica on Klutch.sh provides a private, personal CRM for maintaining meaningful relationships. With features for tracking interactions, setting reminders, and documenting the details that matter, Monica helps you be more thoughtful and present in your personal connections. The self-hosted approach ensures your intimate personal data stays under your control, while Klutch.sh handles the deployment complexity, letting you focus on the people in your life.