### Production Helm Setup with Ingress

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Example `values.yaml` for a production setup, including resource allocation, ingress configuration with TLS, and OIDC integration. Ensure `cert-manager.io/cluster-issuer` and `nginx.ingress.kubernetes.io/ssl-redirect` annotations are correctly configured for your environment.

```yaml
# production-values.yaml
# Resource allocation for production
backend:
  replicaCount: 2
  resources:
    limits:
      memory: 2Gi
      cpu: 2000m
    requests:
      memory: 1Gi
      cpu: 1000m

frontend:
  replicaCount: 2

postgres:
  persistence:
    enabled: true
    size: 50Gi
    storageClass: "fast-ssd"
  resources:
    limits:
      memory: 4Gi
      cpu: 2000m

# Ingress configuration
ingress:
  enabled: true
  className: nginx
  hostname: geopulse.example.com
  tls:
    enabled: true
    secretName: geopulse-tls
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"

# Application configuration
config:
  uiUrl: "https://geopulse.example.com"
  cookieDomain: ".example.com"
  authSecureCookies: true
  admin:
    email: "admin@example.com"
  oidc:
    enabled: true
    google:
      enabled: true
      clientId: "..."
      clientSecret: "..."
```

--------------------------------

### Complete k6 Test Setup with Exported Variables

Source: https://github.com/tess1o/geopulse/blob/main/tests/performance/README.md

Set up a comprehensive test environment by exporting multiple environment variables before running the k6 test. This example configures heavy load and production server details.

```bash
export BASE_URL=https://your-production-server.com
export NUM_TEST_USERS=20
export TEST_USER_PASSWORD=your-password
export TEST_DATA_START_DATE=2025-05-01T00:00:00.000Z
export TEST_DATA_END_DATE=2026-05-20T23:59:59.999Z
export LOAD_MULTIPLIER=4

k6 run scenarios/mixed-workload.js
```

--------------------------------

### Example High-Performance PostgreSQL Configuration

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/docker-compose.md

An example .env configuration for a high-performance setup requiring at least 4GB of container memory. This tune parameters like shared buffers, work memory, and WAL settings for demanding workloads.

```bash
# High-performance .env settings (requires 4GB+ container)
GEOPULSE_POSTGRES_SHARED_BUFFERS=1GB
GEOPULSE_POSTGRES_WORK_MEM=24MB
GEOPULSE_POSTGRES_MAINTENANCE_WORK_MEM=256MB
GEOPULSE_POSTGRES_EFFECTIVE_CACHE_SIZE=3GB
GEOPULSE_POSTGRES_MAX_WAL_SIZE=2GB
GEOPULSE_POSTGRES_WAL_BUFFERS=64MB
GEOPULSE_POSTGRES_PARALLEL_WORKERS=4
GEOPULSE_POSTGRES_IO_CONCURRENCY=200
GEOPULSE_POSTGRES_LOG_SLOW_QUERIES=1000
```

--------------------------------

### Initialize, Start, and Enable PostgreSQL on RHEL/Rocky/AlmaLinux

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Initializes the PostgreSQL 17 database cluster, starts the service, and enables it to start on system boot.

```bash
# Initialize database cluster (first time only)
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb

# Start and enable
sudo systemctl start postgresql-17
sudo systemctl enable postgresql-17
```

--------------------------------

### Start and Enable PostgreSQL on Ubuntu/Debian

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Starts the PostgreSQL service and configures it to start automatically on system boot.

```bash
sudo systemctl start postgresql
sudo systemctl enable postgresql
```

--------------------------------

### Install GeoPulse Interactively

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/kubernetes-helm.md

Launches the interactive script to guide the user through GeoPulse installation options.

```bash
./helm/install.sh
```

--------------------------------

### Install k6 on Windows

Source: https://github.com/tess1o/geopulse/blob/main/tests/performance/README.md

Installs k6 on Windows using Chocolatey. Ensure Chocolatey is installed first.

```powershell
choco install k6
```

--------------------------------

### Install k6 on macOS

Source: https://github.com/tess1o/geopulse/blob/main/tests/performance/README.md

