Free tools Windows power users keep installed
One-click scans. No signup required.
To self-host Monica Personal CRM on an Ubuntu VPS, run Monica’s official Apache Docker image with a MariaDB container, keep both data directories on persistent volumes, and place the application behind a reverse proxy that terminates HTTPS. A practical deployment needs a generated APP_KEY, database credentials, production mode, and a backup plan.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
This guide answers “How do I self-host Monica on an Ubuntu VPS?”, provides a working Docker Compose pattern, explains how much RAM Monica needs, and shows how to put it behind HTTPS without exposing MariaDB to the internet.
As an Amazon Associate I earn from qualifying purchases.
What you need before installing Monica
Monica is an open-source personal relationship management application. The software can be run on your own server without a license fee; hosted Monica is a separate paid service. A self-hosted installation leaves server administration, updates, TLS, backups and account security to you.
VPS requirements
- An Ubuntu VPS with a public IPv4 address or another reachable address.
- A domain name such as
crm.example.compointed at the VPS. - At least 1.5 GB of RAM. The Monica project README gives this as a recommendation for successful builds and updates; normal runtime use may be lighter, but smaller machines can fail during update builds.
- Root or sudo access.
- Enough disk space for the operating system, Docker images, Monica’s uploaded data and MariaDB’s database files.
RAM, disk growth, firewall rules, backup frequency and the VPS provider are operational choices rather than fixed Monica requirements. If you expect several users, frequent file uploads or long retention, choose more storage and memory than the minimum recommendation.
#1 Best Overall
Choose the container or manual route
| Decision | Docker Compose | Manual installation |
|---|---|---|
| Setup reproducibility | Usually strongest: application and database are declared together. | More dependent on host package versions and configuration. |
| Host-package control | Less control because the application runs in an image. | More control over PHP, the web server and system services. |
| Web-server complexity | The Apache image serves HTTP; a reverse proxy still handles public HTTPS. An FPM image requires a separate web server. | You configure Apache, Nginx or Caddy and PHP yourself. |
| Updates and backups | You still update images, run migrations and back up volumes. | You update PHP, Composer dependencies, application files and the database yourself. |
The rest of this article uses Docker Compose because it is the most repeatable path on an Ubuntu VPS. A manual-installation section appears later for administrators who do not want containers.
Install Docker and Compose on Ubuntu
Use the Docker installation path supported for your Ubuntu release, then install the Compose plugin. Package names differ between Ubuntu releases and between the Ubuntu archive and Docker’s repository, so follow the current package instructions for your release rather than copying an obsolete repository line.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →After installation, verify both components:
docker --version
docker compose versionIf you want to run Docker as your normal account, add that account to the Docker group and start a new login session. Remember that membership in this group grants root-equivalent control over the host.
sudo usermod -aG docker $USERUntil the new session is active, prefix Docker commands with sudo. Before deploying Monica, apply Ubuntu security updates and configure a firewall so only SSH and the public web ports are reachable. Do not allow the MariaDB port from the internet.
Create the Monica Compose project
Make a private application directory
- Create a directory owned by your administrative account and enter it.
- Create a separate environment file for secrets.
- Set restrictive permissions so other unprivileged users cannot read the credentials.
mkdir -p ~/monica
cd ~/monica
touch .env
chmod 600 .envGenerate a strong APP_KEY
Monica uses APP_KEY to protect application data. Generate it once and keep it unchanged for the life of the installation. The project documentation gives this command:
echo -n 'base64:'; openssl rand -base64 32Copy the complete output, including the base64: prefix, into .env. Losing or changing this key can make existing encrypted data unreadable, so include the environment file in your secure backup procedure.
Write the environment file
Use long, unique passwords for both the Monica database user and the MariaDB root account. The values below are examples; replace every password and the domain with your own values.
APP_ENV=production
APP_KEY=base64:PASTE_THE_GENERATED_VALUE_HERE
DB_HOST=db
DB_DATABASE=monica
DB_USERNAME=monica
DB_PASSWORD=replace-with-a-long-random-password
DB_ROOT_PASSWORD=replace-with-a-different-long-random-password
APP_URL=https://crm.example.comKeep .env out of public repositories, screenshots and support bundles. If you use source control for the Compose file, commit only a redacted example such as .env.example.
Create compose.yaml
The following pattern runs Monica’s Apache variant and MariaDB. The application listens only on the VPS loopback address, leaving the reverse proxy as the public entry point. The named volumes preserve application storage and database files when containers are recreated.
services:
app:
image: monicahq/monica:apache
restart: unless-stopped
env_file:
- .env
depends_on:
- db
ports:
- "127.0.0.1:8080:80"
volumes:
- monica_storage:/var/www/html/storage
db:
image: mariadb:latest
restart: unless-stopped
environment:
MYSQL_DATABASE: ${DB_DATABASE}
MYSQL_USER: ${DB_USERNAME}
MYSQL_PASSWORD: ${DB_PASSWORD}
MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
volumes:
- monica_db:/var/lib/mysql
volumes:
monica_storage:
monica_db:The Apache image serves Monica’s HTTP application internally. If you choose an FPM image instead, you must add and configure a separate web server; an FPM container does not serve public HTTP by itself. For production, pin image tags that you have checked against Monica’s release notes instead of allowing an unreviewed image change to arrive unexpectedly through latest.
Start Monica and finish first-time setup
- Validate the Compose file and environment interpolation:
docker compose config- Start both services in the background:
docker compose up -d- Watch the application log while the database initializes:
docker compose logs -f appOn the first start, wait for database initialization and migrations to complete. A temporary connection error while MariaDB is still starting is normal; wait a little and inspect the logs before changing credentials.
- Run Monica’s production setup command once after the initial start:
docker compose exec app php artisan setup:production- Open the site through the local proxy address during testing or through your domain after the reverse proxy is configured, then create the first user account.
Do not run the production setup command repeatedly as a routine restart step. Run it again only when Monica’s upgrade instructions specifically require it.
Check container state
docker compose ps
docker compose logs --tail=100 app
docker compose logs --tail=100 dbThe app should remain in an “Up” state, and MariaDB should remain running without an authentication or initialization loop. If you change database credentials after the database volume has already been initialized, the new values do not rewrite existing MariaDB users automatically; either restore the original credentials or change the database user deliberately from inside MariaDB.
Put Monica behind HTTPS
Do not treat the Compose port mapping as a finished public deployment. Monica’s documentation requires production mode and HTTPS for an internet-facing installation. The Apache Compose example serves HTTP and is intended to run behind a proxy; it does not issue certificates or provide TLS by itself.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Reverse-proxy layout
The recommended traffic flow is:
- DNS points
crm.example.comto the VPS. - The host reverse proxy listens on ports 80 and 443.
- The proxy obtains and renews a certificate with your chosen ACME-compatible certificate service.
- The proxy forwards requests to
http://127.0.0.1:8080. - MariaDB remains on the private Docker network and has no host port mapping.
A minimal Nginx-style proxy block looks like this after your certificate paths are configured:
server {
listen 443 ssl http2;
server_name crm.example.com;
ssl_certificate /etc/ssl/your-service/fullchain.pem;
ssl_certificate_key /etc/ssl/your-service/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
}Use the equivalent settings in Apache or Caddy if that is your host standard. Redirect plain HTTP to HTTPS, permit only the proxy’s public ports through the firewall, and confirm that APP_URL uses the final HTTPS URL. Never expose port 3306 publicly merely to make troubleshooting easier.
Test the public path
- Visit the HTTPS URL and confirm the browser shows a valid certificate for the exact hostname.
- Sign in, create a test contact and reload it to verify that requests are reaching Monica through the proxy.
- Check browser developer tools for mixed-content warnings; these usually indicate an incorrect application URL or missing forwarded-protocol header.
- Stop the proxy temporarily and confirm the application is not reachable from the internet through port 8080. The loopback binding should prevent direct external access.
Persist and back up Monica data
Monica’s application data is under /var/www/html/storage. The Compose file maps that directory to monica_storage. MariaDB data is stored separately in monica_db. Backing up only the Compose file is not a backup of your contacts.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11What to back up
- The
.envfile, protected as a secret. - The
monica_storagevolume, including uploaded files and generated application data. - A consistent dump of the MariaDB database, or a database-volume backup performed while MariaDB is safely stopped.
- Your reverse-proxy configuration and certificate-renewal configuration.
Use a database dump for portability
A logical dump is generally easier to restore to another MariaDB instance than copying live database files. Use the database credentials from .env, write the dump to a directory with restricted permissions, and encrypt it before sending it off the VPS. Schedule backups according to how much contact history you can afford to lose, and keep at least one copy outside the server.
Rank #4
Test a restoration on a separate temporary instance. A backup that has never been restored is an assumption, not a recovery plan.
Protect the volumes
Named volumes survive docker compose down unless you explicitly remove them with the volume-removal option. Do not run destructive cleanup commands until you have verified the backup and identified the exact volume names:
docker volume ls
docker compose down
docker compose up -dFor a planned migration, stop writes, create the database dump and storage archive, copy the Compose and environment files securely, then start the replacement stack and restore the data before allowing users to sign in.
Updating Monica safely
- Read the release notes for the Monica image version you intend to deploy and check compatibility with your MariaDB version.
- Make a fresh database dump and storage backup.
- Record the current image tags and running configuration with
docker compose config. - Pull the reviewed image and recreate the app:
docker compose pull app
docker compose up -d app- Watch logs for migrations and run
docker compose exec app php artisan setup:productiononly if the release instructions call for it. - Test login, contact search, notes, reminders and uploaded files before declaring the update complete.
Keep the previous image tag available until the new release has passed those checks. Never delete the database volume as an update shortcut.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Manual installation without containers
Containers are optional. Monica’s project README lists PHP 8.1 or newer, an HTTP server with PHP support such as Apache, Nginx or Caddy, Composer and MySQL for a manual installation. It recommends at least 1.5 GB of RAM because update builds can fail on smaller systems even when everyday use is lighter.
Manual prerequisites
- Ubuntu with PHP 8.1 or newer and the PHP extensions required by the Monica release.
- Apache, Nginx or Caddy configured to serve the Monica public directory.
- Composer available to the deployment user.
- MySQL, with a database and least-privilege application account.
- HTTPS termination and a persistent backup strategy.
The manual path gives you direct control over host packages and service files, but every PHP, web-server and Composer update becomes your responsibility. Follow the version-specific installation instructions from the Monica project for the exact checkout, environment generation, database migration and web-root settings. Do not combine a container’s storage directory with a manual install unless you have planned the migration and understand the file ownership changes.
Best Value
Troubleshoot common failures
The app cannot connect to MariaDB
- Confirm
DB_HOST=db; inside Compose, the service name is the hostname. - Check that
DB_DATABASE,DB_USERNAMEandDB_PASSWORDmatch the values used when MariaDB initialized. - Inspect
docker compose logs dbfor initialization or permission errors. - Wait for MariaDB to finish its first startup before restarting the app repeatedly.
“APP_KEY is missing” or encrypted data errors
Check that APP_KEY is present in .env, includes the base64: prefix and is passed to the app through env_file. Do not generate a new key to solve an existing-data error; recover the original key from your protected backup.
The browser shows a 502 or connection refused
Confirm the app container is running, port 8080 is bound on loopback, and the proxy’s upstream is exactly 127.0.0.1:8080. A 502 from the proxy is different from a Monica application error: first inspect the proxy error log, then the app log.
HTTPS redirects incorrectly or links use HTTP
Set APP_ENV=production, use an HTTPS APP_URL, pass X-Forwarded-Proto https, and reload the proxy. Clear an old browser session only after verifying the server-side settings.
The VPS runs out of memory during an update
Keep at least the README’s 1.5 GB recommendation available, stop unrelated services, and check memory and swap before retrying. If builds still fail, move to a larger VPS rather than repeatedly killing containers during a migration.
Is self-hosting Monica worth it?
Self-hosting is a good fit when you want control of the server and data, can maintain Ubuntu and Docker, and will actually test backups. Docker Compose makes the initial deployment reproducible, while HTTPS, updates, credentials and recovery remain operational work. Manual installation is reasonable when host-level PHP control matters more than container isolation. In either case, the non-negotiable pieces are a strong APP_KEY, persistent application and database storage, production mode, HTTPS and a tested restore procedure.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
