How to Use Dawarich: The Beginner's Guide (First Deploy, First Tracker, and the Google Takeout Import)

CodexFuse Team · 2026-11-01T09:18:39.734Z · 14 min read

What Is Dawarich?

Dawarich is the self-hosted Google Timeline alternative: an open-source Rails web app that rebuilds Google's retired location-history timeline on a server you control, with an interactive map, trips, visits, stats, and a heatmap of everywhere you have been. That is the whole Dawarich Google Timeline pitch — your history, your server, a self hosted Google Timeline alternative that nobody can take away. Learning how to use Dawarich means three things: deploying the Docker stack, changing the demo credentials before anything else, and then feeding it GPS data from your phone plus your old Google history.

The project started in March 2024 as a simple endpoint that accepted location points from the OwnTracks app, and it has grown into a full timeline brain: it imports Google Takeout exports, OwnTracks and Strava data, Immich photos, and GPX or GeoJSON files, and it exports everything back out as GeoJSON or GPX so your history is never locked in. It is AGPL-3.0 licensed, and its latest release, version 1.20.0, shipped on October 30, 2026 with more than 10,791 GitHub stars behind it.

This Dawarich tutorial walks the complete beginner arc: first Docker deploy, the demo-credentials rule, your first tracker, the Google Takeout import, and reading the dashboard.

How to Use Dawarich: The 10-Step First Run

1. Check you have Docker and at least 2 GB of free RAM.
2. Download the official compose file and run the stack with Docker Compose.
3. Open the login page and change the demo credentials immediately.
4. Generate a SECRET_KEY_BASE and set the production basics (hosts, timezone, domain).
5. Create an API key under Account, then pair your first phone tracker.
6. Grant the phone app background-location permission so tracking never silently stops.
7. Export your history from Google Takeout or your phone's Timeline export.
8. Import it through Imports, then New Import, and let the background job finish.
9. Check the timeline, trips, visits, and stats pages for your first results.
10. Set up a backup and read the update rule before your next upgrade.

Step 1: Deploy Dawarich with Docker

Dawarich runs as a multi-container stack: the Rails web app, Sidekiq background workers, a PostgreSQL database with the PostGIS extension, and Redis. The README's quick start is one line: docker compose -f docker/docker-compose.yml up, which opens the app at http://localhost:3000. That is the development flow, not the production flow.

For a real server, use the official production flow from the Dawarich docs. New to containers? This Docker beginner guide covers the concepts you need. Download the official compose file from the project's repository, then run docker compose config --quiet, docker compose pull, and docker compose up -d. This is the standard Dawarich Docker deploy path for a production install on your own Dawarich self hosted server. Expect the first pull to take a while: the full image set is close to 1 GB, so plan roughly 2 GB of free RAM on the host before you start.

Step 2: Change the Demo Credentials First

Every fresh Dawarich install ships with the same default login: username [email protected] and password safepassword. Change them in the account settings the moment you log in for the first time. This is the single most important security step in this guide — those credentials are published in the README, so anyone who can reach your server can log in with them until you change them.

Step 3: Configure the Production Basics

Dawarich's behavior is controlled through environment variables, and the docs list the ones that matter for a self-hosted install. Set SELF_HOSTED=true and RAILS_ENV=production, put your hostname in APPLICATION_HOSTS without any protocol (the default is just localhost,my.domain.com), set APPLICATION_PROTOCOL to https once you have a certificate, and set DOMAIN to your real domain because it is required in production for email links. Set TIME_ZONE to your own zone rather than the Europe/London default, so your timeline shows the right local times.