Installs k6 using Homebrew on macOS. Ensure Homebrew is installed first.

```bash
brew install k6
```

--------------------------------

### Install Sudo Package

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Install the 'sudo' package if needed for consistency with instructions. Use 'apt-get' for Debian/Ubuntu and 'dnf' for RHEL-based systems.

```bash
apt-get install -y sudo  # Debian/Ubuntu
```

```bash
dnf install -y sudo      # RHEL/Rocky/Fedora
```

--------------------------------

### Get Events for Pod Startup Issues

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Retrieve Kubernetes events, sorted by timestamp, to diagnose why pods might not be starting correctly.

```bash
kubectl get events --sort-by='.lastTimestamp'
```

--------------------------------

### Install GeoPulse Helm Chart

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Install the GeoPulse Helm chart using `helm install`. Provide custom values via a file or command-line flags. This example uses a custom values file.

```bash
helm install geopulse ./helm/geopulse -f helm/examples/medium-deployment.yaml
```

--------------------------------

### Run SQL Setup Script

Source: https://github.com/tess1o/geopulse/blob/main/tests/performance/README.md

Executes the SQL script against the production PostgreSQL database to create test users and their GPS data.

```bash
psql -h <production-host> -p 5432 -U <username> -d geopulse -f create-test-users.sql
```

--------------------------------

### Docker Compose Configuration for Invitation Base URL

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/system-administration/configuration/admin-panel.md

Example of how to configure the base URL for invitation links using environment variables in a Docker Compose setup.

```yaml
services:
  geopulse:
    image: tess1o/geopulse:latest
    environment:
      GEOPULSE_INVITATION_BASE_URL: https://geopulse.example.com
      # ... other environment variables
```

--------------------------------

### Install GeoPulse with MQTT Broker Enabled

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Install the GeoPulse Helm chart with the MQTT broker enabled.

```bash
helm install geopulse ./helm/geopulse -f mqtt-values.yaml
```

--------------------------------

### Start Docker Compose with Overlay

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/system-administration/configuration/apprise-notifications.md

Command to start your Docker Compose services including the Apprise overlay. Ensure you use the correct compose file names.

```bash
docker compose -f docker-compose.yml -f docker-compose.apprise.yml up -d
```

--------------------------------

### Install Native GeoPulse Backend (ARM64 Modern)

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Installs the native ARM64 GeoPulse backend binary. This is for modern ARM64 architectures.

```bash
# Copy binary and set permissions
sudo cp geopulse-backend-native-arm64-${VERSION} /opt/geopulse/backend/geopulse-backend
sudo chmod +x /opt/geopulse/backend/geopulse-backend
sudo chown geopulse:geopulse /opt/geopulse/backend/geopulse-backend
```

--------------------------------

### Install Native GeoPulse Backend (AMD64 Modern)

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Installs the native AMD64 GeoPulse backend binary. This involves copying the downloaded file to the correct location and setting execute permissions and ownership.

```bash
# Copy binary and set permissions
sudo cp geopulse-backend-native-amd64-${VERSION} /opt/geopulse/backend/geopulse-backend
sudo chmod +x /opt/geopulse/backend/geopulse-backend
sudo chown geopulse:geopulse /opt/geopulse/backend/geopulse-backend
```

--------------------------------

### Install System Dependencies on Ubuntu/Debian

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Installs core dependencies, PostgreSQL 17 with PostGIS, and Nginx. Configures the timezone for PostgreSQL.

```bash
# Update package list
sudo apt-get update

# Install core dependencies (including timezone data and lsb-release for repository setup)
sudo apt-get install -y curl wget tar openssl ca-certificates tzdata lsb-release

# Configure timezone (required for PostgreSQL)
sudo ln -sf /usr/share/zoneinfo/UTC /etc/localtime
sudo dpkg-reconfigure -f noninteractive tzdata

# Install PostgreSQL 17 + PostGIS
sudo apt-get install -y postgresql-17 postgresql-17-postgis-3

# Install Nginx
sudo apt-get install -y nginx

# If using JVM backend, install Java 25
# sudo apt-get install -y openjdk-25-jre-headless
```

