Skip to content

Commit 467e656

Browse files
dgraf-ghdgraf-gh
committed
Merge branch 'main' into v5.0
2 parents a15dc6b + a50df0b commit 467e656

8 files changed

Lines changed: 269 additions & 5 deletions

File tree

‎docs/about/features.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@ Reitti provides a comprehensive set of features for personal location tracking a
4040
- **Queue Monitoring**: Real-time job status and processing queue visibility
4141
- **Custom Tiles-Server**: Ability to use your own tiles-server
4242

43+
#### Spatial Coverage
44+
- **H3-Based Coverage Analysis**: See what percentage of a city, district, or country you have explored, with the ability to travel back in time and view your coverage at any point in the past. [Learn more](../configurations/spatial-coverage.md)
45+
4346
### Integration Features
4447

4548
Reitti supports various integrations to enhance your location tracking experience:

‎docs/configurations/spatial-coverage.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: "Spatial Coverage"
3+
description: "Visualize how much of a city, district, or country you have explored over time"
4+
weight: 7
5+
tags: ["configuration", "h3", "coverage"]
6+
---
7+
|since|v5.2.0|.version-badge|
8+
9+
H3 Spatial Coverage gives you a bird's-eye view of your exploration history. Instead of just seeing where you've been as individual tracks on a map, it visualizes the percentage of an area you've actually covered — whether that's a city, a district, or an entire country.
10+
11+
### Why Use Spatial Coverage?
12+
13+
Spatial coverage turns your raw location data into a clear picture of your exploration footprint:
14+
15+
- **Percent-Based Insights**: See exactly how much of an area you have uncovered (e.g., "You've explored 42 % of Berlin")
16+
- **Time Travel**: Go back in time and see what your coverage looked like months or years ago. Watch your exploration grow
17+
- **Compare Areas**: Switch between cities, districts, or countries to see where you've spent the most time
18+
- **Discover Hidden Gaps**: Find neighborhoods or regions you haven't visited yet
19+
20+
### How It Works
21+
22+
Reitti uses Uber's [H3](https://www.uber.com/blog/h3/) hexagon grid system to discretize geographic space into evenly sized cells. Here is the process:
23+
24+
1. **Enable the feature** (see Configuration below).
25+
2. **Background calculation** begins: Reitti assigns an H3 hex cell to every location point in your database.
26+
3. **Global boundary database** is downloaded from Cloudflare. Provided by [Paikka](https://github.com/dedicatedcode/paikka), it maps H3 cells to administrative boundaries (countries, states, cities, districts) using OpenStreetMap data. The download is roughly **4 GB** and requires around **5 GB** of disk space once extracted.
27+
4. **Coverage calculation** compares the number of unique hex cells you've visited against the total number of cells in any given boundary, this gives you your coverage percentage.
28+
5. **Historical snapshots** are preserved, letting you navigate backward in time to see how your coverage evolved.
29+
30+
### Configuration
31+
32+
Spatial coverage is disabled by default. Enable it using one of the following methods:
33+
34+
#### Docker
35+
36+
Set the environment variable to `true`:
37+
38+
```yaml
39+
environment:
40+
- SPATIAL_COVERAGE=true
41+
```
42+
43+
#### JAR / application.properties
44+
45+
Add the following to your `application.properties`:
46+
47+
```properties
48+
reitti.h3.enabled=true
49+
```
50+
51+
### Restart
52+
53+
A restart is required after enabling the feature. When Reitti starts back up, it will:
54+
55+
- Download the global administrative boundary index
56+
- Begin calculating H3 cells for every point in the database in the background
57+
58+
**Please be patient** — depending on the size of your database, the initial calculation can take a considerable amount of time and will use additional disk space.
59+
60+
### Main Map Layer
61+
62+
Enabling spatial coverage also adds a new H3 overlay to Reitti's main map. Each visited hex cell appears as a colored tile, giving you an at-a-glance view of your coverage directly from the main map.
63+
64+
![H3 Overlay on Main Map](../img/h3-main-map.png)
65+
66+
### Using the Coverage Page
67+
68+
Once the initial calculation is complete, navigate to the **Spatial Coverage** page. The page shows a map with all your visited H3 cells overlaid.
69+
70+
![Default Coverage View](../img/h3-default-cells.png)
71+
72+
#### Right Panel — Area Explorer
73+
74+
On the right side of the map, a panel lists all OSM administrative areas you have visited, grouped by level:
75+
76+
- **Country**
77+
- **City**
78+
- **District**
79+
- **Other**
80+
81+
The list updates automatically as you zoom and pan the map — it only shows areas that fall within the currently visible map boundaries.
82+
83+
- **Hover** over an area to see its boundary outline on the map.
84+
- **Click** an area to zoom the map to its full extent and display the H3 cells at the exact resolution used to calculate your coverage percentage.
85+
- **Click again** to deselect and return to the default view.
86+
87+
![Selected Area View](../img/h3-area-select.png)
88+
89+
#### Controls
90+
91+
At the **bottom right**, you can switch between different devices and connected users to view each one's coverage individually.
92+
93+
At the **bottom**, a **time slider** lets you travel backward in time — see what your coverage looked like a week, a month, or years ago.
94+
95+
### Disabling the Feature
96+
97+
If you decide you no longer want spatial coverage:
98+
99+
1. Set `SPATIAL_COVERAGE` to `false` (or remove the environment variable entirely).
100+
2. Restart Reitti.
101+
3. Reitti will **automatically clean up** all H3 cells and the downloaded boundary database in the background.
102+
103+
You do not need to manually delete anything.
104+
105+
### Best Practices
106+
107+
- **Be patient with initial processing**: The first calculation processes every point in your database. Let it run — it works in the background and will not affect normal usage.
108+
- **Ensure sufficient disk space**: The H3 cells and the global boundary database add to your storage footprint.
109+
- **Use the time slider**: The historical view is one of the most powerful aspects of this feature — experiment with different dates to see how your exploration has changed over time.

‎docs/configurations/user-management.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
title: "User Management"
3+
description: "Manage user accounts and configure your personal profile"
4+
weight: 5
5+
tags: [ "configuration" ]
6+
---
7+
8+
Reitti provides a **User Management** page that lets administrators manage all accounts on the instance, while giving
9+
every user a place to edit their own profile and preferences. A single page at **Settings > User Management** renders
10+
two
11+
completely different views depending on your role:
12+
13+
- **Admin users** see a table of all accounts with create, edit, and delete actions.
14+
- **Non-admin users** (and admins editing their own account) see their own profile form.
15+
16+
### Roles and User Types
17+
18+
Reitti distinguishes between the **role** of a user (what they are allowed to do) and the **user type** (how their
19+
location data is handled).
20+
21+
| Role | Description |
22+
|----------------|---------------------------------------------------------------------------------|
23+
| **Admin** | Full access to all settings, including the ability to manage every user account |
24+
| **User** | A regular account that can edit its own profile and preferences |
25+
| **API Access** | An account intended for programmatic API access |
26+
27+
| User Type | Description |
28+
|--------------------|------------------------------------------------------------------------------------------------------|
29+
| **Normal** | Retains the full location history, visits, places, and memories |
30+
| **Live Data Only** | Only tracks live location data and retains **no history** (visits, places, and memories are deleted) |
31+
32+
### Admin User List
33+
34+
Administrators are shown a table of all users with the following columns and actions:
35+
36+
- **Username** — the login name of the account
37+
- **Display Name** — the name shown across the interface
38+
- **Role** — the account's role (`Admin`, `User`, or `API Access`)
39+
- **Actions** — per-row **Edit** and **Delete** buttons
40+
41+
From this view an admin can:
42+
43+
- **Add New User** — opens a blank profile form to create an account. This button is hidden when local login
44+
is disabled (see [Configuration](#configuration)).
45+
- **Edit** — opens the profile form for an existing user.
46+
- **Delete** — removes an account after a confirmation prompt. You cannot delete your own account.
47+
48+
Feedback such as success or error messages is shown at the top of the list. If an admin changes their own username, a
49+
special banner prompts them to re-login.
50+
51+
![User Management](../img/user-management.png)
52+
53+
### Profile Form
54+
55+
The profile form is shared between administrators editing any account and users editing their own profile. It contains
56+
the following sections:
57+
58+
#### Identity
59+
60+
- **Username** — required
61+
- **Display name** — required
62+
- **Password** — required when creating a user; on update, leave empty to keep the current password
63+
64+
#### Role and User Type (admin only)
65+
66+
- **Role** — `User` or `Admin`
67+
- **User Type** — `Normal` or `Live Data Only` (see [Switching User Type](#switching-user-type))
68+
69+
#### Profile Picture
70+
71+
- Choose one of four bundled default avatars
72+
- Upload a custom image (up to 2 MB; JPEG, PNG, GIF, or WebP)
73+
- Remove the current avatar
74+
75+
#### Custom CSS
76+
77+
Upload your own stylesheet (up to 1 MB, must be a `.css` file) to personalize the interface, or remove an existing one.
78+
79+
#### Preferences
80+
81+
- **Preferred Language** — one of the supported languages
82+
- **Unit System** — `Metric` or `Imperial`
83+
- **Time Display Mode** — use the browser/override timezone (`Default`) or the timezone of the current location
84+
(`Geo Local`)
85+
- **Time Format** — 12-hour or 24-hour clock
86+
- **Timezone Override** — a specific timezone, or empty to use the browser timezone
87+
- **Color Theme** — a preset color or a custom value
88+
- **Home Location** — latitude/longitude with an interactive map and draggable marker
89+
90+
### Creating a User
91+
92+
Creating a user (admin only) requires a username, display name, and password. Reitti then automatically provisions a
93+
complete set of defaults for the new account:
94+
95+
- Personal settings (language, unit system, home location, time modes, color)
96+
- A default map style
97+
- A default device and API token
98+
- Default visit and transport detection parameters (skipped for `Live Data Only` accounts)
99+
100+
### Updating a User
101+
102+
An admin can edit any account, while a regular user can only edit their own. When updating:
103+
104+
- Blank username and display name fall back to the existing values
105+
- The password is only changed when a new one is provided
106+
- The selected language, unit system, home location, timezone, time modes, color, avatar, and custom CSS are applied
107+
- If a user changes their own username, they are asked to re-login
108+
109+
Updates use optimistic locking, so if two people edit the same account at once, the later save fails with a conflict
110+
instead of silently overwriting the earlier change.
111+
112+
### Switching User Type
113+
114+
When an admin changes an account between `Normal` and `Live Data Only`, Reitti performs the necessary data migrations:
115+
116+
- **Normal → Live Data Only**: requires typing the exact username in a confirmation modal, then permanently deletes all
117+
history (visits, trips, places, and memories).
118+
- **Live Data Only → Normal**: recreates the default detection parameters for the account.
119+
120+
Without confirming the modal, a `Normal → Live Data Only` change is ignored and the account stays `Normal`.
121+
122+
### Deleting a User
123+
124+
Deleting a user (admin only, never your own account) permanently removes the account and cascades to all associated
125+
data, including detection parameters, settings, geocoding responses, visits, places, raw location points, API tokens,
126+
MQTT integrations, map styles, devices, and the avatar.
127+
128+
### OIDC-Managed Accounts
129+
130+
When an account is managed by an external OpenID Connect provider (see [OpenID Connect](../infrastructure/oidc.md)), the
131+
profile form adapts:
132+
133+
- **Username** and **display name** inputs are disabled — they are synchronized from the provider.
134+
- The **password** field is hidden when local login is disabled.
135+
- The **avatar** section is replaced with a notice that the avatar is managed by the provider and updated automatically.
136+
- An information banner shows a **"View external profile"** link to the provider's profile page.
137+
138+
These fields can never be overwritten by the form; they are always preserved from the provider's data. For details on
139+
how OIDC users are created and matched, refer to the [OpenID Connect](../infrastructure/oidc.md) documentation.
140+
141+
### Best Practices
142+
143+
- **Use `Normal` for full-feature accounts**: It retains history, visits, places, and memories. Reserve `Live Data Only`
144+
for accounts that only need live tracking.
145+
- **Confirm before switching to `Live Data Only`**: The transition permanently deletes all history and cannot be undone.
146+
- **Disable local login for OIDC-only environments**: Set `local-login.disable` to enforce authentication through your
147+
provider and hide the password fields.
148+
- **Never delete your own account**: Self-deletion is blocked to avoid locking yourself out of the instance.

‎docs/img/h3-area-select.png‎

3.43 MB
Loading

‎docs/img/h3-default-cells.png‎

4.82 MB
Loading

‎docs/img/h3-main-map.png‎

2.15 MB
Loading

‎docs/img/user-management.png‎

164 KB
Loading

‎docs/infrastructure/docker-config.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -99,11 +99,12 @@ variables for quick reference.
9999

100100
### Data Import / Processing
101101

102-
| Variable | Description | Default Value | Example Value |
103-
|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:--------------|
104-
| `PROCESSING_BATCH_SIZE` | Number of location points processed in a single batch during import. Larger values use more memory and speed up processing. | `10000` | `50000` |
105-
| `INGESTION_MAX_BATCH_SIZE` | Maximum number of raw location points the server will wait before flushing API request from the ingestion endpoint. | `100` | `500` |
106-
| `INGESTION_MAX_IDLE_TIME` | Maximum time (in seconds) the server will wait before flushing a partially filled batch to the database when receiving data via the live mode / batch ingestion API. | `5` | `10` |
102+
| Variable | Description | Default Value | Example Value |
103+
|:---------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:--------------|
104+
| `PROCESSING_BATCH_SIZE` | Number of location points processed in a single batch during import. Larger values use more memory and speed up processing. | `10000` | `50000` |
105+
| `INGESTION_MAX_BATCH_SIZE` | Maximum number of raw location points the server will wait before flushing API request from the ingestion endpoint. | `100` | `500` |
106+
| `INGESTION_MAX_IDLE_TIME` | Maximum time (in seconds) the server will wait before flushing a partially filled batch to the database when receiving data via the live mode / batch ingestion API. | `5` | `10` |
107+
| `SPATIAL_COVERAGE` | Enables H3-based spatial coverage analysis. Calculates H3 hex cells for every location point and downloads a global administrative boundary database. Requires additional disk space and processing time. [Learn more](../configurations/spatial-coverage.md) | `false` | `true` |
107108

108109
---
109110

@@ -157,6 +158,9 @@ services:
157158
- PROCESSING_BATCH_SIZE=10000
158159
- INGESTION_MAX_BATCH_SIZE=100
159160
- INGESTION_MAX_IDLE_TIME=5
161+
162+
# Spatial coverage
163+
- SPATIAL_COVERAGE=false
160164
tile-cache:
161165
image: dedicatedcode/reitti-tile-cache:latest
162166
environment:

0 commit comments

Comments
 (0)