Codakey
Play
← Back to geopulse

How to Deploy & Use geopulse

GeoPulse Deployment and Usage Guide

1. Prerequisites

Runtime & Tools:

  • Docker and Docker Compose (recommended for easiest deployment)
  • Java 17+ (if building from source)
  • PostgreSQL 14+ with PostGIS extension (included in Docker setup)
  • Node.js 18+ (for frontend development only)

Optional for Production:

  • Reverse proxy (Nginx, Traefik, or Caddy) for HTTPS termination
  • Domain name with SSL certificates
  • MQTT broker (if using MQTT-based tracking apps like OwnTracks)

Accounts (Optional):

  • No external API keys required (privacy-first design)
  • Immich instance credentials (for photo integration)

System Resources:

  • Minimum RAM: 512MB (typical usage: 40-100MB)
  • Minimum CPU: 1-2 vCPU
  • Storage: Varies based on location data volume

2. Installation

Docker Compose (Recommended)

  1. Clone the repository:

    git clone https://github.com/tess1o/geopulse.git
cd geopulse

  2. Choose deployment scenario:

    • Local Development: Use docker-compose.local.yml
    • Production: Use docker-compose.yml with custom domain configuration

  3. For Local Deployment:

    docker-compose -f docker-compose.local.yml up -d

    Access at: http://localhost:5555

  4. For Production Deployment:

    # Copy and edit the production compose file
cp docker-compose.yml docker-compose.prod.yml
# Edit environment variables and volumes as needed
docker-compose -f docker-compose.prod.yml up -d

Kubernetes/Helm

  1. Add the Helm repository:

    helm repo add geopulse https://tess1o.github.io/geopulse/charts
helm repo update

  2. Install GeoPulse:

    helm install my-geopulse geopulse/geopulse

  3. Customize values:

    helm show values geopulse/geopulse > values.yaml
# Edit values.yaml with your configuration
helm install my-geopulse geopulse/geopulse -f values.yaml

From Source

  1. Backend (Java/Quarkus):

    cd backend
./mvnw clean package
# For native build (requires GraalVM):
./mvnw clean package -Pnative -Dquarkus.native.container-build=true

  2. Frontend:

    cd frontend
npm install
npm run build

3. Configuration

Environment Variables

Required:

# Database
POSTGRES_DB=geopulse
POSTGRES_USER=geopulse
POSTGRES_PASSWORD=your_secure_password
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# First admin user (email)
GEOPULSE_ADMIN_EMAIL=admin@example.com

# JWT Secret (generate with: openssl rand -base64 32)
QUARKUS_HTTP_AUTH_JWT_SIGNATURE_SECRET=your_jwt_secret_here

Optional:

# Immich Integration
IMMICH_INSTANCE_URL=https://your-immich.instance
IMMICH_API_KEY=your_immich_api_key

# MQTT Configuration (for OwnTracks, etc.)
MQTT_ENABLED=true
MQTT_HOST=your-mqtt-broker
MQTT_PORT=1883
MQTT_USERNAME=mqtt_user
MQTT_PASSWORD=mqtt_password

# Reverse Proxy Settings
QUARKUS_HTTP_PROXY_ENABLED=true
QUARKUS_HTTP_CORS_ORIGINS=https://your-domain.com

Configuration Files

Backend Configuration (application.yml):

quarkus:
  http:
    port: 8080
    cors:
      origins: "${CORS_ORIGINS:http://localhost:3000}"
  datasource:
    db-kind: postgresql
    jdbc:
      url: jdbc:postgresql://${POSTGRES_HOST:localhost}:${POSTGRES_PORT:5432}/${POSTGRES_DB:geopulse}"
  hibernate-orm:
    database:
      generation: update

Timeline Configuration (User-specific): Configured via Admin Panel → System Settings:

  • Trip detection sensitivity
  • Stay/trip classification thresholds
  • GPS validation settings (matches TravelClassification constants)

4. Build & Run

Development Mode

  1. Start dependencies:

    docker-compose -f docker-compose.dev.yml up postgres redis -d

  2. Run backend in dev mode:

    cd backend
./mvnw compile quarkus:dev

  3. Run frontend in dev mode:

    cd frontend
npm run dev

  4. Access development environment:

Production Build

Using Docker:

# Build all services
docker-compose build

# Or build specific service
docker build -t geopulse-backend:latest -f backend/src/main/docker/Dockerfile.jvm backend/

# Run with production compose
docker-compose -f docker-compose.yml up -d

Native Executable (Optimal Performance):

cd backend
./mvnw clean package -Pnative -Dquarkus.native.container-build=true
# Output: target/geopulse-runner (≈40MB, starts in milliseconds)

5. Deployment

Platform Recommendations

