Updating guides
Dawarich is a rapidly evolving project, and some changes may break compatibility with older versions. This page will serve as a record of the breaking changes and migration paths. Instructions for each version assume that you are updating from the previous version.
After each update, please make sure there is no jobs running in the Sidekiq interface (/sidekiq). If there are, please wait for them to finish. Once all jobs are finished, you can proceed with the update.
0.28.0
If you're updating from a version before 0.28.0, first read sections about most recent breaking changes. What was introduced in 0.27.0 was later reverted with some changes in 0.28.0. Please pay attention and read release notes before updating.
⚠️ This release includes a breaking change. ⚠️
Well, we're moving back to Sidekiq and Redis for background jobs and caching. Unfortunately, SolidQueue and SolidCache brought more problems than they solved. Please update your docker-compose.yml to use Redis and Sidekiq.
Before updating, you can remove dawarich_development_queue database from your postgres. All *.sqlite3 files in dawarich_sqlite_data volume can be removed as well.
networks:
dawarich:
services:
+ dawarich_redis:
+ image: redis:7.4-alpine
+ container_name: dawarich_redis
+ command: redis-server
+ networks:
+ - dawarich
+ volumes:
+ - dawarich_shared:/data
+ restart: always
+ healthcheck:
+ test: [ "CMD", "redis-cli", "--raw", "incr", "ping" ]
+ interval: 10s
+ retries: 5
+ start_period: 30s
+ timeout: 10s
...
dawarich_app:
image: freikin/dawarich:latest
container_name: dawarich_app
volumes:
- dawarich_public:/var/app/public
- dawarich_watched:/var/app/tmp/imports/watched
- dawarich_storage:/var/app/storage
- dawarich_db_data:/dawarich_db_data
- - dawarich_sqlite_data:/dawarich_sqlite_data
...
restart: on-failure
environment:
RAILS_ENV: development
+ REDIS_URL: redis://dawarich_redis:6379
DATABASE_HOST: dawarich_db
DATABASE_USERNAME: postgres
DATABASE_PASSWORD: password
DATABASE_NAME: dawarich_development
- # PostgreSQL database name for solid_queue
- QUEUE_DATABASE_NAME: dawarich_development_queue
- QUEUE_DATABASE_PASSWORD: password
- QUEUE_DATABASE_USERNAME: postgres
- QUEUE_DATABASE_HOST: dawarich_db
- QUEUE_DATABASE_PORT: 5432
- # SQLite database paths for cache and cable databases
- CACHE_DATABASE_PATH: /dawarich_sqlite_data/dawarich_development_cache.sqlite3
- CABLE_DATABASE_PATH: /dawarich_sqlite_data/dawarich_development_cable.sqlite3
...
depends_on:
dawarich_db:
condition: service_healthy
restart: true
+ dawarich_redis:
+ condition: service_healthy
+ restart: true
...
+ dawarich_sidekiq:
+ image: freikin/dawarich:latest
+ container_name: dawarich_sidekiq
+ volumes:
+ - dawarich_public:/var/app/public
+ - dawarich_watched:/var/app/tmp/imports/watched
+ - dawarich_storage:/var/app/storage
+ networks:
+ - dawarich
+ stdin_open: true
+ tty: true
+ entrypoint: sidekiq-entrypoint.sh
+ command: ['sidekiq']
+ restart: on-failure
+ environment:
+ RAILS_ENV: development
+ REDIS_URL: redis://dawarich_redis:6379
+ DATABASE_HOST: dawarich_db
+ DATABASE_USERNAME: postgres
+ DATABASE_PASSWORD: password
+ DATABASE_NAME: dawarich_development
+ APPLICATION_HOSTS: localhost
+ BACKGROUND_PROCESSING_CONCURRENCY: 10
+ APPLICATION_PROTOCOL: http
+ PROMETHEUS_EXPORTER_ENABLED: false
+ PROMETHEUS_EXPORTER_HOST: dawarich_app
+ PROMETHEUS_EXPORTER_PORT: 9394
+ SELF_HOSTED: "true"
+ STORE_GEODATA: "true"
+ logging:
+ driver: "json-file"
+ options:
+ max-size: "100m"
+ max-file: "5"
+ healthcheck:
+ test: [ "CMD-SHELL", "pgrep -f sidekiq" ]
+ interval: 10s
+ retries: 30
+ start_period: 30s
+ timeout: 10s
+ depends_on:
+ dawarich_db:
+ condition: service_healthy
+ restart: true
+ dawarich_redis:
+ condition: service_healthy
+ restart: true
+ dawarich_app:
+ condition: service_healthy
+ restart: true
...
volumes:
dawarich_db_data:
- dawarich_sqlite_data:
dawarich_shared:
dawarich_public:
dawarich_watched:
dawarich_storage:
0.27.4 - 2025-06-06
Update your docker-compose.yml to use SQLite database names for queue, cache and cable databases.
...
dawarich_app:
image: freikin/dawarich:latest
container_name: dawarich_app
volumes:
- dawarich_public:/var/app/public
- dawarich_watched:/var/app/tmp/imports/watched
- dawarich_storage:/var/app/storage
- dawarich_db_data:/dawarich_db_data
+ - dawarich_sqlite_data:/dawarich_sqlite_data
...
restart: on-failure
environment:
...
DATABASE_NAME: dawarich_development
+ # PostgreSQL database name for solid_queue
+ QUEUE_DATABASE_NAME: dawarich_development_queue
+ QUEUE_DATABASE_PASSWORD: password
+ QUEUE_DATABASE_USERNAME: postgres
+ QUEUE_DATABASE_PORT: 5432
+ QUEUE_DATABASE_HOST: dawarich_db
# SQLite database paths for cache and cable databases
- QUEUE_DATABASE_PATH: /dawarich_db_data/dawarich_development_queue.sqlite3
- CACHE_DATABASE_PATH: /dawarich_db_data/dawarich_development_cache.sqlite3
- CABLE_DATABASE_PATH: /dawarich_db_data/dawarich_development_cable.sqlite3
+ CACHE_DATABASE_PATH: /dawarich_sqlite_data/dawarich_development_cache.sqlite3
+ CABLE_DATABASE_PATH: /dawarich_sqlite_data/dawarich_development_cable.sqlite3
volumes:
dawarich_db_data:
+ dawarich_sqlite_data:
dawarich_shared:
dawarich_public:
dawarich_watched:
dawarich_storage:
...
0.27.0
If you're updating from a version before 0.27.0, first read sections about most recent breaking changes. What was introduced in 0.27.0 was later reverted with some changes in 0.28.0. Please pay attention and read release notes before updating.
Starting 0.27.0, Dawarich is using SolidQueue and SolidCache to run background jobs and cache data. Before updating, make sure your Sidekiq queues (https://your_dawarich_app/sidekiq) are empty.
Moving to SolidQueue and SolidCache will require creating new SQLite databases, which will be created automatically when you start the app. They will be stored in the dawarich_db_data volume.
Background jobs interface is now available at /jobs page.
Please, update your docker-compose.yml and add the following:
dawarich_app:
image: freikin/dawarich:latest
container_name: dawarich_app
volumes:
- dawarich_public:/var/app/public
- dawarich_watched:/var/app/tmp/imports/watched
- dawarich_storage:/var/app/storage
+ - dawarich_db_data:/dawarich_db_data
...
environment:
...
DATABASE_NAME: dawarich_development
# SQLite database paths for secondary databases
+ QUEUE_DATABASE_PATH: /dawarich_db_data/dawarich_development_queue.sqlite3
+ CACHE_DATABASE_PATH: /dawarich_db_data/dawarich_development_cache.sqlite3
+ CABLE_DATABASE_PATH: /dawarich_db_data/dawarich_development_cable.sqlite3
0.26.0
Starting this version, Dawarich requires PostgreSQL 17 with PostGIS 3.5. If you haven't updated your database image yet, please consider doing so as suggested in the docs on the website. Simply replacing the image in the docker-compose.yml unfortunately doesn't work, as PostgreSQL 17 is not backwards compatible with 14 (which was used in previous versions).
If you have encountered problems with moving to a PostGIS image while still on Postgres 14, I collected a selection of compatible docker images for different CPU architectures, which you can also find in the docs. New users will be automatically provisioned with PostgreSQL 17 with PostGIS 3.5 with default docker-compose.yml file.
You still may use PostgreSQL 14, but no support will be provided for it starting this version. It's strongly recommended to update to PostgreSQL 17.
Changed
- Dawarich now uses PostgreSQL 17 with PostGIS 3.5 by default.
0.25.4
⚠️ This release includes a breaking change. ⚠️
Make sure to add dawarich_storage volume and SELF_HOSTED: "true" to your docker-compose.yml file. Example:
...
dawarich_app:
image: freikin/dawarich:latest
container_name: dawarich_app
volumes:
- dawarich_public:/var/app/public
- dawarich_watched:/var/app/tmp/imports/watched
+ - dawarich_storage:/var/app/storage
...
environment:
+ SELF_HOSTED: "true"
...
dawarich_sidekiq:
image: freikin/dawarich:latest
container_name: dawarich_sidekiq
volumes:
- dawarich_public:/var/app/public
- dawarich_watched:/var/app/tmp/imports/watched
+ - dawarich_storage:/var/app/storage
...
environment:
+ SELF_HOSTED: "true"
volumes:
dawarich_db_data:
dawarich_shared:
dawarich_public:
dawarich_watched:
+ dawarich_storage:
In this release we're changing the way import files are being stored. Previously, they were being stored in the raw_data column of the imports table. Now, they are being attached to the import record. All new imports will be using the new storage, to migrate existing imports, you can use the bundle exec rake imports:migrate_to_new_storage task. Run it in the container shell.
This is an optional task, that will not affect your points or other data. Big imports might take a while to migrate, so be patient.
Also, you can now migrate existing exports to the new storage using the bundle exec rake exports:migrate_to_new_storage task (in the container shell) or just delete them.
If your hardware doesn't have enough memory to migrate the imports, you can delete your imports and re-import them.
0.25.0
Visits and places
The release page: https://github.com/Freika/dawarich/releases/tag/0.25.0
There is a known issue when data migrations are not being run automatically on some systems. If you're experiencing issues when opening map page, trips page or when trying to see visits, try executing the following command in the Console:
Errors on the map page
If on the map page you see errors like this:
undefined method `y' for nil:NilClass
This means that the data migration job that supposed to move coordinates from longitude and latitude columns to lonlat column on points table was not run. We can fix this by running the following command in the Console:
User.includes(:tracked_points).find_each do |user|
user.tracked_points.where(lonlat: nil).update_all('lonlat = ST_SetSRID(ST_MakePoint(longitude, latitude), 4326)')
end
This will update the lonlat column for all the points. After this, the map should work again.
If this script failed with a killed message, you have ran out of memory. Simply repeat the command again, it will pick up from the last processed point.
If you experiencing something similar to the following error:
Caused by PG::UniqueViolation: ERROR: duplicate key value violates unique constraint "index_points_on_lonlat_timestamp_user_id"
DETAIL: Key (lonlat, "timestamp", user_id)=(0101000020E6100000E2E5E95C51522140B6D8EDB3CA184940, 1737716451, 2) already exists.
This means, you have some points with the same coordinates, timestamp and user_id. This usually should not happen, but we can remove the duplicates. Run the following command in the Console:
user_id = 2 # (your user id based on error message above)
timestamp = 1739235618 # (your problematic timestamp, based on error message above)
points = Point.where(user_id: user_id, timestamp: timestamp)
points.size # This will return number of duplicated points
points.drop(1).each(&:destroy) # This will remove all but the first point.
After this, run the script from the previous step again. Repeat, if you see the same for different timestamp or user_id.
The "your user is not active" errors / 401 errors
In the Console, run the following command:
User.find_by(email: "your@email.com").update(status: :active)
This will activate your account.
0.23.6
In this release, Dawarich switched to using PostGIS as the database image.
In your docker-compose.yml change image for postgres:
dawarich_db:
- image: postgres:14.2-alpine
+ image: postgis/postgis:14-3.5-alpine
shm_size: 1G
container_name: dawarich_db
If you're on an ARM system and already updated your postgres to 17, use ghcr.io/baosystems/postgis:17-3.5 image instead of postgis/postgis:14-3.5-alpine. Depending on which postgres version you're using, you can select a fitting docker image to replace your old one here: https://github.com/ImreSamu/docker-postgis?tab=readme-ov-file#recommended-versions-for-new-users
Also, have a look at the moving to postgis guide.
0.22.1
- Gems caching volume from the
docker-compose.ymlfile. #638
To update existing docker-compose.yml to new changes, refer to the following:
dawarich_app:
image: freikin/dawarich:latest
...
volumes:
- - dawarich_gem_cache_app:/usr/local/bundle/gems
...
dawarich_sidekiq:
image: freikin/dawarich:latest
...
volumes:
- - dawarich_gem_cache_app:/usr/local/bundle/gems
...
volumes:
dawarich_db_data:
- dawarich_gem_cache_app:
- dawarich_gem_cache_sidekiq:
dawarich_shared:
dawarich_public:
dawarich_watched:
0.22.0
Docker-related files were moved to the docker directory and some of them were renamed. Before upgrading, study carefully changes in the docker/docker-compose.yml file and update your docker-compose file accordingly, so it uses the new files and commands. Copying docker/docker-compose.yml blindly may lead to errors.
No volumes were removed or renamed, so with a proper docker-compose file, you should be able to upgrade without any issues.
To update existing docker-compose.yml to new changes, refer to the following:
dawarich_app:
image: freikin/dawarich:latest
...
- entrypoint: dev-entrypoint.sh
- command: ['bin/dev']
+ entrypoint: web-entrypoint.sh
+ command: ['bin/rails', 'server', '-p', '3000', '-b', '::']
...
dawarich_sidekiq:
image: freikin/dawarich:latest
...
- entrypoint: dev-entrypoint.sh
- command: ['bin/dev']
+ entrypoint: sidekiq-entrypoint.sh
+ command: ['bundle', 'exec', 'sidekiq']
0.21.0
The dawarich_db service now can use a custom postgresql.conf file.
As @tabacha pointed out in #549, the default shm_size for the dawarich_db service is too small and it may lead to database performance issues. This release introduces a shm_size parameter to the dawarich_db service to increase the size of the shared memory for PostgreSQL. This should help database with peforming vacuum and other operations. Also, it introduces a custom postgresql.conf file to the dawarich_db service.
To mount a custom postgresql.conf file, you need to create a postgresql.conf file in the dawarich_db service directory and add the following line to it:
dawarich_db:
image: postgres:14.2-alpine
shm_size: 1G
container_name: dawarich_db
volumes:
- dawarich_db_data:/var/lib/postgresql/data
- dawarich_shared:/var/shared
+ - ./postgresql.conf:/etc/postgresql/postgresql.conf # Provide path to custom config
...
healthcheck:
test: [ "CMD-SHELL", "pg_isready -U postgres -d dawarich_development" ]
interval: 10s
retries: 5
start_period: 30s
timeout: 10s
+ command: postgres -c config_file=/etc/postgresql/postgresql.conf # Use custom config
To ensure your database is using custom config, you can connect to the container (docker exec -it dawarich_db psql -U postgres) and run SHOW config_file; command. It should return the following path: /etc/postgresql/postgresql.conf.
An example of a custom postgresql.conf file is provided in the postgresql.conf.example file.