Sep 9, 2024 3 min read

Monica: Your Self-Hosting Setup and Management Guide

Monica: Your Self-Hosting Setup and Management Guide
Table of Contents

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:

  1. Install dependencies:

sudo apt update

sudo apt install -y php-cli php-mysql mysql-server nginx git unzip curl

  1. 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

  1. Configure .env with your database credentials and app settings.

  2. Migrate the database:


php artisan migrate --force

  1. 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/views directory.

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!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.