--------------------------------

### Verify Backend Installation

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Lists the contents of the backend directory to verify successful extraction.

```bash
ls -la /opt/geopulse/backend/quarkus-app/
```

--------------------------------

### Install Timezone Data and Set Localtime

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Install the necessary timezone data package and create a symbolic link for the system's localtime.

```bash
sudo apt-get install -y tzdata  # Ubuntu/Debian
```

```bash
# or: sudo dnf install -y tzdata  # RHEL/Rocky/Fedora
```

```bash
sudo ln -sf /usr/share/zoneinfo/UTC /etc/localtime
```

--------------------------------

### Install Apprise Docker Compose Overlay

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/system-administration/configuration/apprise-notifications.md

Use an overlay compose file to add the Apprise service to your Docker Compose setup. This ensures Apprise runs as a separate container.

```yaml
services:
  apprise-api:
    image: caronc/apprise:latest
    container_name: geopulse-apprise
    restart: unless-stopped
    ports:
      - "8000:8000"
```

--------------------------------

### Install GeoPulse with Minimal Configuration

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Install the GeoPulse Helm chart using a minimal values file for local development or testing.

```bash
helm install geopulse ./helm/geopulse -f minimal-values.yaml
```

--------------------------------

### k6 Environment Variables Example

Source: https://github.com/tess1o/geopulse/blob/main/tests/performance/README.md

This file serves as an example template for environment variables used by k6, typically containing sensitive information or runtime configurations.

```env
# Environment template
```

--------------------------------

### Install System Dependencies on RHEL/Rocky/AlmaLinux

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Installs core dependencies, PostgreSQL 17 with PostGIS, and optionally Nginx. Configures the timezone for PostgreSQL.

```bash
# Install core dependencies (including timezone data)
sudo dnf install -y curl wget tar openssl ca-certificates tzdata

# Configure timezone (required for PostgreSQL)
sudo ln -sf /usr/share/zoneinfo/UTC /etc/localtime

# Install PostgreSQL 17 + PostGIS
sudo dnf install -y postgresql17-server postgresql17-contrib postgis35_17

# Install Nginx (optional)
sudo dnf install -y nginx

# If using JVM backend, install Java 25
# sudo dnf install -y java-25-openjdk-headless
```

--------------------------------

### Install System Dependencies on Fedora

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Installs core dependencies, PostgreSQL 17 with PostGIS, and optionally Nginx. Configures the timezone for PostgreSQL.

```bash
# Install core dependencies (including timezone data)
sudo dnf install -y curl wget tar openssl ca-certificates tzdata

# Configure timezone (required for PostgreSQL)
sudo ln -sf /usr/share/zoneinfo/UTC /etc/localtime

# Install PostgreSQL 17 + PostGIS
sudo dnf install -y postgresql-server postgresql-contrib postgis

# Install Nginx (optional)
sudo dnf install -y nginx

# If using JVM backend, install Java 25
# sudo dnf install -y java-25-openjdk-headless
```

--------------------------------

### Start GeoPulse Backend Service

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

This command starts the GeoPulse backend service using systemctl.

```bash
sudo systemctl start geopulse-backend
```

--------------------------------

### Start GeoPulse Backup Service

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/system-administration/maintenance/backup-restore.md

After configuring the backup service in docker-compose.yml, use this command to start it in detached mode.

```bash
docker compose up -d geopulse-backup
```

--------------------------------

### Install GeoPulse in Production with Ingress

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Install the GeoPulse Helm chart with production-specific configurations, including ingress.

```bash
helm install geopulse ./helm/geopulse -f production-values.yaml
```

--------------------------------

### Install GeoPulse using Helm

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/kubernetes-helm.md

Installs the GeoPulse application using the Helm chart from the added repository.

```bash
helm install my-geopulse geopulse/geopulse
```

--------------------------------

### Install Native GeoPulse Backend (AMD64 Compatible)

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Installs the native AMD64 compatible GeoPulse backend binary. This command is for systems that require broader compatibility than the modern AMD64 version.

