dawarich/docs/How_to_install_Dawarich_on_Unraid.md

How to install Dawarich on Unraid

Warning

Do not use autoupdate and do not update any Dawarich container without backing up your data first and checking for breaking changes in the updating guides!

Dawarich is still in beta and a rapidly evolving project, and some changes may break compatibility with older versions.

This guide is written for:

• Unraid OS 7.1.4
• Dawarich 0.33.0

Installation methods: CA Templates vs. Docker Compose

For Dawarich to run 4 docker containers are required:

• dawarich_db - PostgreSQL database
• dawarich_redis - Redis database
• dawarich_app - Dawarich web application
• dawarich_sidekiq - Sidekiq worker (for background jobs)

Note

Some containers depend on others to be running first. Therefore this guide will follow this order: dawarich_db >> dawarich_redis >> dawarich_app >> dawarich_sidekiq.

Usually all 4 containers are created and started together using Docker Compose. Unraid does not support Docker Compose natively. Instead, it uses its own implementation of DockerMan for managing Docker containers via Community Applications (CA) plugin.

However, there is a Docker Compose Manager plugin that can be used to setup and run Dawarich using Docker Compose. This method is not covered in this guide.

Feel free to contribute a PR if you want to add it.

Support for Unraid CA Templates

Important

Since Freika is not maintaining the Unraid CA templates, all Unraid-related issues should be raised in the appropriate repositories or Unraid forum threads:

• dawarich_db & dawarich_redis Github and Unraid forum
• dawarich_app & dawarich_sidekiq Github and Unraid forum

There is an official PostGIS CA you can use for dawarich_db and an official redis CA you can use for dawarich_redis. However, if you don’t want to set up the correct volume paths, environment variables, health-checks and arguments by yourself, Pa7rickStar has created CA for dawarich_db and dawarich_redis which are preconfigured for an easy Dawarich installation.

For dawarich_app and dawarich_sidekiq grtgbln aka. nwithan8 on Github is maintaining Unraid CA templates.

Note

All 4 CA use the official docker hub repositories of redis, PostGIS, Dawarich and Sidekiq.

Installation

Important

This guide assumes you will name the containers dawarich_redis, dawarich_db, dawarich_app and dawarich_sidekiq. You can use other names, but make sure to adjust the settings accordingly or use IP addresses and ports instead.

1. (Optional) Setup user-defined bridge network

The docker-compose file usually used to set up Dawarich creates a user-defined bridge network for Dawarich containers so they are isolated in their own network and are still able to communicate with each other. This step is optional, but it is a good practice to do so.

Note

Check out this video on YouTube if you want to learn how different network drivers work in Docker.

1. Set Unraid to preserve user-defined networks

By default user created networks are removed from Unraid when Docker is being restarted. This is done to prevent potential conflicts with the automatic generation of custom networks. If you want to use a user-defined bridge network for Dawarich containers, you need to change this behavior. Go to Settings -> Docker -> enable Advanced View and set Preserve user defined networks to Yes. Docker has to be stopped so that the setting can be changed.

Warning

Change this setting to preserve user defined networks, but it is the responsibility of the user to ensure these entries work correctly and are conflict free.

2. Create the user-defined bridge network

To create an user-defined bridge network called dawarich, open the terminal on your Unraid server and run:

docker network create dawarich

Note

You can check if the network was created successfully by running:

docker network ls

2. Install dawarich_db container

Install the dawarich_db CA template from Pa7rickStar's Repository.

• The container Name dawarich_db will be used by other containers instead of an IP address and port. If you use this method, you don't need set the Database port in this template (there is also no need to access the database directly).
• You can leave the Extra Parameters as is.
• --restart=always in the Extra Parameters field (you have to turn on ADVANCED VIEW in the top right corner to see this field) will make sure the container is restarted automatically if it crashes.

  Note

  This will cause the container to start after you boot the host even if autostart is set to off.

