Self-Hosting Traccar with Docker Compose

What Is Traccar?

Traccar is an open-source GPS tracking platform that supports over 200 GPS device protocols. It provides real-time tracking, historical playback, geofencing, alerts, and reporting through a web interface and mobile apps. Self-hosting means your location data — one of the most sensitive data types — stays on your own server instead of some third-party cloud.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 2 GB of RAM (minimum)
• 10 GB of free disk space
• Open ports for device communication (TCP/UDP 5000-5500)
• A domain name (optional, for web UI access)

Docker Compose Configuration

This setup uses MySQL as the database backend, which is recommended for production deployments. The built-in H2 database works for testing but isn’t suitable for long-term use.

Create a docker-compose.yml file:

services:
  traccar:
    image: traccar/traccar:6.12.2
    container_name: traccar
    restart: unless-stopped
    ports:
      - "8082:8082"           # Web UI and REST API
      - "5000-5150:5000-5150" # GPS device protocols (TCP)
      - "5000-5150:5000-5150/udp" # GPS device protocols (UDP)
    environment:
      CONFIG_USE_ENVIRONMENT_VARIABLES: "true"
      DATABASE_DRIVER: com.mysql.cj.jdbc.Driver
      DATABASE_URL: "jdbc:mysql://traccar-db:3306/traccar?zeroDateTimeBehavior=round&serverTimezone=UTC&allowPublicKeyRetrieval=true&useSSL=false&allowMultiQueries=true&autoReconnect=true&useUnicode=yes&characterEncoding=UTF-8&sessionVariables=sql_mode=''"
      DATABASE_USER: traccar
      DATABASE_PASSWORD: change-this-password    # CHANGE THIS
    volumes:
      - traccar-logs:/opt/traccar/logs
    depends_on:
      - traccar-db
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:8082/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    networks:
      - traccar

  traccar-db:
    image: mysql:8.4
    container_name: traccar-db
    restart: unless-stopped
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
      MYSQL_DATABASE: traccar
      MYSQL_USER: traccar
      MYSQL_PASSWORD: change-this-password       # Must match DATABASE_PASSWORD above
    volumes:
      - traccar-db:/var/lib/mysql
    networks:
      - traccar

volumes:
  traccar-logs:
  traccar-db:

networks:
  traccar:
    driver: bridge

Start the stack:

docker compose up -d

Wait 30-60 seconds for MySQL initialization and Traccar startup. Access the web UI at http://your-server-ip:8082.

Initial Setup

1. Open http://your-server-ip:8082 in a browser
2. Register the first admin account (the first registration becomes the administrator)
3. Go to Settings → Server to configure global preferences

Default admin registration is open — create your account immediately after deployment, then disable registration in Settings → Server → Registration.

Device Setup

Traccar supports 200+ GPS device protocols. Each protocol listens on a specific port within the 5000-5150 range. Common devices and their ports:

Device/Protocol	Port	Notes
OsmAnd (Android/iOS app)	5055	Free app, easiest to start with
Traccar Client (official app)	5055	Available on Android and iOS
GPS103/TK103 devices	5001	Common cheap GPS trackers
GT06 protocol	5023	Popular vehicle tracker protocol
H02 protocol	5013	Sinotrack and similar devices
Teltonika devices	5027	Professional fleet trackers

Quickest way to test: Install the OsmAnd or Traccar Client app on your phone. In the app, set the server URL to http://your-server-ip:5055. Set a unique Device ID and add that same ID in the Traccar web UI under Devices.

Configuration

Traccar uses environment variables (with CONFIG_USE_ENVIRONMENT_VARIABLES=true) that map to its XML configuration. Variable names follow the pattern: XML path database.driver becomes DATABASE_DRIVER.

Key configuration options:

Variable	Purpose	Example
WEB_PORT	Web UI port	8082 (default)
GEOCODER_TYPE	Reverse geocoding provider	nominatim (free, OSM-based)
GEOCODER_URL	Geocoder API URL	https://nominatim.openstreetmap.org/reverse
MAIL_SMTP_HOST	SMTP server for email alerts	smtp.example.com
MAIL_SMTP_PORT	SMTP port	587
MAIL_SMTP_FROM_NAME	Email sender name	Traccar

For advanced configuration, mount a custom traccar.xml:

volumes:
  - ./traccar.xml:/opt/traccar/conf/traccar.xml:ro

Geofencing and Alerts

Traccar supports powerful geofencing — draw zones on the map and trigger alerts when devices enter or leave.

1. In the web UI, click Geofences in the left panel
2. Click the + button and draw a polygon or circle on the map
3. Name the geofence and save
4. Go to Settings → Notifications to configure alert rules:
   • Geofence enter/exit — device enters or leaves a zone
   • Speed limit — device exceeds a set speed
   • Device online/offline — connection status changes
   • Ignition on/off — vehicle ignition state (if device supports it)

