Update (#3)

dgraf-gh · web-flow · commit 747609ac7e97 · 2026-03-27T12:09:12.000+01:00
* restructure navigation

* updated oidc documentation to include username assignment logic

* updated oidc documentation to include username assignment logic

* removed references to rabbitmq

* added upgrade guide

* fixed padding for select
diff --git a/docs/.nav.yml b/docs/.nav.yml
@@ -0,0 +1,20 @@
+nav:
+  - Overview: index.md
+  - Installation: installation.md
+  - Getting Started: getting-started.md
+  - About:
+      - "about/*"
+  - Usage:
+      - "usage/main-view.md"
+      - "usage/*"
+  - Memories:
+      - "memories/*"
+  - Configuration:
+    - "configurations/*"
+  - Integrations:
+      - "integrations/mobile-apps.md"
+      - "integrations/*"
+  - Infrastructure:
+      - backup.md
+      - "infrastructure/*"
+  - "*"
diff --git a/docs/about/features.md b/docs/about/features.md
@@ -27,7 +27,7 @@ Reitti provides a comprehensive set of features for personal location tracking a
 - **API Token Management**: Secure API access with token-based authentication
 - **User Profile Management**: Customizable display names and secure password management
 - **Magic Link Sharing**: Share location data without requiring account creation ([Learn more](../usage/share-access.md))
-- **OpenID Connect Integration**: Enterprise authentication with automatic user provisioning ([Setup guide](../configurations/oidc.md))
+- **OpenID Connect Integration**: Enterprise authentication with automatic user provisioning ([Setup guide](../infrastructure/oidc.md))
 
 #### Geocoding & Address Resolution
 - **Multiple Geocoding Services**: Support for custom geocoding providers (Nominatim, etc.)
diff --git a/docs/about/how-it-works.md b/docs/about/how-it-works.md
@@ -5,7 +5,7 @@ weight: 4
 tags: ["overview"] 
 ---
 
-Reitti depends on a consistent stream of geo location data to process and calculate visits, places, and trips between visits. The data processing pipeline follows these steps:
+Reitti depends on a consistent stream of geolocation data to process and calculate visits, places, and trips between visits. The data processing pipeline follows these steps:
 
 ### Data Processing Pipeline
 
@@ -22,10 +22,10 @@ Around each datapoint, Reitti calculates potential visits. This process can iden
 Successive visits are merged into ProcessedVisits, combining related location points into meaningful stay periods.
 
 #### 5. Significant Places Creation
-After visits are merged into ProcessedVisits, SignificantPlaces are created or matched for each ProcessedVisit. SignificantPlaces represent locations on the map where you spend time - such as your home, workplace, or any other location where you stayed more than 5 minutes.
+After visits are merged into ProcessedVisits, SignificantPlaces are created or matched for each ProcessedVisit. SignificantPlaces represent locations on the map where you spend time – such as your home, workplace, or any other location where you stayed more than 5 minutes.
 
 #### 6. Address Resolution
-SignificantPlaces are processed through reverse geocoding to assign human-readable names and addresses, making them easier to identify and understand.
+SignificantPlaces are processed through reverse geocoding to assign human-readable names and addresses, making them easier to identify and understand. See [Reverse Geocoding](../configurations/reverse-geocoding.md) for more details.
 
 #### 7. Trip Calculation
 Finally, the system calculates Trips between successive ProcessedVisits, tracking your movement patterns and transportation between significant locations.
diff --git a/docs/assets/js/scripts.js b/docs/assets/js/scripts.js
@@ -20,7 +20,7 @@ document.addEventListener("DOMContentLoaded", function() {
             // 2. Create the select element
             const select = document.createElement("select");
             select.id = "version-selector";
-            select.style.padding = "4px 8px";
+            select.style.padding = "4px 24px 4px 8px";
             select.style.border = "1px solid #444";
             select.style.borderRadius = "6px";
             select.style.fontSize = "12px";
diff --git a/docs/index.md b/docs/index.md
@@ -47,7 +47,7 @@ Memories transform your raw location data into narrative-driven travel logs, all
 #### Privacy & Self-hosting
 - **Complete Data Control**: Your location data never leaves your server
 - **Self-hosted Solution**: Deploy on your own infrastructure
-- **Asynchronous Processing**: Handle large datasets efficiently with RabbitMQ-based processing
+- **Asynchronous Processing**: Handle large datasets efficiently
 
 ### Quick Start
 
diff --git a/docs/infrastructure/docker-secrets.md b/docs/infrastructure/docker-secrets.md
@@ -8,8 +8,8 @@ tags: ["configuration"]
 
 ## General Information
 
-When deploying **Reitti** with Docker Swarm or Docker Compose you can keep sensitive
-information (e.g. database credentials) out of the plain‑text `docker‑compose.yml`
+When deploying **Reitti** with Docker Swarm or Docker Compose, you can keep sensitive
+information (for example database credentials) out of the plain‑text `docker‑compose.yml`
 by using Docker **secrets**.
 
 The workflow consists of three steps:
@@ -66,8 +66,6 @@ services:
     ports:
       - "8080:8080"
     depends_on:
-      rabbitmq:
-        condition: service_healthy
       postgis:
         condition: service_healthy
         restart: true
@@ -102,8 +100,7 @@ the contents of the secret files.
 ## Full Example `docker-compose.yml`
 
 Below is a minimal compose file that demonstrates the complete setup for the
-`reitti` service with Docker secrets.  The other services (`postgis`, `rabbitmq`,
-`redis`, etc.) are omitted for brevity – add them back as required by your
+`reitti` service with Docker secrets.  The other services (`postgis`, `redis`, etc.) are omitted for brevity – add them back as required by your
 deployment.
 
 ```yaml
@@ -115,8 +112,6 @@ services:
     ports:
       - "8080:8080"
     depends_on:
-      rabbitmq:
-        condition: service_healthy
       postgis:
         condition: service_healthy
         restart: true
@@ -136,7 +131,7 @@ services:
       - postgis_user
       - postgis_password
 
-  # ... other services such as postgis, rabbitmq, redis, etc. ...
+  # ... other services such as postgis, redis, etc. ...
 
 volumes:
   reitti-data:
diff --git a/docs/infrastructure/oidc.md b/docs/infrastructure/oidc.md
@@ -81,6 +81,24 @@ Reitti uses a flexible process to match OIDC users with existing accounts:
 2. **Fallback Match**: If no external ID match, searches by the OIDC `preferred_username`
 3. **Account Linking**: When a username match is found, the account is linked with the external ID for future logins
 
+### Username Assignment Logic
+
+When a user logs in via OIDC for the first time, Reitti follows this priority to determine their username:
+
+1. **`preferred_username` claim** from the ID token
+2. **`preferred_username` claim** from the OIDC user object
+3. **`preferred_username` claim** from user info endpoint (if available)
+4. **Email address** (`email` claim)
+5. **Generated name** (`given_name` + "." + `family_name` in lowercase)
+6. **OIDC subject** (`sub` claim) as final fallback
+
+This means Reitti will try multiple OIDC claims before falling back to the subject identifier. For example:
+
+- If your OIDC provider supplies `preferred_username: "jane.doe"`, that becomes the username
+- If not, but `email: "jane@example.com"` is available, that becomes the username
+- If only `given_name: "Jane"` and `family_name: "Doe"` are available, the username becomes `"jane.doe"`
+- As a last resort, the OIDC subject (e.g., `"1234567890"`) is used
+
 #### User Data Synchronization
 
 User information is automatically updated from OIDC claims on each login:
diff --git a/docs/infrastructure/reverse-proxy.md b/docs/infrastructure/reverse-proxy.md
diff --git a/docs/installation.md b/docs/installation.md
@@ -4,9 +4,9 @@ description: "Step-by-step guide to install and configure Reitti"
 ---
 ### Docker Installation (Recommended)
 
-Docker is the easiest way to get Reitti up and running. The provided Docker Compose configuration handles all the required services including PostgreSQL with PostGIS, RabbitMQ, Redis, and Photon geocoding service.
+Docker is the easiest way to get Reitti up and running. The provided Docker Compose configuration handles all the required services including PostgreSQL with PostGIS and Redis.
 
-Simply download the [docker-compose.yml](https://github.com/dedicatedcode/reitti/blob/main/docker-compose.yml) file and run:
+Download the [docker-compose.yml](https://github.com/dedicatedcode/reitti/blob/main/docker-compose.yml) file and run:
 
 ```bash
 docker-compose up -d
@@ -19,9 +19,8 @@ This will start all services and make Reitti available at http://localhost:8080.
 If you prefer to run Reitti without Docker but don't want to build from source, you can download the pre-built JAR file from the releases page.
 
 #### Prerequisites
-- Java 24 or higher
+- Java 25 or higher
 - PostgreSQL with PostGIS extensions
-- RabbitMQ
 - Redis
 
 #### Installation Steps
@@ -43,12 +42,6 @@ spring.data.redis.port=6379
 spring.data.redis.username=
 spring.data.redis.password=
 
-# RabbitMQ Configuration
-spring.rabbitmq.host=localhost
-spring.rabbitmq.port=5672
-spring.rabbitmq.username=reitti
-spring.rabbitmq.password=reitti
-
 # Storage configuration (optional)
 # Default: reitti.storage.path=data/
 # Make sure the user running Reitti has write permissions to this directory
@@ -69,10 +62,9 @@ The application will be available at http://localhost:8080. When you first open
 To build and run Reitti from source code:
 
 #### Prerequisites
-- Java 24 or higher
+- Java 25 or higher
 - Maven 3.6 or higher
 - PostgreSQL with PostGIS extensions
-- RabbitMQ
 - Redis
 
 #### Build Steps
@@ -98,12 +90,6 @@ spring.data.redis.port=6379
 spring.data.redis.username=
 spring.data.redis.password=
 
-# RabbitMQ Configuration
-spring.rabbitmq.host=localhost
-spring.rabbitmq.port=5672
-spring.rabbitmq.username=reitti
-spring.rabbitmq.password=reitti
-
 # Storage configuration (optional)
 # Default: reitti.storage.path=data/
 # Make sure the user running Reitti has write permissions to this directory
diff --git a/docs/integrations/custom-file-upload.md b/docs/integrations/custom-file-upload.md
@@ -1,7 +1,6 @@
 ---
 title: "Custom File Upload"
 description: "Integrate custom scripts to upload GPX files to Reitti for automated location data import"
-weight: 15
 tags: ["integrations"]
 ---
 
diff --git a/docs/integrations/home-assistant.md b/docs/integrations/home-assistant.md
@@ -1,7 +1,6 @@
 ---
 title: "Home-Assistant"
 description: "Connect Home-Assistant to Reitti"
-weight: 3
 tags: [ "integrations" ]
 ---
 
diff --git a/docs/integrations/mobile-apps.md b/docs/integrations/mobile-apps.md
@@ -1,7 +1,6 @@
 ---
 title: "Mobile App Integration"
 description: "Real-time location tracking with mobile applications"
-weight: 0
 tags: ["integrations"]
 ---
 
diff --git a/docs/integrations/owntracks-recorder.md b/docs/integrations/owntracks-recorder.md
@@ -1,7 +1,6 @@
 ---
 title: "OwnTracks Recorder Integration"
 description: "Alternative data collection method with backup storage capabilities"
-weight: 4
 tags: ["integrations"]
 ---
 
diff --git a/docs/integrations/reitti.md b/docs/integrations/reitti.md
@@ -1,7 +1,6 @@
 ---
 title: "Shared Instances: Federated Connections"
 description: "Connect with users on other Reitti instances for federated location sharing and collaboration"
-weight: 1
 tags: [ "integrations" ]
 ---
 |since|v1.3.0|.version-badge|
diff --git a/docs/upgrade.md b/docs/upgrade.md
@@ -0,0 +1,130 @@
+---
+title: "Upgrading Reitti"
+description: "Guide for upgrading between Reitti versions"
+weight: 5
+tags: ["upgrade", "migration", "version"]
+---
+
+# Upgrading Reitti
+
+Reitti follows (https://semver.org/), which means:
+
+- **Major versions** (v1.x → v2.x): Contain breaking changes that may require manual intervention
+- **Minor versions** (v2.1 → v2.2): Add new features in a backward-compatible manner
+- **Patch versions** (v2.1.0 → v2.1.1): Include bug fixes and minor improvements
+
+For most upgrades, simply pulling the latest Docker image or updating the source code is enough. 
+Only upgrades between major versions require special attention.
+
+## Upgrading from v3 to v4
+
+This guide covers the changes when upgrading from Reitti v3 to v4. These are breaking changes that require manual updates to your configuration.
+
+### 1. RabbitMQ Removal
+
+RabbitMQ is no longer required. Remove all RabbitMQ-related configuration from your `docker-compose.yml`:
+
+**Remove these services:**
+```yaml
+# Remove this entire service
+rabbitmq:
+  image: rabbitmq:3-management-alpine
+  # ... other rabbitmq configuration
+```
+
+**Remove RabbitMQ environment variables from the Reitti service:**
+```yaml
+environment:
+  # Remove these lines if they exist:
+  - RABBITMQ_HOST=rabbitmq
+  - RABBITMQ_PORT=5672
+  - RABBITMQ_USERNAME=guest
+  - RABBITMQ_PASSWORD=guest
+```
+
+### 2. Photon Geocoder Configuration Changes
+
+Photon is now configured like other reverse geocoding services through the web interface. If you had `PHOTON_BASEURL` configured:
+
+1. **First start with v4:** Reitti will automatically create a Photon geocoder entry in **Settings > Geocoding** using your existing `PHOTON_BASEURL` environment variable.
+2. **After verification:** Once you confirm the Photon service is working in the web interface, you can remove the `PHOTON_BASEURL` environment variable from your `docker-compose.yml`.
+
+For more details on configuring reverse geocoding services, see the [Reverse Geocoding documentation](./configurations/reverse-geocoding.md).
+
+### 3. New Default Geocoder: Paikka
+
+Reitti v4 includes a new default reverse geocoding service called **Paikka**. This service is specifically designed for Reitti and provides:
+
+- Optimized results for personal location tracking
+- Administrative boundary information when available
+- Lightweight and efficient processing
+
+On first start, Reitti will automatically add Paikka to your geocoding services using the public instance at `https://geo.dedicatedcode.com`.
+
+**Privacy consideration:** If you prefer not to use the public Paikka instance for privacy reasons:
+
+1. Go to **Settings > Geocoding**
+2. Find the "Paikka" service in the list
+3. Click the Disable button or remove it entirely
+
+You can also visit [Paikka](https://github.com/dedicatedcode/paikka) for information about it and how to self-host it.
+
+### 4. Tile Service Configuration Changes
+
+The custom tile configuration has been simplified:
+
+**Remove these environment variables:**
+```yaml
+environment:
+  # Remove these lines:
+  - CUSTOM_TILES_SERVICE=https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
+  - CUSTOM_TILES_ATTRIBUTION='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
+```
+
+At the moment there is no equivalent for these in Reitti v4.0. If you need this, please open an issue.
+
+### 5. Tile Cache Replacement
+
+The previous nginx-based tile cache has been replaced with a dedicated tile cache service:
+
+**Update your `docker-compose.yml`:**
+
+Replace the existing tile cache configuration with if you had one:
+```yaml
+services:
+  tile-cache:
+    image: dedicatedcode/reitti-tile-cache:next
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://127.0.0.1/osm/0/0/0.png"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - tile-cache-data:/var/cache/nginx
+```
+
+### 6. Verification Steps
+
+After making these changes:
+
+1. **Compare configurations:** Review the latest `docker-compose.yml` example in the Reitti repository and compare it with your current configuration.
+2. **Backup your data:** Always back up your database before major upgrades.
+3. **Start the services:** Start the updated containers with `docker-compose up -d`.
+4. **Check logs:** Monitor the logs for any errors during startup: `docker-compose logs -f reitti`.
+5. **Verify functionality:**
+    - Log in to the web interface
+    - Check **Settings > Geocoding** for configured services
+    - Verify map tiles are loading correctly
+    - Test location tracking and geocoding
+
+### 7. Troubleshooting
+
+If you encounter issues after upgrading:
+
+1. **Check the logs:** `docker-compose logs reitti` for error messages.
+2. **Database migrations:** Reitti v4 includes database schema changes that are applied automatically on startup.
+3. **Service dependencies:** Ensure all required services (database, redis) are running and accessible.
+4. **Configuration validation:** Double-check that all removed environment variables have been deleted from your configuration.
+
+For additional help, check the [GitHub issues](https://github.com/dedicatedcode/reitti/issues) or community discussions.
diff --git a/docs/usage/logging.md b/docs/usage/logging.md
@@ -1,7 +1,7 @@
 ---
 title: "Logging"
 description: "Live log view and log level management for Reitti"
-weight: 0
+weight: 100
 tags: ["admin"]
 ---
 |since|v3.0.0|.version-badge|
@@ -16,7 +16,7 @@ From **Settings > Logging** you can view a live stream of the current instan
 1. Open the Reitti web UI and navigate to **Settings > Logging**.  
 2. The page shows a continuously updating view of the log output from the running instance.  
 
-![Logging View](./img/logging.png)
+![Logging View](../img/logging.png)
 
 ### Adjusting Log Levels
 
diff --git a/mkdocs.yml b/mkdocs.yml
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/uv.lock b/uv.lock