• If you have set up a user-defined bridge network in the first step, select it under Network Type. Otherwise, leave it at bridge.
• The default Database username is fine. You should set a strong Database password.

  Note

  You can change the Database password without having the old one from the Unraid (host) Terminal by running:

  docker exec -it dawarich_db \
   psql -U postgres -d postgres -c "ALTER ROLE postgres WITH PASSWORD 'NEW_STRONG_PASSWORD';"
  

  Replace NEW_STRONG_PASSWORD with your new password and keep the ''.

3. Install dawarich_redis container

Install the dawarich_redis CA template from Pa7rickStar's Repository.

• The container Name dawarich_redis will be used by other containers instead of an IP address.
• --restart=always in the Extra Parameters field (you have to turn on ADVANCED VIEW in the top right corner to see this field) will make sure the container is restarted automatically if it crashes.

  Note

  This will cause the container to start after you boot the host even if autostart is set to off.

• If you have set up a user-defined bridge network in the first step, select it under Network Type. Otherwise, leave it at bridge.
• If you have no port conflicts, leave the Redis Port at default value. Otherwise, change it to a free port. This port has to be used later in the dawarich_app and dawarich_sidekiq containers.

4. Install dawarich_app container

Install the dawarich_app CA template from grtgbln's Repository.

• You do not need to change the container Name to dawarich_app as other containers won't establish a connection by themselves.

• Set Extra Parameters (you have to turn on ADVANCED VIEW in the top right corner to see this field) to:

  --entrypoint=web-entrypoint.sh --restart=on-failure --health-cmd='wget -qO- http://127.0.0.1:3000/api/v1/health | grep -q "\"status\"[[:space:]]*:[[:space:]]*\"ok\"" || exit 1' --health-interval=10s --health-retries=30 --health-start-period=30s --health-timeout=10s
  

  Note

  The --restart=on-failure parameter will make sure the container is restarted automatically if it crashes. This might cause the container to start after you boot the host even if autostart is set to off.

• If you have set up a user-defined bridge network in the first step, select it under Network Type. Otherwise, leave it at bridge.