Alerts can be sent via email, web push, or SMS (with a gateway).

Reverse Proxy

Point your reverse proxy to http://traccar:8082 for the web UI. Device communication ports (5000-5150) should NOT go through the reverse proxy — GPS devices connect directly to those ports using raw TCP/UDP protocols.

For a dedicated reverse proxy setup, see Reverse Proxy Guide.

Backup

Back up the MySQL database:

docker exec traccar-db mysqldump -u traccar -p traccar > traccar-backup.sql

The logs volume is optional to back up (useful for debugging but not essential for disaster recovery).

For general backup strategies, see Backup Strategy.

Troubleshooting

Device Shows as “Unknown” or Not Connecting

Symptom: You added a device ID in the web UI, but the device shows offline.

Fix: Verify the device’s configured server address and port match your Traccar instance. Check that the correct ports are open in your firewall (both TCP and UDP). Use docker logs traccar to see if connection attempts appear in the logs. The Device ID in the web UI must exactly match what the GPS device sends.

”Too Many Connections” Database Error

Symptom: Traccar logs show MySQL connection pool exhaustion.

Fix: MySQL 8.4 defaults to 151 max connections. For large deployments (500+ devices), increase it:

  traccar-db:
    command: --max-connections=500

Web UI Loads But Map Tiles Missing

Symptom: The interface works but the map shows gray/missing tiles.

Fix: Traccar uses OpenStreetMap tiles by default. If your server has no outbound internet access, map tiles won’t load. For air-gapped setups, configure a local tile server.

Resource Requirements

• RAM: 1-2 GB for small deployments (10-50 devices), 4+ GB for 500+ devices
• CPU: 1-2 cores for small deployments, CPU is rarely the bottleneck
• Disk: 10-50 GB depending on data retention and device count

Traccar is Java-based (JRE 21), so RAM is the primary constraint. The reporting interval of your devices matters more than the device count — 50 devices reporting every 10 seconds generates more load than 5,000 devices reporting every 6 hours.

Verdict

Traccar is the definitive self-hosted GPS tracking platform. The 200+ protocol support means it works with virtually any GPS hardware, from $15 AliExpress trackers to professional Teltonika fleet devices. The web UI is functional (not beautiful), the mobile apps work well, and the geofencing and alert system is genuinely useful.

For personal device tracking (family, pets, vehicles), OwnTracks is simpler but limited to MQTT/HTTP — no hardware GPS tracker support. Traccar is the answer when you need to track physical GPS devices or build a fleet management system.

Frequently Asked Questions

Is Traccar free for commercial use?

Yes. Traccar is open-source under the Apache License 2.0, which allows free commercial use including fleet management for businesses. There is no per-device licensing fee. The project also offers a commercial cloud version at traccar.org, but self-hosting is fully free regardless of device count.

How many devices can Traccar handle?

Traccar handles thousands of devices on modest hardware. A small deployment (10-50 devices) runs fine on 2 GB RAM and 1-2 CPU cores. For 500+ devices, plan for 4+ GB RAM and increase MySQL’s max connections. The reporting interval matters more than device count — 50 devices reporting every 10 seconds generates more load than 5,000 devices reporting every 6 hours.

Can I use my phone as a GPS tracker?

Yes. Install the free OsmAnd app or the official Traccar Client app on your Android or iOS phone. Set the server URL to your Traccar instance on port 5055, configure a unique Device ID, and add that ID in Traccar’s web UI. This is the quickest way to test your setup.

Does Traccar support geofencing?

Yes. Draw polygon or circle zones on the map in the web UI under Geofences. Configure alerts for when devices enter or leave zones, exceed speed limits, or go online/offline. Alerts can be delivered via email, web push notifications, or SMS through a gateway.

Can I use the built-in H2 database instead of MySQL?

Traccar includes an embedded H2 database that works without any external database service. It’s fine for testing and small personal deployments. For production use with more than a few devices or long data retention, MySQL or PostgreSQL is strongly recommended — H2 doesn’t handle concurrent access or large datasets as well.

Do I need to open many ports for GPS devices?

GPS device protocols use ports in the 5000-5150 range. You only need to open the specific port for your device’s protocol — for example, port 5055 for OsmAnd/Traccar Client, port 5001 for TK103 devices. The Docker Compose config maps the entire range for convenience, but your firewall only needs the ports you actually use.

Related

• Traccar vs OwnTracks: Which GPS Tracker?
• How to Self-Host OwnTracks
• Best Self-Hosted Maps & GPS Tracking Tools
• Docker Compose Basics
• Reverse Proxy Guide
• Backup Strategy
• Best Self-Hosted Home Automation Tools
• Getting Started with Self-Hosting