```bash
# Copy binary and set permissions
sudo cp geopulse-backend-native-amd64-compat-${VERSION} /opt/geopulse/backend/geopulse-backend
sudo chmod +x /opt/geopulse/backend/geopulse-backend
sudo chown geopulse:geopulse /opt/geopulse/backend/geopulse-backend
```

--------------------------------

### Install k6 on Linux

Source: https://github.com/tess1o/geopulse/blob/main/tests/performance/README.md

Installs k6 on Debian-based Linux distributions using apt. This involves adding the k6 GPG key and repository.

```bash
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update
sudo apt-get install k6
```

--------------------------------

### Kubernetes/Helm Configuration for Invitation Base URL

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/system-administration/configuration/admin-panel.md

Example of how to configure the base URL for invitation links in a Kubernetes environment using Helm.

```yaml
config:
  invitation:
    baseUrl: "https://geopulse.example.com"
```

--------------------------------

### Manual Helm Installation with Custom Values

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/kubernetes-helm.md

Installs GeoPulse using Helm directly, applying configurations from a custom values file.

```bash
helm install geopulse ./helm/geopulse -f my-values.yaml
```

--------------------------------

### Custom URL Examples for Default Home Page

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/user-guide/personalization/profile-settings.md

Examples of internal paths that can be used to set a custom default home page after login. These paths must be valid GeoPulse page paths.

```bash
/app/timeline?date=2024-01-01
```

```bash
/app/dashboard
```

```bash
/app/journey-insights?month=current
```

--------------------------------

### Example .env file for OIDC Configuration

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/system-administration/configuration/oidc-sso.md

A sample .env file demonstrating the required global OIDC enablement and callback URL settings.

```shell
# ⚠️ REQUIRED: Enable OIDC globally first
GEOPULSE_OIDC_ENABLED: "true"

```

--------------------------------

### Quick Start: Deploy GeoPulse without MQTT

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/docker-compose.md

Use this option for a standard GeoPulse installation that does not require MQTT integration. Ensure Docker and Docker Compose are installed.

```bash
# 1) Download .env
curl -L -o .env https://raw.githubusercontent.com/tess1o/GeoPulse/main/.env.example

# 2) Configure .env (optional for local evaluation, required for production/security)
# nano .env

# 3) Download docker-compose
curl -L -o docker-compose.yml https://raw.githubusercontent.com/tess1o/GeoPulse/main/docker-compose.yml

# 4) Start
docker compose up -d
```

--------------------------------

### Verify GeoPulse Helm Installation

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Check the status of GeoPulse pods after installation using `kubectl get pods`. Run Helm tests to ensure the deployment is functioning correctly.

```bash
kubectl get pods -l app.kubernetes.io/instance=geopulse
```

```bash
helm test geopulse
```

--------------------------------

### Override Helm Chart Values

Source: https://github.com/tess1o/geopulse/blob/main/helm/examples/README.md

Override specific Helm chart values during installation, for example, to increase PostgreSQL storage size or backend replica count.

```bash
helm install geopulse ./helm/geopulse \
  -f helm/examples/mqtt-enabled.yaml \
  --set postgres.persistence.size=200Gi \
  --set backend.replicaCount=5
```

--------------------------------

### Verify Upgrade and Cleanup

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Checks backend logs for successful startup after an upgrade and verifies the frontend version. Cleans up the temporary upgrade directory.

```bash
# Check logs for successful startup
sudo journalctl -u geopulse-backend -n 50

# Access frontend in browser
# Version should be visible in UI (bottom right corner or About page)

# Cleanup
rm -rf /tmp/geopulse-upgrade
```

--------------------------------

### Retroactive Stay Timestamp Example (Old vs. New Behavior)

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/user-guide/timeline/trip_detection.md

Illustrates the problem with the old behavior where trip durations were inflated by the detection delay. It contrasts this with the new behavior where the stay start time is retroactively set to the first stopped point, ensuring accurate trip durations.

