Habitica works on your Synology NAS - a simple docker setup to get your containers running

Photo by Thomas Despeyroux / Unsplash

Docker + Habitica = Winning at Life

Containers Jan 20, 2023

Habitica is a tool designed to give you maximum enjoyment from doing those things that you, well, don't necessarily enjoy. It helps you set up goals which reward you in-game, and is playable with friends and family.

I'm not going to go through the actual mechanics of it in this article - you can read up on that here at the habitica fandom wiki, but what I will do is show you how to get it going in docker.

As always, we have some...


  1. SSH access to your NAS (click the link if you don't know how to do that)
  2. Docker and docker-compose installed on your machine
  3. Git installed on your machine
  4. Sudo/root access (normally by using the same password as any user with admin permissions)

First steps

The setup method here uses git clone and a docker-compose up -d command which sets off a build tree in your directory.

  • SSH into your machine
  • Navigate to your root docker directory
  • Type git clone https://github.com/alexiswatson/habitica.git into your client and press Enter
  • Wait one while it clones and downloads the nearly 1.7GB repository to your machine
  • Once it's complete, type cd habitica and you should find yourself in a fully populated folder which includes both docker-compose.yml and docker-compose.dev.yml
Check to make sure that your habitica directory has a docker-entrypoint-initdb.d folder, and inside that is a mongo-init.js file, which is required for creating Parties and Groups. If there isn't make sure you add the folder and file, and copy the contents which can be found here into it

A little bit of configuration

We need to do a little bit of modification to our files here.


  • In your SSH teminal (make sure you're still in the habitica directory) past cp config.json.example config.json to copy and rename the file so you have a working config.json file
It's really not recommended to rename or delete the config.json.example file, just in case you need a fresh start at some point

The habitica docker notes suggest that if you need to change any ports in your compose file to avoid port conflicts, you should also change them in the config.json. DON'T DO THIS.

The truth is that to get habitica working, you don't actually need to change a thing in this file. Check it out as there are a lot of options to add things like payment methods and other integrations, but for now, let's move on.


We use the .dev.yml as for some reason the normal compose doesn't have MongoDB included.

Use whatever you normally use to edit this file. Take a look through and make sure that any ports: settings don't clash with existing containers, but even if you do, don't change any of the URL or port settings in the config.json, and don't change the BASE_URL variable in the docker-compose.dev.yml, which you'll want to look something like this:

      context: .
      dockerfile: ./Dockerfile-Dev
    command: ["npm", "run", "client:dev"]
      - server
      - BASE_URL=http://server:3000 #DON'T CHANGE
      - "8080:8080" #change before the `:` if you need to
      - .:/usr/src/habitica
      - /usr/src/habitica/node_modules
      - /usr/src/habitica/website/client/node_modules
      context: .
      dockerfile: ./Dockerfile-Dev
    command: ["npm", "start"]
      - mongo
      - NODE_DB_URI=mongodb://mongo/habitrpg
      - "3000:3000" #change before the `:` if you need to
      - .:/usr/src/habitica
      - /usr/src/habitica/node_modules
    image: mongo:4.2.8
      - "27017:27017"
    command: --replSet rs
      - ./docker-entrypoint-initdb.d/mongo-init.js:/docker-entrypoint-initdb.d/mongo-init.js:ro
    name: habitica
        - subnet: 172.xx.0.0/28 #change the xx to an unused docker subnet

I've modified the networks block here to create a default network called habitica, and I've removed the networks variable in the various service blocks because they're no longer needed. You don't need to, but for me it's a cleaner setup.

  • Change the subnet (replace the xx) to one that's not in use, but keep the /28 at the end
  • If you do have containers using either port 3000 or port 8080, modify the compose file so that the port number on the left or before the : reflects a port not yet in use
  • Don't change the BASE_URL
  • Save if you've made changes

Are you ready for this?

Building your containers

  • In your SSH terminal (again, we're still in the habitica directory) type in docker-compose -f docker-compose.dev.yml up -d which will start off your build

This will take some time. At points it may look like it's hung or it's not doing anything, but give it some time (a day is maybe too long).

You'll likely see a lot of npm warnings and things in red popping up here. They're likely not container-threatening, but it will advise you to run npm audit fix which you can do after your containers are created. Your choice if you want to, but you should see an output something like this:

And your containers are up! Or are they...

Check your logs

Your habitica_mongo_1 and habitica_server_1 containers should be fine, but chances are your client container will stop pretty soon. Checking the logs (docker logs habitica_client_1) should show the following:


Don't worry, this is fixable.

If you type cat /proc/sys/fs/inotify/max_user_watches, your output will likely be something like 8192. This isn't enough for Habitica (it's a bit of a resource hog to be honest). Below is how to solve.

Non-Synology users

You're going to want to type this into your terminal:

echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/50-max-user-watches.conf && sudo sysctl --system

Synology users

We don't have an /etc/sysctl.d/ directory, so it's a bit different.

  • Make sure you are elevated to root user by typing sudo -i, pressing Enter and inputting your admin password again
  • Paste and execute the following:
echo 524288 > /proc/sys/fs/inotify/max_user_watches

The above isn't persistent between reboots however, so you may want to create a task in Task Scheduler to make sure it executes on startup. Make sure you set the user to be root and the task to actually run on startup.

Are we done yet?!

Accessing the app

  • We've made a change to our system, so we need to reboot our client container with a docker restart habitica_client_1 command
  • Wait one...to five. Rebooting the client container means a lot of things need to happen under the hood before things will work
  • In your browser address bar, type in your server IP and the port you mapped for the client container (so if your ports: looked like 9090:8080 and your host IP on your LAN is then you'd type in

If all has gone well, you should get this screen:

Congratulations! Time to sign up and begin gamifying your life. There's a decent 'Getting Started' on the Habitica Wiki which I'd recommend you look through, otherwise start looking around and happy habit...ing.

A note on reverse proxies

I initially had an error when trying to set up a reverse proxy for Habitica, receiving an error saying that my habitica domain couldn't be proxied to http://server:3000. Which was confusing. So the below is for anyone who may run into a similar issue.

I use SWAG to manage my reverse proxies. I have container stacks on their own networks, and when I want to create a reverse proxy I connect the relevant container to SWAG's proxy network so that they can communicate. Turns out that for whatever reason, connecting the Habitica client container to the proxy network as well as the habitica network stopped it being able to communicate with the server and database containers. I haven't figured out why, but my workaround was to connect SWAG to the habitica network instead, and it works just fine.

Preshared Keys and more - SSH on Linux and Synology
An easy guide which explains how to access and use your SSH sessions to their fullest, including clients and logging in with preshared keys
Portainer - Easy Container Management for Docker
A step-by-step docker walkthrough to installing and configuring Portainer, your one-stop container-management resource
Local DNS to serve your apps via URL instead of IP
Tired of remembering a raft of port numbers to access your service GUIs? Here’s a way to access them all using easier-to-remember URLs


With very limited knowledge, PTS fell down the selfhosted rabbit hole after buying his first NAS in October 2020. You can find him on the Synology discord server (click the icon below)

Have some feedback or something to add? Comments are welcome!

Please note comments should be respectful, and may be moderated