diff --git a/.github/workflows/build-deploy.yml b/.github/workflows/build-deploy.yml index 3707df2..fff7e3e 100644 --- a/.github/workflows/build-deploy.yml +++ b/.github/workflows/build-deploy.yml @@ -7,7 +7,7 @@ on: - 'v*' env: - CURRENT_MAJOR_VERSION: "4.0" + CURRENT_MAJOR_VERSION: "5.0" jobs: deploy: diff --git a/docs/api/geojson.md b/docs/api/geojson.md new file mode 100644 index 0000000..2be3412 --- /dev/null +++ b/docs/api/geojson.md @@ -0,0 +1,124 @@ +--- +title: "GeoJSON API" +type: "projects" +parent: "API Documentation" +weight: 25 +--- + +The GeoJSON API endpoints allow you to export and import location data in GeoJSON format, enabling interoperability with other mapping and GIS tools. + +### Endpoints + +``` +GET /api/v1/geojson/export?start={YYYY-MM-DD}&end={YYYY-MM-DD}&device={deviceId} +``` + +``` +POST /api/v1/geojson/import +``` + +### Usage + +These endpoints are useful for: + +- **Export**: Generate GeoJSON files for use in GIS applications, custom maps, or data analysis +- **Import**: Upload GeoJSON files from other sources to populate your location history + +### Authentication + +Include your API token either as a header or query parameter: + +```bash +# Using header +curl -H "X-API-TOKEN: your-api-token" \ + "https://your-reitti-instance/api/v1/geojson/export?start=2025-09-11&end=2025-09-13" \ + -o locations.geojson + +# Using query parameter +curl "https://your-reitti-instance/api/v1/geojson/export?start=2025-09-11&end=2025-09-13&token=your-api-token" \ + -o locations.geojson +``` + +### Export Endpoint + +``` +GET /api/v1/geojson/export?start={YYYY-MM-DD}&end={YYYY-MM-DD}&device={deviceId} +``` + +#### Parameters + +| Parameter | Type | Required | Description | +|-----------|--------|----------|-----------------------------------------------------------------------------| +| `start` | string | Yes | Start date in YYYY-MM-DD format (inclusive) | +| `end` | string | Yes | End date in YYYY-MM-DD format (inclusive) | +| `device` | long | No | Optional device ID to filter results to a specific device | + +#### Response + +The endpoint returns a GeoJSON FeatureCollection containing all location points within the specified date range. The response has the content type `application/json`. + +```bash +# Export location data for a specific date range +curl -H "X-API-TOKEN: your-api-token" \ + "https://your-reitti-instance/api/v1/geojson/export?start=2025-09-11&end=2025-09-13" \ + -o my-locations.geojson +``` + +### Import Endpoint + +``` +POST /api/v1/geojson/import +``` + + +#### Request Format + +Send the GeoJSON file as a multipart form upload with the field name `file`. Only files with `.geojson` or `.json` extensions are accepted. + +#### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|---------------------------------------------------------| +| `file` | file | Yes | The GeoJSON file to upload | +| `device` | long | No | Optional device ID to override where the data is stored | + +By default, imported data is associated with the device linked to your API token. If you specify a `device` parameter, +it overrides this and stores the data under the specified device instead. + +```bash +# Import a GeoJSON file (data stored under device linked to token) +curl -X POST -H "X-API-TOKEN: your-api-token" \ + -F "file=@locations.geojson" \ + https://your-reitti-instance/api/v1/geojson/import + +# Import a GeoJSON file with explicit device override +curl -X POST -H "X-API-TOKEN: your-api-token" \ + -F "file=@locations.geojson" \ + -F "device=42" \ + https://your-reitti-instance/api/v1/geojson/import +``` + +#### Response + +The endpoint returns a JSON response confirming the import: + +```json +{ + "pointsScheduled": 2139, + "success": true, + "message": "Successfully imported GeoJSON file with 2139 location points" +} +``` + +#### Response Fields + +- **pointsScheduled**: Number of location points that were imported from the GeoJSON file +- **success**: Boolean indicating if the import was successful +- **message**: Descriptive message about the import operation + +### What Can Be Achieved + +- **Export**: Generate GeoJSON files for use in GIS applications, custom maps, or data analysis +- **Import**: Upload GeoJSON files from other sources to populate your location history +- **Data Migration**: Transfer location data between systems using the GeoJSON format +- **Custom Visualizations**: Use exported data in tools like QGIS, Leaflet, or Mapbox \ No newline at end of file diff --git a/docs/api/index.md b/docs/api/index.md index df750af..3149d84 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -22,3 +22,14 @@ Example using query parameter: ```bash curl https://your-reitti-instance/api/v1/latest-location?token=your-api-token ``` + +### Available Endpoints + +| Endpoint | Description | +|---------------------------------------|--------------------------------------------------------------------------------------------------------| +| [Latest Location](latest-location.md) | Retrieve the most recent location point for a user. Useful for monitoring and health checks. | +| [GPX Import](gpx-import.md) | Upload GPX files to import location data programmatically. Supports automated batch imports. | +| [GPX Export](gpx-export.md) | Export location data as GPX files for a specified date range. Useful for backups and data portability. | +| [Visits](visits.md) | Retrieve visit data for places within a date range and optional geographic bounding box. | +| [Ingest](ingest.md) | Send location data directly to Reitti for processing and storage. Supports Owntracks format. | +| [GeoJSON](geojson.md) | Export and import location data in GeoJSON format for use with GIS tools and custom applications. | diff --git a/docs/api/ingest.md b/docs/api/ingest.md index c89226d..a1be6ce 100644 --- a/docs/api/ingest.md +++ b/docs/api/ingest.md @@ -13,6 +13,12 @@ The Ingest Data API endpoint allows you to send location data directly to Reitti ``` POST /api/v1/ingest/owntracks?token=API-TOKEN ``` +or +``` +POST /api/v1/ingest/gpslogger?token=API-TOKEN +``` + +Instead of the `token` parameter, you can also use the `X-API-Token` header for enhanced security. ### Usage diff --git a/docs/assets/js/scripts.js b/docs/assets/js/scripts.js deleted file mode 100644 index 535e474..0000000 --- a/docs/assets/js/scripts.js +++ /dev/null @@ -1,52 +0,0 @@ -document.addEventListener("DOMContentLoaded", function() { - const path = window.location.pathname; - const match = path.match(/(.*\/)(?:v?\d+\.\d+|latest)\//); - const base_path = match ? match[1] : path.substring(0, path.lastIndexOf('/') + 1); - const json_url = `${base_path}versions.json`; - const stargazers_element = document.querySelector('header div div:nth-child(3) a'); - - if (!stargazers_element) { - console.warn("Could not find the stargazers element to attach the version selector."); - return; - } - fetch(json_url) - .then(response => response.json()) - .then(data => { - const container = document.createElement("div"); - container.style.display = "flex"; - container.style.alignItems = "center"; - container.style.marginLeft = "12px"; // Space between stars and version - - // 2. Create the select element - const select = document.createElement("select"); - select.id = "version-selector"; - select.style.padding = "4px 24px 4px 8px"; - select.style.border = "1px solid #444"; - select.style.borderRadius = "6px"; - select.style.fontSize = "12px"; - select.style.fontWeight = "600"; - select.onchange = function() { window.location.href = this.value; }; - - // 3. Populate options - const currentPath = window.location.pathname; - data.forEach(v => { - const opt = document.createElement("option"); - const isLatest = v.aliases.includes("latest"); - - // If it's the latest, point to the /latest/ alias instead of the version folder - opt.value = isLatest ? `${base_path}/latest/` : `${base_path}/${v.version}/`; - - opt.textContent = isLatest ? `${v.title} (latest)` : v.title; - - if (currentPath.includes(`/${v.version}/`) || (isLatest && currentPath.includes('/latest/'))) { - opt.selected = true; - } - select.appendChild(opt); - }); - - container.appendChild(select); - - stargazers_element.insertAdjacentElement('afterend', container); - }) - .catch(error => console.error("Error loading versions:", error)); -}); \ No newline at end of file diff --git a/docs/configurations/devices.md b/docs/configurations/devices.md new file mode 100644 index 0000000..e90d53f --- /dev/null +++ b/docs/configurations/devices.md @@ -0,0 +1,87 @@ +--- +title: "Devices" +description: "Manage multiple tracking sources and build your timeline" +weight: 5 +tags: [ "configuration" ] +--- + +|since|v5.0.0|.version-badge| + +Reitti v5 introduces **Devices** as a core concept for managing location data from multiple sources. Each device +represents a tracking source (e.g., a phone, a Home Assistant integration, or a custom script), allowing you to organize +and visualize data independently before merging it into your personal timeline. + +### Why Use Devices? + +Devices give you the flexibility to: + +- **Track Multiple Sources**: Ingest location data from different apps, devices, or integrations simultaneously +- **Organize Your Data**: Keep sources separate until you are ready to combine them +- **Color-Code Paths**: Each device can have its own color, making it easy to distinguish sources on the map +- **Control Visibility**: Show or hide a device on the map with a single toggle +- **Disable Inactive Sources**: Prevent further data ingestion and hide the device from other parts of Reitti + +### How It Works + +1. When data is ingested into the **default device**, your personal timeline is automatically updated and recalculated. +2. For any **additional devices** you create, you need to **manually stitch** together slices of GPS data to merge them + into your timeline. This is done in the [Workbench](../usage/workbench.md). +3. The stitching process lets you select specific time ranges from a device and combine them with the default device's + data, giving you full control over your final timeline. + +### Configuration + +To configure devices: + +1. Navigate to **Settings > Devices** +2. You will see a list of all devices, including the default device created during migration +3. Configure each device's settings as desired +4. Save your settings to apply the configuration + +### Device Settings + +Each device has the following configurable properties: + +- **Name**: A friendly name to identify the device (e.g., "Phone," "GPS Tracker," "Home Assistant," "Car Tracker") +- **Color**: The color used to draw the device's path on the map. Helps visually distinguish multiple sources +- **Show on Map**: A checkbox that enables or disables the device's visibility on the main map. Unchecked devices still + ingest data, but their paths are hidden +- **Disabled**: Completely disables the device. When disabled: + - Data cannot be ingested into the device + - The device is hidden from other places in Reitti (e.g., **Settings > Integrations**) + - The device's path is not shown on the map + +![Device Configuration](../img/device-configuration.png) + +### Default Device vs. Additional Devices + +| Feature | Default Device | Additional Devices | +|-------------------------------|----------------|--------------------| +| **Auto-updates timeline** | Yes | No | +| **Manual stitching required** | No | Yes | +| **Can be disabled** | Yes | Yes | +| **Can be renamed** | Yes | Yes | +| **Colour-coded path** | Yes | Yes | + +### Best Practices + +- **Use the default device for your primary tracking source**: This ensures automatic timeline updates without manual + intervention +- **Create additional devices for secondary sources**: For example, a work phone, a shared family device, or a + temporary tracker +- **Stitch data regularly**: If you use multiple devices, periodically merge their data in + the [Workbench](../usage/workbench.md) to keep your timeline complete +- **Name devices clearly**: Use descriptive names to easily identify each source +- **Disable unused devices**: Prevents accidental data ingestion and keeps your settings clean + +### Data Merging + +To stitch data from an additional device into your timeline: + +1. Go to the [Workbench](../usage/workbench.md) +2. Select the device you want to merge from +3. Choose the time slices of GPS data you want to include +4. Confirm the merge — the selected time slice will replace the data from your default device's timeline + +Once merged, the data becomes part of your permanent timeline and is automatically recalculated alongside future default +device data. \ No newline at end of file diff --git a/docs/configurations/map-styles.md b/docs/configurations/map-styles.md new file mode 100644 index 0000000..db8c5de --- /dev/null +++ b/docs/configurations/map-styles.md @@ -0,0 +1,117 @@ +--- +title: "Map Styles" +description: "Customize the look of your map with built-in and custom styles" +weight: 5 +tags: ["configuration"] +--- + +|since|v5.0.0|.version-badge| + +Reitti v5 introduces **Map Styles** as a first-class configuration option, allowing you to customize the look and feel of your map. You can choose from built-in Reitti styles, create your own JSON-based styles, or use raster tile sources. + +### Why Use Custom Map Styles? + +Custom map styles let you: + +- **Personalize Your Map**: Choose colors, fonts, and detail levels that suit your preferences +- **Optimize for Different Use Cases**: Use a dark style for low-light environments or a colorful style for better contrast +- **Integrate Professional Tile Services**: Use services like MapTiler, Mapbox, or self-hosted tile servers +- **Share Styles Across Users**: Admin users can prepare styles for less experienced users + +### How It Works + +1. Map styles define how tiles are rendered on the map – colors, labels, roads, water, and more +2. You can use one of the built-in Reitti styles or create your own +3. Styles can be JSON-based (Style JSON) or raster-based (tile URL templates) +4. Requests can be proxied through Reitti to leverage the built-in tile cache for faster load times + +### Configuration + +To configure map styles: + +1. Navigate to **Settings > Map Styles** +2. Choose between **Built-in Styles** or **Custom Styles** +3. Configure your preferred settings +4Save your settings to apply the new style + +![Map Styles](../img/map-styles.png) + +### Built-in Styles + +Reitti ships with two built-in styles: + +- **Default Reitti**: A dark theme optimized for location data visualisation +- **Colored Reitti**: A lighter, more colorful variant with better contrast for certain environments + +These styles are always available and cannot be deleted. + +### Custom Styles + +You can create your own map styles in two ways: + +#### 1. JSON-based Styles + +Style JSON follows the [MapLibre Style Specification](https://maplibre.org/style-spec/). You can either: + +- **URL-based**: Provide a URL pointing to a hosted `style.json` document (e.g., from [MapTiler](https://cloud.maptiler.com/maps/)) +- **Paste JSON**: Obtain the complete Style JSON (e.g., created with [Maputnik](https://maplibre.org/maputnik/)) and paste it directly into the **Style JSON** field + +#### 2. Raster-based Styles + +If you prefer a simple raster tile source, you can: + +- **Tile URL Template**: Provide a tile URL template (e.g., `https://example.com/tiles/{z}/{x}/{y}.png`) +- **TileJSON URL**: Provide a URL to a `tile.json` document that defines the raster source + +### Proxy Settings + +You can choose whether all tile requests should be proxied through Reitti. + +**Proxy enabled (recommended):** +- Tile requests pass through the built-in tile cache for faster subsequent load times +- Useful when using external tile services with rate limits or when you want to cache tiles locally + +**Proxy disabled:** +- Tile requests go directly to the tile server +- No caching layer. Useful for local tile servers where caching is unnecessary + +### Sharing Styles (Admin Only) + +If you are an **admin user**, you can choose to share a custom map style with other users. This allows you to prepare a map style once and make it available to less experienced users, who can then select it from their own settings without needing to configure anything. + +Shared styles appear automatically in other users' **Map Styles** settings. Users cannot modify or delete a shared style, but they can still select it for their own map. + +### Capabilities: 3D Buildings, Terrain, and Satellite + +If your custom Style JSON is configured correctly, Reitti will automatically detect and enable advanced map features such as 3D buildings, terrain, hillshading, and satellite overlay. No additional configuration is needed. Reitti scans the style and activates the relevant +controls. + +The following elements must be present in your Style JSON for each capability to be recognized: + +#### Terrain + +- A **source** with `"type": "raster-dem"` must be defined in the `sources` object. +- A **layer** with `"type": "hillshade"` must be present in the `layers` array. + +When both are detected, the 3D terrain toggle becomes available in the map view. + +#### Satellite Layer + +- A **raster source** with a URL or tile pattern typically containing `satellite` in the identifier or URL. Reitti checks for known satellite patterns in raster layers. + +When a satellite layer is detected, the map view will enable the satellite overlay toggle. + +#### 3D Buildings + +- One or more **layers** with `"type": "fill-extrusion"` where either the layer `id` or `source-layer` contains the word `building` (case-insensitive). + +When 3D building layers are found, the 3D buildings toggle becomes available in the map view. + +**Note:** These capabilities are only available for **JSON-based styles** (URL or pasted JSON). Raster-based styles do not support these advanced features. + +### Best Practices + +- **Start with built-in styles**: Use the default or colored Reitti style before creating custom ones +- **Use Maputnik for JSON styling**: The [Maputnik editor](https://maplibre.org/maputnik/) is the recommended tool for visually designing Style JSON +- **Enable proxy for external tile services**: This reduces load times and respects rate limits +- **Share styles if you manage multiple users**: Create a consistent map experience across your instance diff --git a/docs/img/device-configuration.png b/docs/img/device-configuration.png new file mode 100644 index 0000000..85e10bc Binary files /dev/null and b/docs/img/device-configuration.png differ diff --git a/docs/img/map-styles.png b/docs/img/map-styles.png new file mode 100644 index 0000000..cda54ae Binary files /dev/null and b/docs/img/map-styles.png differ diff --git a/docs/img/metadata-dialog.png b/docs/img/metadata-dialog.png new file mode 100644 index 0000000..3f6a786 Binary files /dev/null and b/docs/img/metadata-dialog.png differ diff --git a/docs/img/multiple-users.png b/docs/img/multiple-users.png index bca5a96..a2756c9 100644 Binary files a/docs/img/multiple-users.png and b/docs/img/multiple-users.png differ diff --git a/docs/img/workbench-actions.png b/docs/img/workbench-actions.png new file mode 100644 index 0000000..0d2916d Binary files /dev/null and b/docs/img/workbench-actions.png differ diff --git a/docs/img/workbench-stitching.png b/docs/img/workbench-stitching.png new file mode 100644 index 0000000..6780cc2 Binary files /dev/null and b/docs/img/workbench-stitching.png differ diff --git a/docs/img/workbench.png b/docs/img/workbench.png new file mode 100644 index 0000000..57498a1 Binary files /dev/null and b/docs/img/workbench.png differ diff --git a/docs/index.md b/docs/index.md index e82e391..2cc9479 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,14 +4,14 @@ description: "Personal location tracking and analysis application that transform weight: 0 --- -## Reitti - Personal Location Tracking +## Reitti – Personal Location Tracking Reitti is a comprehensive personal location tracking and analysis application that helps you understand your movement patterns and significant places. The name "Reitti" comes from Finnish, meaning "route" or "path". ### Screenshots #### Main View -![Main View](./img/main.png) +![Main View](img/main.png) #### Multiple Users View ![Multiple Users View](./img/multiple-users.png) @@ -65,4 +65,4 @@ This will make Reitti available at http://localhost:8080 with default credential ### License -Reitti is licensed under the MIT License. +Reitti is licensed under the GNU Affero General Public License Version 3 (AGPLv3) License. diff --git a/docs/infrastructure/docker-config.md b/docs/infrastructure/docker-config.md new file mode 100644 index 0000000..d9d7f0d --- /dev/null +++ b/docs/infrastructure/docker-config.md @@ -0,0 +1,157 @@ +--- +title: "Docker Compose Configuration" +description: "Reference of all environment variables available when deploying Reitti with Docker Compose" +weight: 2 +tags: [ "configuration" ] +--- + +## Overview + +When running Reitti using Docker Compose, all configuration is provided through environment variables. This page +documents every supported variable, its default value, and a brief description of its purpose. + +> **Note:** The OpenID Connect (OIDC) related variables are described in detail on the +> [OpenID Connect](./oidc.md) page. They are listed here for completeness, but +> refer to that page for the full OIDC configuration guide. + +--- + +### Server and Context Path + +| Variable | Description | Default Value | Example Value | +|:-----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:-----------------------------| +| `BASE_PATH` | Base path used by the embedded servlet container. If you want to serve Reitti behind a reverse proxy under a sub‑path, set this to that sub‑path (e.g., `/reitti`). | `/` | `/reitti` | +| `LOGGING_LEVEL` | Logging level for application classes (`com.dedicatedcode.reitti`). Choices: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`. | `INFO` | `DEBUG` | +| `ADVERTISE_URI` | Public URI of the Reitti instance. Used for external references such as links in emails. | *(empty)* | `https://reitti.example.com` | +| `DANGEROUS_LIFE` | When set to `true`, enables the background data‑management endpoints (clean data, purge, etc.). **Use with caution.** | `false` | `true` | + +--- + +### Application Runtime + +| Variable | Description | Default Value | Example Value | +|:--------------|:-------------------------------------------------------------------------------------------------------------------------------------|:--------------|:------------------------------| +| `SERVER_PORT` | Port on which the application server listens. | `8080` | `8080` | +| `APP_UID` | User ID under which the application process runs inside the container. | `1000` | `1000` | +| `APP_GID` | Group ID under which the application process runs inside the container. | `1000` | `1000` | +| `JAVA_OPTS` | Additional JVM options passed to the Java process. | *(empty)* | `-Xmx512m -Xms256m` | + +--- + +### PostgreSQL / PostGIS Database + +| Variable | Description | Default Value | Example Value | +|:-------------------|:---------------------------------------------|:--------------|:-----------------| +| `POSTGIS_HOST` | Hostname of the PostgreSQL / PostGIS server. | `postgis` | `db.example.com` | +| `POSTGIS_PORT` | Database port. | `5432` | `5432` | +| `POSTGIS_DB` | Database name. | `reittidb` | `reittidb` | +| `POSTGIS_USER` | Database username. | `reitti` | `reitti` | +| `POSTGIS_PASSWORD` | Database password. | `reitti` | `s3cret!` | + +--- + +### Redis Cache + +| Variable | Description | Default Value | Example Value | +|:---------------------|:-------------------------------------------------------------------------|:--------------|:--------------------------| +| `REDIS_HOST` | Hostname of the Redis server. | `redis` | `redis.example.com` | +| `REDIS_PORT` | Redis port. | `6379` | `6379` | +| `REDIS_USERNAME` | Username for Redis authentication (leave empty if not needed). | *(empty)* | `default` | +| `REDIS_PASSWORD` | Password for Redis authentication. | *(empty)* | `r3d!s$3cr3t` | +| `REDIS_DATABASE` | Redis database index. | `0` | `1` | +| `REDIS_CACHE_PREFIX` | Prefix added to all cache keys in Redis. | *(empty)* | `reitti:` | + +--- + +### Tile Cache + +| Variable | Description | Default | Example Value | +|:---------------|:----------------------------------------------------------------------------------------------------|:----------------------|:----------------------------| +| `TILES_CACHE` | URL of our external tile cache (e.g. a tile‑proxy service). Map tiles are fetched through this URL. | `http://tile-cache` | `http://tiles.local:8080` | + +--- + +### Local Authentication + +| Variable | Description | Default Value | Example Value | +|:----------------------|:------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:--------------| +| `DISABLE_LOCAL_LOGIN` | When `true`, disables login with username / password and clears existing stored passwords. Use alongside OIDC to enforce SSO-only access. | `false` | `true` | + +--- + +### OpenID Connect (OIDC) + +Full configuration details are covered on the [OpenID Connect](./oidc.md) page. The table below lists all OIDC +environment +variables for quick reference. + +| Variable | Description | Default Value | Example Value | +|:-----------------------------|:---------------------------------------------------------------------------------------------------------------|:----------------------|:-----------------------------------| +| `OIDC_ENABLED` | Whether to enable OIDC authentication. | `false` | `true` | +| `OIDC_SIGN_UP_ENABLED` | Whether new users can self‑register via OIDC. When `false`, only existing users can log in. | `true` | `false` | +| `OIDC_CLIENT_ID` | Client ID issued by the OIDC provider. | *(empty)* | `reitti` | +| `OIDC_CLIENT_SECRET` | Client secret issued by the OIDC provider. | *(empty)* | `F0oxfg8b2rp5X97YPS92C2ERxof1oike` | +| `OIDC_ISSUER_URI` | Issuer URI of the OIDC provider (e.g. `https://accounts.google.com`). | *(empty)* | `https://auth.example.com` | +| `OIDC_SCOPE` | Comma‑separated list of OIDC scopes requested during authentication. | `openid,profile` | `openid,profile,email` | +| `OIDC_AUTHENTICATION_METHOD` | Authentication method used by the OIDC client. Supported: `client_secret_basic`, `client_secret_post`, `none`. | `client_secret_basic` | `client_secret_basic` | + +--- + +### Data Import / Processing + +| Variable | Description | Default Value | Example Value | +|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:--------------| +| `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` | +| `INGESTION_MAX_BATCH_SIZE` | Maximum number of raw location points the server will wait before flushing API request from the ingestion endpoint. | `100` | `500` | +| `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` | + +--- + +## Example `docker-compose.yml` snippet + +The following snippet shows how the environment variables can be placed under the `reitti` service: + +```yaml +services: + reitti: + image: dedicatedcode/reitti:latest + environment: + # Base path & logging + - BASE_PATH=/ + - LOGGING_LEVEL=INFO + - ADVERTISE_URI=https://reitti.example.com + + # Application runtime + - SERVER_PORT=8080 + - APP_UID=1000 + - APP_GID=1000 + - JAVA_OPTS=-Xmx512m + + # Database + - POSTGIS_HOST=postgis + - POSTGIS_PORT=5432 + - POSTGIS_DB=reittidb + - POSTGIS_USER=reitti + - POSTGIS_PASSWORD=reitti + + # Redis + - REDIS_HOST=redis + - REDIS_PORT=6379 + - REDIS_DATABASE=0 + + # Tile cache + - TILES_CACHE=http://tile-cache + + # Data management (import/export) + - DANGEROUS_LIFE=false + + # Ingestion tuning + - PROCESSING_BATCH_SIZE=10000 + - INGESTION_MAX_BATCH_SIZE=100 + - INGESTION_MAX_IDLE_TIME=5 +``` + +OIDC variables are omitted in the snippet above; see the [OpenID Connect](./oidc.md) page for how to add them. + +For a complete working setup, refer to the [quick‑start guide](../index.md) and the provided +`docker-compose.yml` in the repository. diff --git a/docs/upgrade.md b/docs/upgrade.md index c18061c..1bebdc7 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -7,21 +7,165 @@ tags: ["upgrade", "migration", "version"] # Upgrading Reitti -Reitti follows (https://semver.org/), which means: +Reitti follows [Semantic Versioning](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. +For most upgrades, simply pulling the latest versioned Docker image or updating the source code is enough. Only upgrades between major versions require special attention. +--- + +## Upgrading from v4 to v5 + +> ⚠️ **This is a Major Upgrade** +> Reitti v5 introduces **Devices** and changes how map tiles are handled. +> If you skip the configuration steps below, your map may appear dark or your location data may stop syncing. + +### Pre-Upgrade Checklist + +Before starting, ensure you have: + +- [ ] **Backed up your database** (Always recommended before major version changes). +- [ ] **Saved your current `docker-compose.yml`** (For reference if you need to rollback). + +--- + +### ⚠️ Performance Warning + +**This upgrade may take a significant amount of time depending on your database size.** + +During the upgrade process, Reitti performs two time-consuming operations: + +1. **GPS Data Migration:** All GPS points are copied from the legacy table to the new table associated with the default + device. +2. **Index Creation:** An index is created on the `api_token_usages` table to support the new architecture. + +**Optimization Tip:** +If you have a large database and want to speed up the upgrade, you can clear the `api_token_usages` table before running +the update. This removes the usage history but significantly reduces the time required for index creation. + +**Run this command before starting the upgrade:** + +```bash +sudo docker compose exec postgis psql -U reitti -d reittidb --command "DELETE FROM api_token_usages" +``` + +--- + +### Step 1: Update Docker Configuration + +You must update your `docker-compose.yml` to match the new architecture. + +#### 1.1 Update Image Tags + +**Action:** Change image tags from `:next` to `:5` (explicit version). + +```yaml +services: + reitti: + image: dedicatedcode/reitti:5 # Was :next + tile-cache: + image: dedicatedcode/reitti-tile-cache:5 # Was :next +``` + +**Why this is required:** + +- **Explicit Versioning:** Using `:5` ensures you are upgrading to the exact major version intended, avoiding unexpected + changes if `:latest` shifts to a newer major version (e.g., 6.0) before you are ready. +- **Stability:** The `:next` tag points to the next branch, which is unstable for production. +- **Note:** The `:next` tag was included in the official docker-compose examples for a short period during development. + If your configuration uses `:next`, it likely means you copied it during that window. + +#### 1.2 Update Tile Cache Service + +**Action:** Ensure the `tile-cache` service is using the new image version (see 1.1) and **remove the `healthcheck` +block**. + +```yaml +services: + tile-cache: + image: dedicatedcode/reitti-tile-cache:5 + # Remove this block entirely: + # healthcheck: + # test: ["CMD", "curl", "-s", "http://127.0.0.1/osm/0/0/0.png"] +``` + +**Why this is required:** + +- **Image Update:** The tile cache service in v5 handles URL proxying differently. The old image cannot resolve the new + map style URLs, causing the map to break. +- **Healthcheck Removal:** The healthcheck logic is now built directly into the Docker image. Having both the + user-defined block and the built-in one can cause startup conflicts or resource contention. + +#### 1.3 Apply Changes + +Run the following commands to pull and restart: + +```bash +docker compose pull +docker compose up -d +``` + +--- + +### Step 2: Verify Critical Functionality + +After the containers restart, perform these checks to ensure the upgrade was successful. + +#### 2.1 Map Tiles + +**Action:** Open Reitti in your browser. + +- **If the map is displayed in dark mode:** Go to **Settings > Map Styles** and select "Colored Reitti". +- **If the map is broken:** Check logs with `docker compose logs tile-cache`. + +**Why this is required:** +For consistency and security, all users are reset to the **default (dark) Reitti style** on upgrade. If you were using +the "Colored Reitti" style, you must manually re-enable it. + +#### 2.2 API Tokens & Devices + +**Action:** Go to **Settings > API Tokens** and verify your tokens have a **Device** attached. + +**Why this is required:** +v5 introduces **Devices** as a core concept. + +- **Tokens without a device** can only **read data** (they cannot ingest location data). +- **Tokens with a device** can ingest data (OwnTracks, HTTP, etc.). +- While Reitti automatically links existing tokens to a default device, you must verify this to ensure your mobile apps + or Home Assistant integrations can still push location data. + +--- + +### Step 3: Optional Cleanup + +- [ ] **Reorganize Devices:** If you have multiple users or devices, create specific devices and assign tokens + accordingly. +- [ ] **Import Map Styles:** If you have custom map styles, import them via **Settings > Map Styles**. +- [ ] **Remove Old Config:** Clean up any remaining `:next` tags or custom environment variables from previous versions. + +--- + +### Troubleshooting + +| Problem | Likely Cause | Solution | +|:-------------------------|:--------------------------|:-----------------------------------------------------| +| **Map is not displayed** | Tile Cache image outdated | Update `tile-cache` to `:5` or `:latest` | +| **Map is in dark mode** | Map style not selected | Manually select "Colored Reitti" in Settings | +| **Data ingestion fails** | Token has no Device | Go to **Settings > API Tokens** and link to a Device | +| **Service won't start** | Conflicting Healthcheck | Remove `healthcheck` block from `docker-compose.yml` | +| **Tiles not loading** | URL Proxy Error | Check `docker compose logs tile-cache` | + +--- + ## 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. +*Note: This section is for users still on v3. If you are upgrading from v4 to v5, skip this section.* ### 1. RabbitMQ Removal - RabbitMQ is no longer required. Remove all RabbitMQ-related configuration from your `docker-compose.yml`: **Remove these services:** @@ -43,7 +187,6 @@ environment: ``` ### 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. @@ -52,7 +195,6 @@ Photon is now configured like other reverse geocoding services through the web i 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 @@ -70,7 +212,6 @@ On first start, Reitti will automatically add Paikka to your geocoding services 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:** @@ -84,7 +225,6 @@ environment: 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`:** @@ -100,7 +240,6 @@ services: ``` ### 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. @@ -108,13 +247,12 @@ After making these changes: 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 + - 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. diff --git a/docs/usage/main-view.md b/docs/usage/main-view.md index 7bf06ff..dc6bc86 100644 --- a/docs/usage/main-view.md +++ b/docs/usage/main-view.md @@ -13,54 +13,72 @@ The main view is the central interface of Reitti where you can visualize and int Located in the top navigation bar, the main menu provides access to all major sections of Reitti: -- **Timeline** – The main view showing your location data on a map (this page) -- **Memories** – Create and manage location-based memories (see [Memories](../memories/index.md)) -- **Statistics** – View detailed analytics of your movement patterns -- **Settings** – Configure application preferences and integrations -- **Enter Live-Mode** - Switch to real-time location tracking -- **Enter Fullscreen** – Expand the interface to fullscreen view -- **Logout** – Sign out of your Reitti account +- **Timeline**: The main view showing your location data on a map (this page) +- **Memories**: Create and manage location-based memories (see [Memories](../memories/index.md)) +- **Workbench**: Merge different timelines from multiple devices. Edit single or multiple location points. (see [Workbench](workbench.md) +- **Statistics**: View detailed analytics of your movement patterns +- **Settings**: Configure application preferences and integrations +- **Enter Live-Mode**: Switch to real-time location tracking +- **Enter Fullscreen**: Expand the interface to fullscreen view +- **Logout**: Sign out of your Reitti account ## Timeline Component The timeline component is located on the left side of the interface and displays your location history chronologically: ### User Switcher -If you have access to other users' data (via [Share Access](share-access.md) or [Reitti Integration](../integrations/reitti.md)), a user switcher appears at the top of the timeline. This allows you to: +If you have access to other users' data (via [Share Access](share-access.md) or [Reitti Integration](../integrations/reitti.md)) or more than one device configure (via [Devices](../configurations/devices.md)), a user switcher appears at the top of the timeline. This allows +you to: + - Switch between different users' timelines - View location data for multiple users - Compare movement patterns across users +- Clicking on a user or device avatar focuses the map on that user's or device location +- Enable follow user mode for a single user. This instructs reitti to focus only on this user during a page refresh. ### Chronological List Below the user switcher, the timeline shows a chronological list of all visits and trips during the selected time range: -- **Visits** – Periods where you stayed at a specific location -- **Trips** – Movement between locations with transportation mode information +- **Visits**: Periods where you stayed at a specific location +- **Trips**: Movement between locations with transportation mode information ### Interactive Features -- **Click to Zoom** - Clicking on a timeline entry zooms the map to that element - - For trips: Highlights the route on the map - - For visits: Centers the map on the location -- **Click Again to Restore** – Clicking the same entry again restores the previous map view -- **Edit Visits** – When a visit is selected, hover over it to reveal an edit icon (pencil) that takes you to [Edit Place](place-edit.md) -- **Edit Trips** – When a trip is selected, hover over it and click the edit icon to change the transportation mode - +- **Click to Zoom**: Clicking on a timeline entry zooms the map to that element + - For trips: Highlights the route on the map + - For visits: Centers the map on the location +- **Click Again to Restore**: Clicking the same entry again restores the previous map view +- **Edit Visits**: When a visit is selected, hover over it to reveal an edit icon (pencil) that takes you to [Edit Place](place-edit.md) +- **Edit Trips**: When a trip is selected, hover over it and click the edit icon to change the transportation mode + +### Metadata +You can enrich your visits and trips with metadata such as mood, tags, and notes. When a visit or trip is selected, hover over it to reveal a metadata icon (e.g., a smiley or note icon). Clicking the icon opens a dialog where you can: + +- **Mood**: Select a mood from the following options: + - 😊 Happy + - 😌 Relaxed + - 🧗 Adventurous + - 😴 Tired + - 😰 Stressed +- **Tags**: Add custom tags (e.g., "work", "commute", "weekend") to categorize the element. +- **Notes**: Attach free-form text notes for personal context. + +![Metadata Dialog](../img/metadata-dialog.png) ## Date Picker The date picker is a horizontal interface that allows flexible navigation through your location history. It displays dates as interactive elements with multiple modes and selection options: ### Date Selection -- **Single Date Selection** – Click on a date to select it, loading data and updating the timeline -- **Range Selection Mode** – Click a selected date again to enter range selection mode, then click another date to select a range -- **Range Modification** – In range selection mode, click any other date to change the range boundaries -- **Range Clearing** – In range selection mode, click the start or end date to clear the selection and exit range mode +- **Single Date Selection**: Click on a date to select it, loading data and updating the timeline +- **Range Selection Mode**: Click a selected date again to enter range selection mode, then click another date to select a range +- **Range Modification**: In range selection mode, click any other date to change the range boundaries +- **Range Clearing**: In range selection mode, click the start or end date to clear the selection and exit range mode ### Navigation Methods -- **Horizontal Scrolling** – Drag the date slider left/right or use horizontal scroll to navigate through time -- **Mode Switching** – Scroll up/down to switch between different time granularity modes: - - **Day Mode** – View individual days - - **Month Mode** – View months - - **Year Mode** – View years +- **Horizontal Scrolling**: Drag the date slider left/right or use horizontal scroll to navigate through time +- **Mode Switching**: Scroll up/down to switch between different time granularity modes: + - **Day Mode**: View individual days + - **Month Mode**: View months + - **Year Mode**: View years ### Drill-Down Navigation When drilling into time periods: @@ -69,45 +87,43 @@ When drilling into time periods: - The date picker positions the selected period under the mouse cursor for intuitive navigation ### Advanced Range Selection -- **Year Ranges** – Select a year, click it again, then select another year to create a range from January 1 of the first year to December 31 of the second year -- **Month Ranges** – Similarly, select months to create ranges spanning from the first day of the first month to the last day of the second month -- **Arbitrary Ranges** – Combine different modes to create custom date ranges spanning days, months, or years - +- **Year Ranges**: Select a year, click it again, then select another year to create a range from January 1 of the first year to December 31 of the second year +- **Month Ranges**: Similarly, select months to create ranges spanning from the first day of the first month to the last day of the second month +- **Arbitrary Ranges**: Combine different modes to create custom date ranges spanning days, months, or years ## View Control The View Control component sits above the date picker and provides tools for controlling how your location data is visualized: ### Replay Controls -- **Start Replay** – Begins a replay of all your movements during the selected time range, animating your path on the map -- **Speed Control** – Adjusts the playback speed of the replay (slow, normal, fast) -- **Time Control Slider** – When opened, displays a slider above the View Control that allows you to scrub through the replay time to show specific ranges of interest +- **Start Replay**: Begins a replay of all your movements during the selected time range, animating your path on the map +- **Speed Control**: Adjusts the playback speed of the replay (slow, normal, fast, automatic, adaptive) +- **Time Control Slider**: When opened, displays a slider above the View Control that allows you to scrub through the replay time to show specific ranges of interest ### Today Button -- **Today** – Jumps to the current date and time, if not currently selected +- **Today**: Jumps to the current date and time, if not currently selected ### Map View Settings The map view control allows you to customize the map display with various settings: -- **3D View** - Enable/disable the 3D perspective view of the map -- **Render Buildings** - Toggle building rendering for more detailed urban environments -- **Globe Projection** – Switch between flat map and globe projection views -- **Terrain Layer** - Enable/disable terrain elevation visualization -- **Satellite View** - Toggle between map and satellite imagery -- **North Alignment** – Align the map with true north (disables automatic rotation) +- **3D View**: Enable/disable the 3D perspective view of the map +- **Render Buildings**: Toggle building rendering for more detailed urban environments +- **Globe Projection**: Switch between flat map and globe projection views +- **Terrain Layer**: Enable/disable terrain elevation visualization +- **Satellite View**: Toggle between map and satellite imagery +- **North Alignment**: Align the map with true north (disables automatic rotation) ### Settings Menu -- **Open Settings** – Access the main view settings menu for additional customization options - +- **Open Settings**: Access the main view settings menu for additional customization options ## Settings The Settings menu provides comprehensive control over how your location data is displayed and analyzed: ### Path Display Modes -- **Standard** – Displays optimized paths that balance detail with performance by not overwhelming the browser with all points in the time range -- **Raw Path** – Displays all location data points without any optimizations, showing the complete raw data -- **Edge Bundling** – Bundles paths based on proximity, making it easy to visualize your most frequently used routes within the selected time range +- **Standard**: Displays optimized paths that balance detail with performance by not overwhelming the browser with all points in the time range +- **Raw Path**: Displays all location data points without any optimizations, showing the complete raw data +- **Edge Bundling**: Bundles paths based on proximity, making it easy to visualize your most frequently used routes within the selected time range ### 24-Hour Aggregate Mode When enabled, this feature aligns all times to the day, allowing you to: @@ -116,50 +132,50 @@ When enabled, this feature aligns all times to the day, allowing you to: - When combined with the replay feature, all days in the selected time range are played simultaneously, showing aggregated daily patterns ### Interface Controls -- **Hide Timeline** – Toggle visibility of the timeline component on the left side -- **Hide Date Picker** – Toggle visibility of the date picker component +- **Hide Timeline**: Toggle visibility of the timeline component on the left side +- **Hide Date Picker**: Toggle visibility of the date picker component ## Live Mode Live mode provides real-time tracking functionality with a kiosk-style display: ### Real-time Tracking -- **Automatic Updates** – The display automatically updates as soon as new location data arrives -- **Latest Locations** – Shows the most recent known location of you and all connected users -- **User Avatars** – Each user is represented by their avatar on the map -- **Hover Information** – Hover over an avatar to display additional information including when the data was last updated +- **Automatic Updates**: The display automatically updates as soon as new location data arrives +- **Latest Locations**: Shows the most recent known location of you and all connected users +- **User Avatars**: Each user is represented by their avatar on the map +- **Hover Information**: Hover over an avatar to display additional information including when the data was last updated ### Multi-User Display -- **Connected Users** – View all users you have access to via [Share Access](share-access.md) or [Reitti Integration](../integrations/reitti.md) -- **Real-time Movement** – Watch as user locations update in real-time as they move +- **Connected Users**: View all users you have access to via [Share Access](share-access.md) or [Reitti Integration](../integrations/reitti.md) +- **Real-time Movement**: Watch as user locations update in real-time as they move ### Kiosk Mode -- **Continuous Display** – Ideal for wall-mounted displays or shared screens -- **Minimal Interface** – Clean, focused display optimized for at-a-glance viewing -- **Automatic Refresh** – No user interaction required to see updated locations +- **Continuous Display**: Ideal for wall-mounted displays or shared screens +- **Minimal Interface**: Clean, focused display optimized for at-a-glance viewing +- **Automatic Refresh**: No user interaction required to see updated locations ## Navigation Tips -- **Zoom Controls** – Use mouse wheel, +/- buttons, or double-click to zoom -- **Pan Navigation** – Click and drag to move around the map -- **Search Locations** – Use the search bar to find specific places -- **Fullscreen Mode** – Expand the map to fullscreen for better visibility -- **Quick Date Navigation** – Use the date picker's horizontal scroll and mode switching for efficient time travel -- **Interactive Timeline** – Click timeline entries to zoom to specific locations or trips -- **Multi-User Switching** – Use the user switcher in the timeline to view different users' data +- **Zoom Controls**: Use mouse wheel, +/- buttons, or double-click to zoom +- **Pan Navigation**: Click and drag to move around the map +- **Search Locations**: Use the search bar to find specific places +- **Fullscreen Mode**: Expand the map to fullscreen for better visibility +- **Quick Date Navigation**: Use the date picker's horizontal scroll and mode switching for efficient time travel +- **Interactive Timeline**: Click timeline entries to zoom to specific locations or trips +- **Multi-User Switching**: Use the user switcher in the timeline to view different users' data ## Getting the Most from the Main View -1. **Analyze Daily Patterns** – Use **24-Hour Aggregate Mode** to identify your regular routines and commute patterns -2. **Explore Movement History** – Switch between **Standard**, **Raw Path**, and **Edge Bundling** modes to analyze your movement data at different levels of detail -3. **Customize Your View** – Adjust map settings like **3D View**, **Terrain Layer**, and **Satellite View** to match your analysis needs -4. **Use Live Mode for Real-time Tracking** – Enable live tracking for current movement monitoring or set up a **Kiosk Mode** display for shared viewing -5. **Leverage Replay Features** – Use the **Replay Controls** with different speeds to review your movements over selected time ranges -6. **Compare Multi-User Data** – If you have access to other users' data, use the **User Switcher** to compare movement patterns and coordinate activities +1. **Analyze Daily Patterns**: Use **24-Hour Aggregate Mode** to identify your regular routines and commute patterns +2. **Explore Movement History**: Switch between **Standard**, **Raw Path**, and **Edge Bundling** modes to analyze your movement data at different levels of detail +3. **Customize Your View**: Adjust map settings like **3D View**, **Terrain Layer**, and **Satellite View** to match your analysis needs +4. **Use Live Mode for Real-time Tracking**: Enable live tracking for current movement monitoring or set up a **Kiosk Mode** display for shared viewing +5. **Leverage Replay Features**: Use the **Replay Controls** with different speeds to review your movements over selected time ranges +6. **Compare Multi-User Data**: If you have access to other users' data, use the **User Switcher** to compare movement patterns and coordinate activities ## View Mode Use Cases -- **Route Planning** – Use **Edge Bundling** mode to identify your most frequently traveled routes -- **Pattern Recognition** – Enable **24-Hour Aggregate Mode** to discover daily routines and habitual locations -- **Presentation Mode** – Use **Fullscreen** with a simplified interface for sharing your location history with others -- **Real-time Monitoring** - **Live Mode** is ideal for tracking current movements or monitoring multiple users simultaneously \ No newline at end of file +- **Route Planning**: Use **Edge Bundling** mode to identify your most frequently traveled routes +- **Pattern Recognition**: Enable **24-Hour Aggregate Mode** to discover daily routines and habitual locations +- **Presentation Mode**: Use **Fullscreen** with a simplified interface for sharing your location history with others +- **Real-time Monitoring**: **Live Mode** is ideal for tracking current movements or monitoring multiple users simultaneously \ No newline at end of file diff --git a/docs/usage/share-access.md b/docs/usage/share-access.md index 9e4691c..33d9a12 100644 --- a/docs/usage/share-access.md +++ b/docs/usage/share-access.md @@ -159,6 +159,52 @@ To optimize the multi-user map experience: ![Shares Access](../img/shared-access.png) + +## Owntracks Integration for User Visibility + +|since|v3.1.0|.version-badge| + +When using the [Owntracks mobile app](https://owntracks.org/) to report your location data into Reitti, you can also see other connected users directly within the Owntracks app. This is possible because Reitti responds to Owntracks ingestion requests with **cards** containing +user information, including: + +- **Profile image** (if available) +- **Display name** +- **Latest known location** + +This allows the Owntracks app to show a visual overview of all users you have access to, making it easy to see who is where at a glance. + +### Prerequisites + +For this feature to work: + +1. **Use the Owntracks App**: You must be using the Owntracks mobile app to report your location data into Reitti +2. **Configure the Owntracks Integration**: Your location data must be sent to Reitti via the (docs/integrations/mobile-apps.md) +3. **Have Other Users in Reitti**: You need to have other registered users in your Reitti instance whose location data you can view (either via magic links or direct user sharing) + +### How It Works + +When you open the Owntracks app, it will display a list of all users you have access to, showing: + +- **Profile Image**: Each user's profile picture (if set) +- **Display Name**: The user's name as configured in Reitti +- **Latest Known Location**: The most recent location data reported by that user + +This provides a quick, at-a-glance view of who is currently active and where they are, without needing to open the full Reitti dashboard. + +### Configuration + +No additional configuration is required beyond: + +- Setting up the [Owntracks integration](../integrations/mobile-apps.md) to report your data +- Having other users share their location data with you (via (#share-access-with-magic-links) or (#share-access-to-other-users)) + +### Limitations + +- Only users who have shared their location data with you will appear in the Owntracks app +- The feature requires the Owntracks app to be actively connected to your Reitti instance +- Location data is updated in real-time as users report their positions + + ### Best Practices for User Sharing - **Regular review**: Periodically check who has access to your data diff --git a/docs/usage/workbench.md b/docs/usage/workbench.md new file mode 100644 index 0000000..f2da453 --- /dev/null +++ b/docs/usage/workbench.md @@ -0,0 +1,125 @@ +--- +title: "Workbench" +description: "Merge, edit, and stitch location data from multiple devices" +weight: 1 +tags: ["usage", "workbench", "data-merge"] +--- + +|since|v5.0.0|.version-badge| + +The **Workbench** is Reitti's tool for merging and editing location data from multiple devices. It allows you to combine GPS data from different sources into your personal timeline, giving you full control over which data points are included. + +![Workbench Interface](../img/workbench.png) + +## Overview + +The Workbench consists of two main areas: + +- **Map Area** – Displays the path of the selected day ± 24 hours +- **Stitching Area** – A synced area with two timelines for merging data + +![Stitching Area](../img/workbench-stitching.png) + +### Map Area + +The map shows the selected device's path for the chosen day, with a ±24-hour window around it. When you select a timeframe in the stitching area, the corresponding path is highlighted on the map. + +### Stitching Area + +The stitching area is synced to the map and contains two timelines: + +- **Upper Timeline** – Displays data from your **main timeline** (the default device) +- **Lower Timeline** – Displays data from the **selected device** + +Both timelines show the same time range, allowing you to compare and merge data. + +## Stitching Process + +1. **Select a device** – Use the device picker to choose which device's data you want to merge +2. **Select a timeframe** – A slider overlays the device timeline, allowing you to: + - Move the start and end points independently + - Move the entire timeframe selection as a unit +3. **Preview on map** – The selected timeframe is highlighted on the map +4. **Insert** – Press the **Insert** button to add this slice to your main timeline +5. **Save** – All actions are performed locally. Only when you press **Save** are changes persisted to the server +6. **Recalculation** – After saving, all necessary data is recalculated. You can monitor progress under **Settings > Job Status** + +## Stitching Area Controls + +The lower timeline area includes the following controls: + +![Actions Bar](../img/workbench-actions.png) + +### Date Picker + +A date picker for navigating through the selected device's data. + +### Selection Mode + +Three modes for interacting with GPS data: + +| Key | Mode | Description | +|-----|-------------|----------------------------------------------| +| `1` | **Inspect** | View details of individual GPS points | +| `2` | **Select** | Select individual GPS points for editing | +| `3` | **Box** | Select multiple points using a box selection | + +### Help Menu + +The help menu provides keyboard shortcuts and tool descriptions. + +#### Keyboard Shortcuts + +**Selection** + +| Shortcut | Action | +|-----------------------------------|------------------------------------------| +| `Ctrl` + `←` / `→` | Previous / next point | +| `Ctrl` + `Shift` + `←` / `→` | Extend selection by one point | +| `Ctrl` + `Home` / `End` | Jump to first / last point in the window | +| `Ctrl` + `Shift` + `Home` / `End` | Extend selection to start / end | +| `Ctrl` + `A` | Select all points in the editable window | +| `Esc` | Clear selection | + +**Editing** + +| Shortcut | Action | +|----------|------------------------| +| `Delete` | Remove selected points | + +> **Note:** On macOS, `Cmd` works in place of `Ctrl`. + +### Device Picker + +Select which device's data you want to work with. + +### Delete Button + +Removes selected GPS points from the map. + +### Moving Points + +After selecting a GPS point, you can drag it to a new location on the map. This allows you to correct inaccurate location data. + +## Saving and Persistence + +All edits are performed **locally** in the browser. Changes are only saved to the server when you: + +1. Press the **Save** button +2. Confirm the save action + +After saving, the server recalculates your timeline. You can monitor the progress under **Settings > Job Status**. + +## Use Cases + +- **Correcting GPS drift** – Move inaccurate points to their correct location +- **Merging multiple devices** – Combine data from a phone and a car tracker into one timeline +- **Removing unwanted data** – Delete specific GPS points that should not appear in your timeline +- **Stitching time slices** – Select a timeframe from one device and insert it into your main timeline + +## Best Practices + +- **Use the preview** – Always check the map before inserting data +- **Save frequently** – Save your changes regularly to avoid losing work +- **Monitor job status** – Check **Settings > Job Status** to see when recalculations are complete +- **Start with small selections** – Begin with a small timeframe to verify the merge works correctly diff --git a/mkdocs.yml b/mkdocs.yml index 19a935d..70ceac7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,10 +24,5 @@ plugins: 'configurations/reitti-integration.md': 'integrations/reitti.md' markdown_extensions: - codehilite -extra: - version: - provider: mike -extra_javascript: - - assets/js/scripts.js extra_css: - assets/css/styles.css \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index e73a6b4..4f3f9b6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,6 +8,6 @@ dependencies = [ "mkdocs-awesome-nav>=3.3.0", "mkdocs-badges>=0.5.2", "mkdocs-redirects>=1.2.2", - "mkdocs-shadcn>=0.10.2", + "mkdocs-shadcn>=0.11.0", "click==8.2.1" ] diff --git a/theme/overrides/templates/footer.html b/theme/overrides/templates/footer.html index 7a79894..d4f284d 100644 --- a/theme/overrides/templates/footer.html +++ b/theme/overrides/templates/footer.html @@ -4,12 +4,14 @@
{% if config.site_author %} - Built by {{ config.site_author | parse_author}} — + Built by {{ config.site_author | parse_author}} — {% endif %} shadcn theme provided by @asiffer - — - edit this page on github + {% if page and page.file and page.file.edit_uri %} + — + edit this page on github + {% endif %}
diff --git a/uv.lock b/uv.lock index 819ed0a..78d870f 100644 --- a/uv.lock +++ b/uv.lock @@ -279,7 +279,7 @@ wheels = [ [[package]] name = "mkdocs-shadcn" -version = "0.10.2" +version = "0.11.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "bottle" }, @@ -287,9 +287,9 @@ dependencies = [ { name = "mkdocs" }, { name = "pymdown-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/68/c6/d86f2494c1e1bd80d07d4ccd83862e6b4306dd8a39a97e22c0d15e54156c/mkdocs_shadcn-0.10.2.tar.gz", hash = "sha256:cc37a5a2d998dfec2fbfa24c6b67d20c5bd8b53ad36a17e51ef6e1b865be08a3", size = 3161105, upload-time = "2026-03-19T10:12:32.422Z" } +sdist = { url = "https://files.pythonhosted.org/packages/23/09/9f391522008acd1df8eb864744a4dc0405a3023dd5d82381ccb435813923/mkdocs_shadcn-0.11.0.tar.gz", hash = "sha256:f7a6ff53ade8a40e7cde32ec1e24aef05e55935744c4ebd2abd1e00dd4232de2", size = 3466496, upload-time = "2026-06-19T11:18:24.217Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/15/73/ce6ebaaec752d90e774997e890b7a7cff6a0642c8dec9afd7ee8e047c9e0/mkdocs_shadcn-0.10.2-py3-none-any.whl", hash = "sha256:f3c4c5f7f4bf80506d6cf834c6a4201d0e447980020ad8fca145bdb46c20ede1", size = 1410494, upload-time = "2026-03-19T10:12:30.421Z" }, + { url = "https://files.pythonhosted.org/packages/79/12/112cafb8e0c27e25af751644a03d5229167636de815691c2c997bfb7e33a/mkdocs_shadcn-0.11.0-py3-none-any.whl", hash = "sha256:576a450bb679bcf11f0aacaa9f7023df82591f4cff61e2e7a807c283b9733c04", size = 1789009, upload-time = "2026-06-19T11:18:22.696Z" }, ] [[package]] @@ -528,7 +528,7 @@ requires-dist = [ { name = "mkdocs-awesome-nav", specifier = ">=3.3.0" }, { name = "mkdocs-badges", specifier = ">=0.5.2" }, { name = "mkdocs-redirects", specifier = ">=1.2.2" }, - { name = "mkdocs-shadcn", specifier = ">=0.10.2" }, + { name = "mkdocs-shadcn", specifier = ">=0.11.0" }, ] [[package]]