```text
User arrives at 10:00 AM (GPS every 15 min)
Points: 10:00, 10:15, 10:30 (3rd point triggers detection)

OLD BEHAVIOR (incorrect):
  - Trip ends: 10:30 (detection time)
  - Stay starts: 10:30 (detection time)
  - Result: Trip appears 30 minutes longer than reality

NEW BEHAVIOR (correct):
  - Trip ends: 10:00 (first stopped point)
  - Stay starts: 10:00 (first stopped point)
  - Result: Accurate trip duration
```

--------------------------------

### Configure Immich Integration

Source: https://context7.com/tess1o/geopulse/llms.txt

Set up the integration with your Immich self-hosted photo server. This involves enabling the integration in your user profile and providing the Immich server URL and API key with necessary permissions.

```bash
# Configure Immich integration in user profile
# The API key needs permissions: asset.read, asset.download, asset.view

# Example Immich configuration (set via UI at /app/profile):
# - Enable Immich Integration: true
# - Immich Server URL: https://immich.yourdomain.com
# - API Key: your-immich-api-key

# GeoPulse fetches photos from Immich that match the timeline timeframe
# Photos appear as clickable icons on the map, showing:
# - Thumbnail previews
# - Original photo download option
# - Location-based photo clustering
```

--------------------------------

### Quick Installation with Docker Compose

Source: https://github.com/tess1o/geopulse/blob/main/README.md

Use these commands to quickly set up GeoPulse locally. Ensure you review the .env file for security settings before production use.

```bash
mkdir geopulse && cd geopulse
curl -L -o .env https://raw.githubusercontent.com/tess1o/GeoPulse/main/.env.example
curl -L -o docker-compose.yml https://raw.githubusercontent.com/tess1o/GeoPulse/main/docker-compose.yml

docker compose up -d
```

--------------------------------

### Arrival Detection Example with Infrequent GPS

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/user-guide/timeline/trip_detection.md

Illustrates the impact of 'Minimum Stop Points for Arrival Detection' on delay with infrequent GPS updates. A lower point count reduces detection delay.

```text
GPS Frequency: Every 15 minutes
Arrival Time: 10:00 AM

With 3 points (default):
  10:00 - 1st stopped point
  10:15 - 2nd stopped point
  10:30 - 3rd stopped point → Arrival detected
  Result: 30-minute delay, trip duration inflated

With 2 points (configured):
  10:00 - 1st stopped point
  10:15 - 2nd stopped point → Arrival detected
  Result: 15-minute delay, more accurate timeline
```

--------------------------------

### Verify PostGIS Installation

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Run this command to check if the PostGIS extension is installed and accessible in your PostgreSQL database. It displays the installed PostGIS version.

```bash
sudo -u postgres psql -d geopulse -c "SELECT PostGIS_Version();"
```

--------------------------------

### Upgrade Native Backend

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Upgrades the native backend by copying the new binary, setting execute permissions, and changing ownership. Ensure the filename matches your architecture.

```bash
# For native backend
sudo cp geopulse-backend-native-arm64-${NEW_VERSION} /opt/geopulse/backend/geopulse-backend
sudo chmod +x /opt/geopulse/backend/geopulse-backend
sudo chown geopulse:geopulse /opt/geopulse/backend/geopulse-backend
```

--------------------------------

### Add Helm Repository and Install GeoPulse

Source: https://github.com/tess1o/geopulse/blob/main/helm/geopulse/README.md

Commands to add the GeoPulse Helm repository, update it, and install the chart. Includes an option to install with custom values from a file.

```bash
# Add the Helm repository
helm repo add geopulse https://tess1o.github.io/geopulse/charts
helm repo update

# Install GeoPulse
helm install geopulse geopulse/geopulse

# Or install with custom values
helm install geopulse geopulse/geopulse -f custom-values.yaml
```

--------------------------------

### Use Compatible Backend Image

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/docker-compose.md

Replace the default optimized backend image with a compatible variant if your CPU lacks required features. This ensures the backend container starts on older hardware.

```yaml
  geopulse-backend:
    # Comment out the default optimized image:
    # image: tess1o/geopulse-backend:${GEOPULSE_VERSION}-native
    # Use the compatible image instead:
    image: tess1o/geopulse-backend:${GEOPULSE_VERSION}-native-compat
```

--------------------------------