• If you have no port conflicts, leave the Web Port at default value. Otherwise, change it to a free port. This port will be used to access the Dawarich web interface. In this case make sure to set the same port for WebUI (default value is http://[IP]:[PORT:3000]/).

• If you haven't changed any file paths in the previous containers, you can leave all the paths at default values. Otherwise, set the correct paths.

• Set the Redis URL to redis://dawarich_redis:6379/0 if you are using the container name dawarich_redis and the default port in the redis container.

• Set the PostGIS - Host to dawarich_db if you are using the container name dawarich_db. Otherwise use the IP address.

• Set PostGIS - Username, PostGIS - Password and PostGIS - Database to the same values you used in the setup of your dawarich_db container.

• For any other settings refer to the official documentation for environment variables and settings.

  Warning

  The CA template sets PHOTON_API_HOST to photon.komoot.io and STORE_GEODATA to true by default. This means the container will try to translate your location data (longitude, latitude) to addresses, cities etc. and save the result in the database. In order to do so, the app will send your data to the service provider, which might raise privacy concerns. If you don't want this behavior you should leave PHOTON_API_HOST empty! You cold also set up your own reverse geocoding service.

5. Install dawarich_sidekiq container

Install the dawarich_sidekiq CA template from grtgbln's Repository.

• The same notes as for the dawarich_app container apply here.

• Set Extra Parameters (you have to turn on ADVANCED VIEW in the top right corner to see this field) to:

  --entrypoint=sidekiq-entrypoint.sh --restart=on-failure --health-cmd='pgrep -f sidekiq >/dev/null || exit 1' --health-interval=10s --health-retries=30 --health-start-period=30s --health-timeout=10s
  

  Note

  The --restart=on-failure parameter will make sure the container is restarted automatically if it crashes. This might cause the container to start after you boot the host even if autostart is set to off.

Warning

The CA template sets PHOTON_API_HOST to photon.komoot.io and STORE_GEODATA to true by default. This means the container will try to translate your location data (longitude, latitude) to addresses, cities etc. and save the result in the database. In order to do so, the app will send your data to the service provider, which might raise privacy concerns. If you don't want this behavior you should leave PHOTON_API_HOST empty! You cold also set up your own reverse geocoding service.

Post installation

1. Starting the containers

The containers should start automatically when you are setting them up for the first time. If not, start them manually in the Unraid web interface. Use the correct order: dawarich_db >> dawarich_redis >> dawarich_app >> dawarich_sidekiq.

2. Health checks

According to the Unraid documentation, colored health indicators next to each container’s icon are shown in the Unraid web interface when health checks are configured in the containers. Depending on the selected theme the container health might be indicated by text in the uptime column instead.

You can check the health status of the containers from the Unraid (host) Terminal:

docker ps --format 'table {{.Names}}\t{{.Status}}'

This should show something like this:

root@tower# docker ps --format 'table {{.Names}}\t{{.Status}}'
NAMES              STATUS
dawarich_sidekiq   Up About a minute (healthy)
dawarich_app       Up About a minute (healthy)
dawarich_db        Up About a minute (healthy)
dawarich_redis     Up About a minute (healthy)

If not, you can check the health status of each container individually:

docker inspect --format '{{json .State.Health}}' dawarich_db | jq
docker inspect --format '{{json .State.Health}}' dawarich_redis | jq
docker inspect --format '{{json .State.Health}}' dawarich_app | jq
docker inspect --format '{{json .State.Health}}' dawarich_sidekiq | jq

Note

There is a difference between liveness and readiness probes. Simply put:

• liveness = "is the process up?"
• readiness = "can it do useful work?"

The health checks configured in the dawarich_app and dawarich_sidekiq containers are liveness probes. This means that they will show healthy as long as the main process is running, even if the application is not fully started yet. So it might take a while until Dawarich is actually ready to use, even if the health check shows healthy. This also means that the health check will show healthy even if the application is not fully functional (e.g. if it can not connect to the database). You should check the logs of the dawarich_app container for any errors if you suspect that something is wrong.

3. Check the logs

You should check the Logs of each container for any errors.

Note

You might see this warning in the dawarich_redis container:

# WARNING Memory overcommit must be enabled! Without it, a background save or replication may fail under low memory condition. Being disabled, it can also cause failures without low memory condition, see https://github.com/jemalloc/jemalloc/issues/1328. To fix this issue add 'vm.overcommit_memory = 1' to /etc/sysctl.conf and then reboot or run the command 'sysctl vm.overcommit_memory=1' for this to take effect.

The sysctl vm.overcommit_memory=1 command referenced there has to be run on the Unraid host (not in the container). As of now the author of this guide can not confidently advice on this, so please check the Unraid forum for help.

Setup Reverse Geocoding

Note

Please check out the Dawarich docs on reverse geocoding.

1. Install Photon container

If you want to set up your own reverse geocoding service install the Photon CA template from Pa7rickStar's Repository and change the environment variables to your liking.

• To reduce the load on the official Photon servers you can use the community mirrors.

• The default value for REGION is planet which might be more than you need.

  Warning

  Large file sizes! This might take more than 200GB depending on the selected region. See here for the available regions.

2. Post installation

Check the logs after the container started. Photon should download the index files for the REGION you set.

After the index files are downloaded and Photon is ready, you can check if it is working by opening in a webbrowser:

http://localhost:[PORT]/api?q=Berlin

3. Configure Photon for Dawarich

In your dawarich_app and dawarich_sidekiq containers:

• Set the Photon API - Host to [IP]:[PORT] of your Photon container (without the []).
• Set Photon API - Use HTTPS to false.
• Restart the containers in the correct order.

2025-10-07 by Pa7rickStar with contributions from nwithan8.