How to run Monica personal CRM on Dokku

Published on August 28, 2022

I left my home country right after university and I worked and lived in a few countries since then. I’ve met lots of amazing people but I’ve always struggled to remember contact details and important dates for everyone.

As we get busier with life, time rushes on faster and faster and sometimes I realise that it’s months since I checked in on people. When I do, I have forgotten the last things we talked about and what’s important in their lives.

Monica personal CRM

Monica is a privacy focused relationship management tool. You run it on your own server so no-one has access to the data but you. There are no social networking features and it doesn’t parse or interpret your data in any way.

Monica CRM (from Monica HQ)
Monica CRM (from Monica HQ)

(Click for larger screenshot)

If you’re old like me you might have used Facebook for things like birthdays in the decade 2008-2018ish but most of us have deleted their data on there, or are ready to.

Monica replaces that functionality in a privacy-focused way. It removes that final blocker and allows you to delete your social media accounts.

Dokku self hosting

Dokku is a heroku-like PaaS platform that you can run on your own server. It’s perfect for a solo developer to run multiple applications on a VM and it makes handling security, networking, 0-downtime deploying, let’s encrypt https etc. a breeze!

Heroku has just announced that they’re removing their free plan so now is a fantastic time to try Dokku on a $5 Digital Ocean droplet

I host 3 apps on my Dokku instance on digital ocean, they all have different databases and urls. The only infrastructure work I have to do is log in once a quarter and update apt packages and Dokku itself.

I have an article at that describes how to setup a Dokku instance. You can follow that to setup Dokku and then come back here. There is also excellent documentation on digital ocean describing how to setup Dokku.

You will need a url configured if you want to set up tls for the Monica app (you should do this).

So for the next steps I assume you have an instance of Dokku running on a server and you’re ssh’d into it.

The following steps describe how to set up Monica on your Dokku instance.

1. Add a swap file to your Dokku host

Note: These commands are run on your Dokku server

The Monica build process takes a bit of memory. If you’re on a cheap server like a $4 digital ocean droplet you might get errors that the build failed with no details.

This is likely an out of memory issue and digital ocean doesn’t configure a swap for you by default so you should add one. This is optional but recommended.

First you should check if you have a swap file set. If the swapon show command returns nothing then you don’t have a swap and you should add one.

# check if a swap file is set
sudo swapon --show

# check how much free space you have
free -h

Run these commands to setup your swap file on ubuntu. I set a 1GB swap file on my droplet.

# create the allocation
sudo fallocate -l 1G /swapfile

# change permissions for swap
sudo chmod 600 /swapfile

# make it a swap file
sudo mkswap /swapfile

# turn it on
sudo swapon /swapfile

Now add the configuration to fstab so there is still a swap on your server after any reboots.

sudo cp /etc/fstab /etc/fstab.bak
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
sudo sysctl vm.swappiness=10

The digital ocean article recommends turning down the default swappiness because this is a server not a desktop. Sounds like a great idea so let’s do that.

To permanently force swapiness you have to edit a file

sudo nano /etc/sysctl.conf

and add a line at the end


and also set this to be the current value on your running system

sudo sysctl vm.swappiness=10

Digital ocean have a details article on setting a swap file here.

2. Add Monica as a Dokku application

Note: These commands are run on your Dokku server

First thing we need is a Dokku application

dokku apps:create monica-crm

3. Add a database for Monica

Next we need a database. Monica is built around MySQL but I prefer to use MariaDB instead of MySQL. First we install the MariaDB plugin and then create and link a new database instance.

# install the MariaDB plugin
dokku plugin:install mariadb

# create the database instance
dokku mariadb:create monica-crm-db

# link the Dokku database to the Dokku application
dokku mariadb:link monica-crm-db monica-crm

4. Add networking for Dokku app

Next we need to setup some networking for our application. I’m assuming you setup a domain when configuring your Dokku instance, and that you’ve already configured letsencrypt plugin.

# set a domain for the app (the default will be e.g.
dokku domains:set monica-crm

# set a config variable for email address. This is required by lets encrypt
dokku config:set --no-restart monica-crm

# now register a new domain with letsencrypt and install the certificate
dokku letsencrypt:enable monica-crm

5. Add Monica configuration settings

Before you run Monica in a production-like environment you will have to configure some settings for the application. These are set with environment variables.

# APP_URL is used in emails sent by monica so that links work as expected
# APP_DISABLE_SIGNUP blocks anyone from signing up to your instance. We will set this to true later!
# APP_KEY is a security key and you should generate a random set of 32 alphanumeric characters
# APP_ENV tells the application to use tls if set to production - we want this because we have tls with lets encrypt
dokku config:set --no-restart monica-crm APP_URL= APP_DISABLE_SIGNUP=false APP_KEY=CHANGETORANDOMALPHANUMERIC APP_ENV=production