### Install GeoPulse with External PostgreSQL

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Install the GeoPulse Helm chart configured to use an external PostgreSQL database.

```bash
helm install geopulse ./helm/geopulse -f external-db-values.yaml
```

--------------------------------

### k6 Light Load Configuration

Source: https://github.com/tess1o/geopulse/blob/main/tests/performance/README.md

This JSON file defines the configuration for a light load test scenario in k6, specifying 5 Virtual Users (VUs) and a duration of 5 minutes.

```json
{
  "light-load.json": "5 VUs, 5 min"
}
```

--------------------------------

### Configure Google OIDC Provider

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/system-administration/configuration/oidc-sso.md

Example configuration for integrating Google as an OIDC provider. Ensure you replace placeholder values with your actual Google OAuth 2.0 credentials and discovery URL.

```bash
GEOPULSE_OIDC_PROVIDER_GOOGLE_ENABLED=true
GEOPULSE_OIDC_PROVIDER_GOOGLE_NAME=Google
GEOPULSE_OIDC_PROVIDER_GOOGLE_CLIENT_ID=your-google-client-id
GEOPULSE_OIDC_PROVIDER_GOOGLE_CLIENT_SECRET=your-google-client-secret
GEOPULSE_OIDC_PROVIDER_GOOGLE_DISCOVERY_URL=https://accounts.google.com/.well-known/openid-configuration
GEOPULSE_OIDC_PROVIDER_GOOGLE_ICON=pi pi-google
```

--------------------------------

### Patch Install Script for Kubeconfig Export

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/kubernetes-helm.md

Modifies the install script to automatically export the KUBECONFIG variable if it's not already set.

```bash
if [ -z "$KUBECONFIG" ]; then
    export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
fi
```

--------------------------------

### Configure Google and Keycloak Icons

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/system-administration/configuration/oidc-sso.md

Set PrimeIcons CSS classes for Google and Keycloak OIDC providers. Ensure PrimeIcons library is available.

```bash
GEOPULSE_OIDC_PROVIDER_GOOGLE_ICON=pi pi-google
GEOPULSE_OIDC_PROVIDER_KEYCLOAK_ICON=pi pi-key
```

--------------------------------

### Configure Auth0 OIDC Provider

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/system-administration/configuration/oidc-sso.md

Example configuration for integrating Auth0 as an OIDC provider. Replace placeholders with your Auth0 domain, client ID, and secret.

```bash
GEOPULSE_OIDC_PROVIDER_AUTH0_ENABLED=true
GEOPULSE_OIDC_PROVIDER_AUTH0_NAME=Auth0
GEOPULSE_OIDC_PROVIDER_AUTH0_CLIENT_ID=your-auth0-client-id
GEOPULSE_OIDC_PROVIDER_AUTH0_CLIENT_SECRET=your-auth0-client-secret
GEOPULSE_OIDC_PROVIDER_AUTH0_DISCOVERY_URL=https://your-domain.auth0.com/.well-known/openid-configuration
GEOPULSE_OIDC_PROVIDER_AUTH0_ICON=pi pi-shield
```

--------------------------------

### Install GeoPulse with Helm

Source: https://github.com/tess1o/geopulse/blob/main/README.md

Use these commands to add the GeoPulse Helm repository, update it, and install GeoPulse on a managed Kubernetes cluster.

```shell
helm repo add geopulse https://tess1o.github.io/geopulse/charts
helm repo update
helm install my-geopulse geopulse/geopulse
```

--------------------------------

### Minimal Helm Setup for Local Testing

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

A minimal `values.yaml` for local testing, disabling persistence for PostgreSQL and Keygen. Note that disabling Keygen persistence means keys are regenerated on startup, suitable only for single-replica development.

```yaml
# minimal-values.yaml
postgres:
  persistence:
    enabled: false

keygen:
  persistence:
    enabled: false
```

--------------------------------

### Example Timezones

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/user-guide/personalization/profile-settings.md

These are examples of valid timezone strings used for display preferences. Ensure your selected timezone is among the supported options.

```text
America/New_York - Eastern Time (GMT-5)
```

