Monica is a powerful, open-source personal relationship management (PRM) tool designed to help users organize and manage their personal connections, track important dates, and stay on top of meaningful interactions. Self-hosting Monica gives you full control over your data, customization options, and ensures privacy without relying on third-party services. This guide will walk you through installing Monica, configuring it with Nginx, managing logs, creating backups, performing updates, and leveraging its unique features to maximize its potential.
Installing Monica
📦 Docker/Docker Compose Setup
Using Docker Compose is the most efficient way to deploy Monica. Here's how to set it up:
Create a docker-compose.yml file with the following configuration:
version: '3.7'
services:
monica:
image: monicahq/monicahq:latest
container_name: monica
ports:
- "8080:80"
environment:
- APP_KEY=base64:YOUR_APP_KEY_HERE
- APP_URL=http://yourdomain.com
- DB_HOST=db
- DB_DATABASE=monica
- DB_USERNAME=monica
- DB_PASSWORD=yourpassword
depends_on:
- db
volumes:
- ./monica_data:/var/www/html/storage
db:
image: mysql:5.7
container_name: monica_db
environment:
- MYSQL_DATABASE=monica
- MYSQL_USER=monica
- MYSQL_PASSWORD=yourpassword
- MYSQL_ROOT_PASSWORD=rootpassword
volumes:
- ./db_data:/var/lib/mysql
Run the following commands to deploy Monica:
docker-compose up -d
This command will pull the Monica and MySQL images, create the containers, and start the application.
🚀 Manual Installation
For manual installation on a Linux server, follow these steps:
- Install dependencies:
sudo apt update
sudo apt install -y php-cli php-mysql mysql-server nginx git unzip curl
- Clone and set up Monica:
git clone https://github.com/monicahq/monica.git
cd monica
composer install
cp .env.example .env
php artisan key:generate
-
Configure
.envwith your database credentials and app settings. -
Migrate the database:
php artisan migrate --force
- Start Monica using PHP's built-in server (or configure a production-grade web server):
php artisan serve --host=0.0.0.0 --port=8080
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
To serve Monica via Nginx, create a server block:
sudo nano /etc/nginx/sites-available/monica
Add the following content:
server {
listen 80;
server_name yourdomain.com;
root /var/www/monica/public;
index index.php index.html;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ /\.ht {
deny all;
}
}
Enable the configuration and reload Nginx:
sudo ln -s /etc/nginx/sites-available/monica /etc/nginx/sites-enabled/
sudo systemctl reload nginx
🔒 SSL/TLS Setup
Secure Monica with Let's Encrypt:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
Automate certificate renewal:
sudo crontab -e
Add this line to renew certificates automatically:
0 0 * * * certbot renew --quiet
🛠️ Testing and Reloading Nginx
Ensure the configuration is valid and reload Nginx:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging Monica
🗃️ Enabling Debug Logs
Modify the .env file to enable debug logging:
APP_DEBUG=true
Restart Monica for the changes to take effect.
📄 Viewing Logs
For Docker deployments, view logs with:
docker logs monica
For manual setups, access the logs in the storage/logs directory:
tail -f storage/logs/laravel.log
🛠️ Troubleshooting Common Issues
- Issue: "500 Internal Server Error"
Solution: Check the laravel.log file for the exact error and resolve missing dependencies or incorrect configurations.
- Issue: Database connection errors
Solution: Verify .env database settings and ensure the database container/service is running.
📤 Exporting Logs
Export logs to an ELK stack with Filebeat by configuring filebeat.yml to monitor Monica's log directory.
Backup and Restore
🗂️ File-Based Backups
Backup Monica's configuration and storage files:
tar -czvf monica_backup.tar.gz monica_data
🔄 Database Backups
Export the database:
docker exec -i monica_db mysqldump -u monica -pyourpassword monica > monica_db_backup.sql
Restore the database:
docker exec -i monica_db mysql -u monica -pyourpassword monica < monica_db_backup.sql
📅 Automated Backup Scripts
Create a cron job for periodic backups:
crontab -e
Add the following line:
0 2 * * * tar -czvf /backups/monica_$(date +\%F).tar.gz /path/to/monica_data && docker exec monica_db mysqldump -u monica -pyourpassword monica > /backups/monica_$(date +\%F).sql
Updating and Upgrading Monica
⬆️ Updating Docker Images
Update Monica's Docker image and redeploy:
docker-compose down
docker-compose pull
docker-compose up -d
🛠️ Manual Updates
For manual installations, pull the latest changes, update dependencies, and migrate:
git pull origin master
composer install
php artisan migrate --force
🔍 Checking for Updates
Monitor Monica's GitHub repository for releases and changelogs: Monica Releases
Leveraging Monica’s Unique Features
🔧 Enabling APIs
Activate the API by updating the .env file:
API_ENABLED=true
Access the API using cURL:
curl -X GET -H "Authorization: Bearer YOUR_API_KEY" https://yourdomain.com/api/contacts
🌟 Advanced Configurations
- Enable scheduled tasks for reminders using a cron job:
* * * * * php /path/to/monica/artisan schedule:run >> /dev/null 2>&1
- Customize branding by editing the
resources/viewsdirectory.
Wrapping Up
By following this guide, you’ve successfully deployed, configured, and optimized Monica for self-hosting. With its powerful features, self-hosting Monica gives you complete control over your data and the flexibility to tailor it to your needs. Start managing your relationships like a pro and explore its APIs and advanced settings to unlock even more potential!
