How to run Monica personal CRM on Dokku

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)

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 /2021/12/29/run-node-app-postgres-dokku-digital-ocean/ 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 $6 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

vm.swappiness=10

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 https://github.com/dokku/dokku-mariadb.git 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 app-name.yourdomain.com e.g. monica-crm.yourdomain.com)
dokku domains:set monica-crm monica.yourdomain.com

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

# 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=https://monica.yourdomain.com 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_HOST=smtp.mysmtpprovider.com MAIL_PORT=587 MAIL_USERNAME=[email protected] 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 [email protected]:mygithubusername/monica.git

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.

https://github.com/heroku/heroku-buildpack-php
https://github.com/heroku/heroku-buildpack-nodejs

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:
        http://monica.yourdomain.com
        https://monica.yourdomain.com

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

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

Summary

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!