6. Configure email sending for Monica

One of the nice features of Monica are reminder emails for important events or any regular catchups you want to have. Monica needs some email provider so that it can send your emails.

This is optional but very worthwhile.

I have an SMTP email service that I pay for, so that’s what I use. You can use other providers like mailgun or AWS SES. There are more details on the Monica documentation site on how to configure other email sending providers.

Email settings are also environment variables.

# Set the various environment variables for email. These are fairly self-explanatory.
dokku config:set --no-restart monica-crm MAIL_MAILER=smtp MAIL_PORT=587 MAIL_PASSWORD=mysmtppassword MAIL_ENCRYPTION=tls

7. Fork and clone the Monica application

NOTE: These commands are run on your local machine!

We fork Monica on Github or using gh cli, then clone our copy Monica to a local folder. This is so that we can make some changes to the code for Dokku.

# if you have gh cli you can fork (and clone - it will ask you) from your terminal
gh repo fork monicahq/monica

# clone Monica - change the username (skip if you already cloned)
git clone

Monica is built to run directly from the repository on Heroku but we must make minor edits for Dokku.

First file is a new file .buildpacks in the root with this content list the buildpacks to use.

Next is an edit to the existing app.json file where we add a cron.

"cron": [
         "command": "php artisan schedule:run",
         "schedule": "*/10 * * * *"

Now commit and push those 2 changes to your forked Monica instance.

8. Build Monica on Dokku for the first time!

Note: These commands are run on your local machine

# you have to add a remote to the local repository that points to your dokku server
git remote add dokku dokku@the_ip_or_hostname_of_your_dokku_server:monica-crm

# and push the code! This will take a while because it kicks off a build of the application
git push dokku main:master

If that worked as expected it will print lines at the end like

======> Application deployed:

Go to the url! Monica will ask you to set up your account.

Monica login screen
Monica login screen

9. A final security clean up for Monica

Remember the APP_DISABLE_SIGNUP variable from before. Now that you have set up your account you probably don’t want anyone else signing up for an account on your server. So let’s shut off that possibility.

On your Dokku server:

dokku config:set monica-crm APP_DISABLE_SIGNUP=true


I’ve just started using Monica and enjoying it so far. It has a simple interface which is just perfect. Time will tell if it helps me as a personal CRM!

Dokku provides a nice alternative to Heroku’s free tier. Even though it’s not free, it can be run on a very cheap host like a $5 Digital Ocean droplet.

Once you have setup your Dokku instance you can add new apps very quickly and Dokku makes it easy for a solo-developer to manage multiple applications. I recommend checking it out!

Darragh ORiordan

Hi! I'm Darragh ORiordan.

I live and work in Sydney, Australia building and supporting happy teams that create high quality software for the web.

I also make tools for busy developers! Do you have a new M1 Mac to setup? Have you ever spent a week getting your dev environment just right?

My Universal DevShell tooling will save you 30+ hours of configuring your Windows or Mac dev environment with all the best, modern shell and dev tools.

Get DevShell here: ✨

Read more articles like this one...

List of article summaries


Building an AI generated game with Stable Diffusion and data from Wikipedia

Last week I released a game called Doodle:ai.

In the game you’re shown AI generated images and you have to guess the Wikipedia topic it used to create the game.


Easiest way to optimise images for web

Here is how I optimise all pngs and jpgs in a folder for publishing to the web.


Start tracking DORA metrics for your team in just 15 minutes with Apache Dev Lake

DORA (DevOps Research and Assessment) metrics are an excellent way for engineering organisations to measure and improve their performance.

Up until now, monitoring the DORA metrics across Github, Jira, Azure Devops etc required custom tooling or a tedious manual process.

With Apache Dev Lake you can get beautiful reporting for DORA metrics on your local machine in as little as 15 minutes (honestly!).

From Google Sheets to Grafana
From Google Sheets to Grafana


A summary of NDC Sydney 2022 Developer Conference

I attended my first in-person conference for more than 3 years last week! NDC is one of the more well-known developer conferences in Australia and New Zealand. It’s a 5 day conference with 3 days of talks and 2 days of workshops.

There’s so much to learn across all the streams so I try to take notes for each of the talks to quickly reference them later. This post contains all my notes. I’ll add the relevant videos to talks later if they’re released.

A reminder that these notes are just my notes. They’re paraphrased and summarised from what the speaker actually said. Each speakers would have provided must more clarity and went into more detail during their pressos!