Self-Hosted (Recommended):

  • Docker on VPS: DigitalOcean, Linode, Hetzner
  • Home Server: Unraid, TrueNAS, Proxmox
  • NAS Devices: Synology Docker, QNAP Container Station

Cloud Platforms:

  • AWS: ECS/EKS with RDS/PostGIS
  • Google Cloud: GKE with Cloud SQL + PostGIS extension
  • Azure: AKS with Azure Database for PostgreSQL + PostGIS

Managed Services:

  • Railway.app: One-click deploy with PostgreSQL
  • Fly.io: Global deployment with persistent volumes
  • Render.com: Docker deployment with managed PostgreSQL

Production Deployment Checklist

  1. Database Setup:

    CREATE DATABASE geopulse;
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS postgis_topology;

  2. Reverse Proxy Configuration (Nginx example):

    server {
    listen 443 ssl http2;
    server_name geopulse.your-domain.com;
    
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    
    location / {
        proxy_pass http://localhost:5555;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

  3. Data Persistence:

    # In docker-compose.yml
volumes:
  postgres_data:
    driver: local
  geopulse_uploads:
    driver: local

  4. Backup Strategy:

    • Regular PostgreSQL dumps
    • Volume backups for uploaded data
    • GeoPulse native export format for migration

Initial Setup After Deployment

  1. Access the application:

  2. Create Admin Account:

    • Use the email set in GEOPULSE_ADMIN_EMAIL
    • Complete registration form
    • Verify email (if configured)

  3. Configure System Settings:

    • Navigate to Admin Panel
    • Set up Immich integration (optional)
    • Configure MQTT (if using tracking apps)
    • Adjust default timeline sensitivity

  4. Import Existing Data:

    • Use Import feature in web interface
    • Supported formats: Google Timeline JSON, GPX, GeoJSON, OwnTracks, CSV
    • For large imports, use streaming parser (handles GB files with constant memory)

  5. Set Up Tracking Apps:

    • Configure OwnTracks/Overland/GPSLogger to send data to your instance
    • HTTP endpoint: https://your-domain.com/api/gps/ingest
    • MQTT topic: geopulse/gps/+/+

6. Troubleshooting

Common Issues

1. Database Connection Issues:

# Check if PostGIS extension is enabled
docker exec geopulse-postgres psql -U geopulse -d geopulse -c "\dx"

# Verify connection from backend
docker exec geopulse-backend curl http://postgres:5432

2. High Memory Usage During Import:

  • GeoPulse uses streaming parsers (O(1) memory)
  • For Google Timeline imports: Uses StreamingGoogleTimelineParser
  • Check import job status in Admin Panel
  • Large imports processed in batches automatically

3. Trip Classification Inaccurate:

  • Adjust sensitivity in User Settings → Timeline Configuration
  • Classification uses bidirectional GPS validation:
    • Low speed trips (<20 km/h): Strict ratio validation
    • Medium speed (20-200 km/h): 50% tolerance
    • High speed (>200 km/h): Trusts GPS data
  • Check TripClassificationDetailsService for validation details

4. MQTT Integration Not Working:

# Test MQTT connection
docker exec geopulse-backend nc -zv mqtt-broker 1883

# Check MQTT logs
docker logs geopulse-backend | grep -i mqtt

5. Immich Photos Not Showing:

  • Verify Immich instance URL and API key in System Settings
  • Check CORS configuration on Immich side
  • Ensure photos have location data (GPS coordinates)

6. Performance Issues:

  • Enable native build for 10x faster startup and lower memory
  • Add database indexes for large datasets: 
    CREATE INDEX idx_gps_points_user_timestamp ON gps_points(user_id, timestamp);
CREATE INDEX idx_timeline_trips_user_dates ON timeline_trips(user_id, start_time, end_time);

7. Upgrade Issues:

  • Always backup database before upgrading
  • Check migration scripts in backend/src/main/resources/db/migration
  • For major version upgrades, review CHANGELOG.md

Logs and Diagnostics

View Logs:

# Backend logs
docker logs geopulse-backend -f

# Database logs
docker logs geopulse-postgres -f

# All services
docker-compose logs -f

Health Checks:

# Application health
curl http://localhost:5555/api/health

# Database health
curl http://localhost:5555/api/health/database

# Detailed metrics (if enabled)
curl http://localhost:5555/q/metrics

Debug Mode:

# Enable debug logging
export QUARKUS_LOG_LEVEL=DEBUG
# Or in application.yml
quarkus:
  log:
    level: DEBUG
    category:
      "org.github.tess1o.geopulse":
        level: DEBUG

Getting Help

Note: GeoPulse is licensed under BSL 1.1. For commercial SaaS use, contact the author for a commercial license.

← Project overviewView alternatives to geopulse →