Generate a SECRET_KEY_BASE with openssl rand -hex 64 and never regenerate it afterward: the docs warn that changing it signs everyone out and can make encrypted data unreadable. If you are putting this on a rented server, this what is VPS hosting guide explains the server side. The database defaults in the compose file (postgres user, password password, dawarich_development database name, and redis://dawarich_redis:6379 for Redis) are fine for a first install on a private host, but change the database password on any server exposed to the internet.

Step 4: Connect Your First Tracker — Official App, OwnTracks, Overland, or Traccar

Dawarich is the server and the timeline; it does not track your phone by itself. A tracker app on the phone collects the GPS points and sends them to your instance. The official Dawarich app for iOS and Android is the simplest path: open the Account section, go to API access, scan the QR code or enter your server URL and API key manually, then complete the permission walkthrough and flip Tracking on in the Map tab. The app works offline and uploads when the connection returns, but always use HTTPS — the app warns you about plain HTTP.

Dawarich speaks the protocols of the popular tracker apps too, which is handy if you already use one. Dawarich for beginners is worth one clear distinction before the comparison: the phone apps are the eyes, Dawarich is the brain — the apps only collect points, while Dawarich builds the map, trips, visits, and stats.

Dawarich vs OwnTracks is not really a competition: OwnTracks collects, Dawarich stores and visualizes. If you want Dawarich Android tracking today, the official Android app is the least fiddly option; Traccar Client is the flexible backup.

Step 5: Import Your Google Takeout Location History

The Google Takeout import is why most people install Dawarich. Since Google shut down Timeline for the web and took your location history off its servers, the Dawarich Google Takeout import is how you bring that old history home. Dawarich accepts six Google formats: Records, Semantic, Semantic Segments, Settings, TimelineEdits, and Location History. Two of them matter most for beginners:

In the app, go to Imports, then New Import, pick "Google Semantic History" as the source, upload your monthly JSON files, and create the import. Processing runs in the background and takes seconds to minutes depending on how much history you upload. If your Records.json is too big for the browser, copy it into the container first (docker cp Records.json dawarich_app:/var/app/tmp/imports/Records.json) and import from there.

To get the files, use takeout.google.com and select Location History — note that Google says this no longer works for everyone — or export directly from the Google Maps app: on Android go to Settings, then Location, then Timeline, then Export Timeline; on iOS go to Settings, then Personal Content, then Export Timeline data. Also keep your original files after importing: the README explicitly says not to delete your original data after importing into Dawarich. If you are moving photos around too, this Immich beginner guide pairs well — Dawarich can also import Immich data, plus Strava, GPX, GeoJSON, and photo EXIF, and there is a watched folder (/var/app/tmp/imports/watched) that auto-imports files you drop into it.

Step 6: Read the Dashboard — Trips, Visits, Stats, and the Heatmap

Once points start arriving, Dawarich turns raw coordinates into a story. The timeline view shows where you were, when. Trips groups your movement into journeys. Visits names the places you stopped at, with addresses. Stats turns the data into totals — distance, countries, time moving. And the heatmap is the satisfying part: a glowing overlay of everywhere you have ever been. Give it a day of tracking before judging the output; a single afternoon of points looks thin no matter what app you use.

Running Dawarich on Home Assistant

If you run Home Assistant, Dawarich Home Assistant users get a shortcut: a community add-on that runs the entire Dawarich server — app, PostgreSQL with PostGIS, Redis, and the workers — as one add-on container on Home Assistant OS, opening straight from the sidebar. A phone that is already reporting location to Home Assistant can feed Dawarich without installing anything else, and the history is included in your regular Home Assistant backups. Two caveats from the add-on thread: it is 64-bit only (aarch64 or amd64), and the image is about 1 GB, so the first install is slow. Do not confuse this with the separate HACS integration, which only pulls stats out of an existing Dawarich server into Home Assistant sensors — it does not run the server.

The Update and Backup Rules

Dawarich's README has an updating rule that beginners should read twice: do not update automatically — read the release notes before updating, because automatic updates may break your setup. With 339 releases and counting, new versions land constantly, but this is a stack with a database schema and background workers, not a stateless website. Backup before every upgrade.

The official backup guide says a complete backup is a PostgreSQL dump plus the persistent files — explicitly: use a database dump, not a copy of a running database's files. The documented dump is docker exec dawarich_db pg_dumpall --clean --if-exists --username=postgres | gzip > "$backup_dir/dump.sql.gz", followed by copying the storage, public, watched, and redis volumes off the host. Keep your compose file, your .env, your SECRET_KEY_BASE, and your OTP_ENCRYPTION_* overrides with the backup: generating new keys during a restore can make existing encrypted data unreadable. And never run docker compose down -v as a routine restore step — it removes the named volumes that hold your data.

Dawarich Tutorial: Advanced Moves Worth Knowing

Once the beginner arc is done, three power moves are worth learning. First, the built-in API: your instance documents it at /api-docs, and the same API key your phone uses lets scripts and automations push points or pull data out. Second, the watched import folder: any GPX or GeoJSON dropped into /var/app/tmp/imports/watched gets picked up automatically, which is the simplest way to bulk-load years of old track logs. Third, exports: Dawarich exports to GeoJSON and GPX, and the project's free timeline visualizer tool at dawarich.app renders an exported file right in the browser without an account — handy for checking what is inside a Takeout file before you import it.

Dawarich for Beginners: Common Mistakes

Dawarich for beginners has four traps that show up in every community thread. One: phone apps need background-location permission, and without it tracking silently stops — if your timeline goes quiet, check the OS permission first, not the server. Two: the official app warns about plain HTTP, so put the server behind HTTPS before your phone talks to it over the internet. This Caddy beginner guide sets up a certificate in minutes. Three: the demo credentials trap — change [email protected] / safepassword before you expose the server. Four: on a slow server, the biggest delay is the first Docker pull of the ~1 GB image set — it is not stuck, it is downloading.

For remote access without opening ports, this Tailscale beginner guide gives your phone a private tunnel straight to the server.

Sources

• github.com/Freika/dawarich — "Your favorite self-hostable alternative to Google Timeline (Google Location History)"; release 1.20.0 published 2026-10-30; 339 releases; 10,791 stars, 412 forks; GNU Affero General Public License v3.0; created 2024-03-24
• github.com/Freika/dawarich README — Docker quick start (docker compose -f docker/docker-compose.yml up, http://localhost:3000), default credentials [email protected] / safepassword, update strategy ("DO NOT UPDATE AUTOMATICALLY: Read release notes before updating. Automatic updates may break your setup."; "Backup before updates: Always backup your data before upgrading."; "Do not delete your original data after importing into Dawarich.")
• dawarich.app/docs/self-hosting/introduction/ — production install flow (download docker-compose.yml; docker compose config --quiet; docker compose pull; docker compose up -d)
• dawarich.app/docs/self-hosting/environment-variables/ — SELF_HOSTED=true; APPLICATION_HOSTS default localhost,my.domain.com; APPLICATION_PROTOCOL default http; DOMAIN required in production; TIME_ZONE default Europe/London; RAILS_ENV=production; SIDEKIQ_EMBEDDED=true; SECRET_KEY_BASE via openssl rand -hex 64; DATABASE_USERNAME/DATABASE_PASSWORD/DATABASE_NAME defaults; REDIS_URL=redis://dawarich_redis:6379
• dawarich.app/docs/getting-started/track-your-location/ — official app pairing via QR code or server URL + API key at Account → API access; background-location permission; iOS 17.6+; offline-capable; HTTPS recommendation; OwnTracks/Overland/Traccar endpoint formats and API keys
• dawarich.app/tools/timeline-visualizer/ — supported Google import formats: Records, Semantic, Semantic Segments, Settings, TimelineEdits, Location History; Records.json described as raw GPS records in E7 coordinate format; official Takeout export methods
• community.home-assistant.io — Dawarich add-on thread: full server as one add-on container on HA OS; 64-bit only; ~1 GB image; included in Home Assistant backups
• dawarich.app/docs/self-hosting/maintenance/backup-and-restore/ — complete backup = PostgreSQL dump + persistent files; pg_dumpall command; preserve compose file, .env, SECRET_KEY_BASE, OTP_ENCRYPTION_*; warning against docker compose down -v
• hysenlabs.com/projects/freika-dawarich — independent README-driven review with FAQ on demo credentials and backup-before-update
• addrom.com/take-control-of-your-location-history-with-dawarich/ — Google Takeout import walkthrough (Imports → New Import → "Google Semantic History" → multiple monthly JSONs → Create Import)
• dawarich.app/blog/location-history-for-taxes/ — vendor blog on the tax-time use case
• prompts.brightcoding.dev — independent review covering the compose one-liner and the no-auto-update warning

Frequently Asked Questions

What is Dawarich used for?

Dawarich is a self-hosted replacement for Google Timeline: it stores your GPS history on your own server and turns it into a timeline, trips, visits, stats, and a heatmap. It is for people who want their location history without handing it to Google — especially since Google retired Timeline for the web.

Is Dawarich free?

Yes. Dawarich is AGPL-3.0 licensed open source, so the software itself is free. Your costs are the server it runs on — any small VPS or home server with around 2 GB of free RAM and Docker works.

How do I import my Google Timeline history into Dawarich?

Export your history from takeout.google.com (Location History) or from the Google Maps app's Timeline export, then go to Imports → New Import in Dawarich, choose "Google Semantic History," upload your monthly JSON files, and create the import. For the huge Records.json file, copy it into the container first and import from there.

Does Dawarich work on iPhone and Android?

Yes. There is an official Dawarich app for both platforms (iOS 17.6 or newer), and Dawarich also accepts data from OwnTracks, Overland, and Traccar Client through documented API endpoints. Whichever you use, grant the app background-location permission or tracking silently stops.

Is Dawarich safe to update automatically?

No. The README warns explicitly against automatic updates: read the release notes before every upgrade, because updates can break your setup. Always take a PostgreSQL dump backup first, and keep your SECRET_KEY_BASE safe — changing it can make encrypted data unreadable.