```text
Europe/London - British Time (GMT+0)
```

```text
Asia/Tokyo - Japan Standard Time (GMT+9)
```

```text
Australia/Sydney - Australian Eastern Time (GMT+10)
```

--------------------------------

### Verify Frontend Extraction (Ubuntu/Debian)

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Lists the contents of the frontend directory to confirm successful extraction.

```bash
ls -la /var/www/geopulse/
```

--------------------------------

### GeoJSON Feature Example

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/user-guide/interacting-with-data/import-export.md

This GeoJSON example demonstrates a Point feature with timestamp properties. GeoPulse supports Point and LineString features for import.

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-122.4194, 37.7749]
      },
      "properties": {
        "timestamp": "2024-01-15T10:30:00Z"
      }
    }
  ]
}
```

--------------------------------

### Configure PostgreSQL Database and User

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Creates a 'geopulse' user with a specified password, creates a 'geopulse' database owned by this user, enables PostGIS extensions, and grants necessary privileges.

```bash
sudo -u postgres psql << 'EOF'
-- Create user
CREATE USER geopulse WITH PASSWORD 'your_secure_password_here';

-- Create database
CREATE DATABASE geopulse OWNER geopulse;

-- Connect to geopulse database
\c geopulse

-- Enable PostGIS extensions (must be done as superuser)
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS postgis_topology;

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE geopulse TO geopulse;
GRANT ALL ON SCHEMA public TO geopulse;
GRANT ALL ON ALL TABLES IN SCHEMA public TO geopulse;
GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO geopulse;
EOF
```

--------------------------------

### Install JVM GeoPulse Backend

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Installs the JVM version of the GeoPulse backend by extracting the downloaded tarball to the specified directory. This is for environments where a JVM is available.

```bash
# Extract quarkus-app folder
sudo tar -xzf geopulse-backend-jvm-${VERSION}.tar.gz -C /opt/geopulse/backend
```

--------------------------------

### Install Sealed Secrets Controller

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Install the Sealed Secrets controller using the provided YAML manifest URL. This is a prerequisite for using sealed secrets.

```bash
kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml
```

--------------------------------

### Install GeoPulse with Minimal Configuration

Source: https://github.com/tess1o/geopulse/blob/main/helm/examples/README.md

Use this command for quick local testing. It deploys GeoPulse without persistent storage, resulting in fast startup but data loss on pod restarts.

```bash
helm install geopulse ./helm/geopulse -f helm/examples/minimal-testing.yaml
```

--------------------------------

### Install GeoPulse with sudo and explicit KUBECONFIG

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/kubernetes-helm.md

Installs GeoPulse using sudo, explicitly providing the KUBECONFIG path to ensure proper cluster access.

```bash
sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml ./helm/install.sh
```

--------------------------------

### Parking Lot to Building Trip Example

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/user-guide/timeline/trip_detection.md

Shows how a short walk from a parking lot to an office is merged into a single CAR trip because the walking contribution is less than 15% of the journey.

```text
08:30 - Park car
08:32 - Walk 200m to office entrance

Walking: 200m (2 min)
Driving: previous segment

Walking contribution < 15% of journey
→ Result: Merged into single CAR trip
  (The brief walk is absorbed, not shown separately)
```

--------------------------------

### Configure Google OIDC/SSO

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/helm-deployment.md

Enable OIDC and specifically configure Google as an authentication provider. Client ID and secret should be managed securely.

```yaml
config:
  oidc:
    enabled: true
    google:
      enabled: true
      clientId: "your-google-client-id.apps.googleusercontent.com"
      clientSecret: "your-google-client-secret"  # Stored in Kubernetes Secret
```

--------------------------------

### Start and Verify Backend Service

Source: https://github.com/tess1o/geopulse/blob/main/docs-website/docs/getting-started/deployment/manual-installation.md

Starts the geopulse-backend service, checks its status, and verifies the API health endpoint. This is done after upgrading the backend and frontend.

```bash
# Start backend
sudo systemctl start geopulse-backend

# Check status
sudo systemctl status geopulse-backend

# Verify health
curl http://localhost:8080/api/health
```