Deploying Traccar

Introduction

Traccar is a powerful, open-source GPS tracking system that supports over 200 GPS protocols and device types. Whether you’re tracking a fleet of vehicles, monitoring valuable assets, or keeping tabs on personnel locations, Traccar provides a comprehensive solution with real-time tracking, historical playback, and detailed reporting.

Built with Java on the backend and a modern web interface, Traccar delivers enterprise-grade features without enterprise pricing. The system supports thousands of devices simultaneously and integrates with various notification services for alerts and geofencing.

Key highlights of Traccar:

• 200+ Protocol Support: Works with virtually any GPS tracker on the market
• Real-Time Tracking: Live position updates on an interactive map
• Historical Playback: Review past routes and stop locations
• Geofencing: Define zones and receive alerts on entry/exit
• Alert System: Speed alerts, battery warnings, and custom notifications
• Detailed Reports: Trips, stops, fuel consumption, and more
• Mobile Apps: Native apps for iOS and Android
• Multi-User Support: User groups with device sharing and permissions
• REST API: Full API for integrations and custom applications
• 100% Open Source: Licensed under Apache 2.0

This guide walks through deploying Traccar on Klutch.sh using Docker, connecting GPS devices, and configuring tracking features.

Why Deploy Traccar on Klutch.sh

Deploying Traccar on Klutch.sh provides several advantages for GPS tracking:

Always-On Availability: GPS devices report continuously; your tracking server needs to be ready 24/7.

HTTPS by Default: Secure access to your tracking dashboard with automatic SSL certificates.

Reliable Connectivity: Stable network infrastructure for receiving device updates.

Persistent Storage: Location history and device data persist safely across restarts.

GitHub Integration: Manage configuration through version control with automatic redeployments.

Scalable Resources: Start with a few devices and scale up as your fleet grows.

Prerequisites

Before deploying Traccar on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• GPS tracking devices to connect
• (Optional) A custom domain for your Traccar instance

Understanding Traccar Architecture

Traccar consists of several components:

Protocol Decoders: Parse data from 200+ GPS tracker protocols on various ports.

Core Engine: Java-based server handling device management, location processing, and event generation.

Web Interface: Modern React-based dashboard for maps and management.

Database: Stores devices, positions, events, and configuration (H2 embedded or external MySQL/PostgreSQL).

REST API: Powers the web interface and enables custom integrations.

Preparing Your Repository

Create a GitHub repository with your Traccar configuration.

Repository Structure

traccar-deploy/
├── Dockerfile
├── traccar.xml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM traccar/traccar:latest

# Copy custom configuration
COPY traccar.xml /opt/traccar/conf/traccar.xml

# Create data directories
RUN mkdir -p /opt/traccar/data /opt/traccar/logs

# Expose ports
# Web interface
EXPOSE 8082
# Common GPS protocol ports
EXPOSE 5000-5150

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:8082/ || exit 1

Creating the Configuration File

Create a traccar.xml file:

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE properties SYSTEM 'http://java.sun.com/dtd/properties.dtd'>

<properties>

    <!-- Database Configuration -->
    <!-- Using H2 embedded database -->
    <entry key='database.driver'>org.h2.Driver</entry>
    <entry key='database.url'>jdbc:h2:/opt/traccar/data/database</entry>
    <entry key='database.user'>sa</entry>
    <entry key='database.password'></entry>

    <!-- Web Interface -->
    <entry key='web.port'>8082</entry>
    <entry key='web.path'>./web</entry>

    <!-- Geocoder for address lookup -->
    <entry key='geocoder.enable'>true</entry>
    <entry key='geocoder.type'>nominatim</entry>
    <entry key='geocoder.url'>https://nominatim.openstreetmap.org/reverse</entry>

    <!-- Enable common protocols -->
    <entry key='gps103.port'>5001</entry>
    <entry key='tk103.port'>5002</entry>
    <entry key='gl100.port'>5003</entry>
    <entry key='gl200.port'>5004</entry>
    <entry key='t55.port'>5005</entry>
    <entry key='xexun.port'>5006</entry>
    <entry key='totem.port'>5007</entry>
    <entry key='enfora.port'>5008</entry>
    <entry key='meiligao.port'>5009</entry>
    <entry key='gt02.port'>5010</entry>
    <entry key='gt06.port'>5023</entry>
    <entry key='teltonika.port'>5027</entry>
    <entry key='osmand.port'>5055</entry>
    <entry key='h02.port'>5013</entry>

    <!-- Logging -->
    <entry key='logger.enable'>true</entry>
    <entry key='logger.level'>info</entry>
    <entry key='logger.file'>/opt/traccar/logs/tracker-server.log</entry>

    <!-- Server settings -->
    <entry key='server.timeout'>180</entry>

</properties>

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Deploying Traccar on Klutch.sh

Follow these steps to deploy your Traccar instance:

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile traccar.xml .dockerignore README.md
git commit -m "Initial Traccar configuration"
git remote add origin https://github.com/yourusername/traccar-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Name it something like “gps-tracking” or “traccar”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Traccar repository.

Configure HTTP Traffic

For the web interface:

• Select HTTP as the traffic type
• Set the internal port to 8082

Configure Additional Ports

GPS devices connect on various TCP/UDP ports. Configure the protocols you need (commonly 5000-5100 range).

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
/opt/traccar/data	20 GB	Database and position history
/opt/traccar/logs	5 GB	Server logs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Build your Docker image
• Attach persistent volumes
• Start the Traccar server
• Provision an HTTPS certificate

Access Traccar

Navigate to https://your-app-name.klutch.sh to access the web interface. Default credentials are admin/admin.

Initial Configuration

Changing Admin Password

Immediately after first login:

1. Click on your username
2. Go to Settings
3. Change the default password

Adding Devices

Register your GPS trackers:

1. Navigate to Devices
2. Click Add
3. Enter device name and unique identifier
4. The identifier is usually the IMEI number

Device Configuration

Each device needs server information:

Setting	Value
Server Address	your-app-name.klutch.sh
Server Port	Protocol-specific (e.g., 5023 for GT06)
IMEI	Device’s unique identifier

Supported Protocols

Popular Protocols and Ports

Protocol	Port	Common Devices
GT06	5023	Concox, Coban
Teltonika	5027	FMB series
H02	5013	Sinotrack
TK103	5002	Various Chinese trackers
OsmAnd	5055	OsmAnd mobile app
Totem	5007	Totem trackers

OsmAnd Protocol

For smartphone tracking, use the OsmAnd protocol:

1. Install OsmAnd app on your phone
2. Configure tracking plugin with your server URL
3. Format: https://your-server:5055?id=YOUR_DEVICE_ID&lat={0}&lon={1}&timestamp={2}&speed={5}

Geofencing

Creating Geofences

Define geographic boundaries:

1. Navigate to Geofences
2. Click Add
3. Draw polygon or circle on the map
4. Name the geofence

Geofence Alerts

Configure notifications:

1. Go to Notifications
2. Create notification for geofence events
3. Select entry/exit triggers
4. Choose notification method (email, web, etc.)

Reporting

Available Reports

Traccar provides comprehensive reports:

Report	Description
Route	Path traveled during time period
Events	All events for selected devices
Trips	Individual trips with distance and duration
Stops	Locations where device was stationary
Summary	Overview with totals and averages
Chart	Speed and altitude over time

Generating Reports

1. Navigate to Reports
2. Select report type
3. Choose devices and date range
4. Click Show or Export

Notifications

Notification Types

Configure alerts for various events:

• Device online/offline
• Geofence entry/exit
• Speed exceeded
• Low battery
• Ignition on/off
• SOS button pressed

Email Configuration

Enable email notifications:

<entry key='mail.smtp.host'>smtp.example.com</entry>
<entry key='mail.smtp.port'>587</entry>
<entry key='mail.smtp.starttls.enable'>true</entry>
<entry key='mail.smtp.from'>traccar@example.com</entry>
<entry key='mail.smtp.auth'>true</entry>
<entry key='mail.smtp.username'>your-username</entry>
<entry key='mail.smtp.password'>your-password</entry>

API Integration

REST API

Traccar provides a comprehensive REST API:

# Get all devices
curl -u admin:password https://your-traccar.klutch.sh/api/devices

# Get positions
curl -u admin:password https://your-traccar.klutch.sh/api/positions

WebSocket for Real-Time Updates

Connect to real-time position updates:

const socket = new WebSocket('wss://your-traccar.klutch.sh/api/socket');
socket.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Position update:', data);
};

External Database

Using PostgreSQL

For larger deployments, use an external database:

<entry key='database.driver'>org.postgresql.Driver</entry>
<entry key='database.url'>jdbc:postgresql://host:5432/traccar</entry>
<entry key='database.user'>traccar</entry>
<entry key='database.password'>your-password</entry>

Using MySQL

MySQL configuration:

<entry key='database.driver'>com.mysql.cj.jdbc.Driver</entry>
<entry key='database.url'>jdbc:mysql://host:3306/traccar?useSSL=false</entry>
<entry key='database.user'>traccar</entry>
<entry key='database.password'>your-password</entry>

Performance Tuning

Resource Recommendations

Devices	RAM	CPU
1-50	1 GB	1 vCPU
50-200	2 GB	2 vCPU
200-1000	4 GB	4 vCPU

Database Optimization

For many devices:

• Use external PostgreSQL or MySQL
• Enable database connection pooling
• Archive old positions periodically

Troubleshooting Common Issues

Device Not Connecting

Symptoms: Device shows offline.

Solutions:

• Verify server address and port in device
• Check protocol port is exposed correctly
• Confirm device identifier matches Traccar
• Test with simpler protocol (OsmAnd)

No Positions Appearing

Symptoms: Device online but no map updates.

Solutions:

• Check device has GPS fix
• Verify protocol matches device type
• Review server logs for parse errors

Web Interface Slow

Symptoms: Dashboard loads slowly.

Solutions:

• Limit date ranges in map view
• Archive old position data
• Increase memory allocation

Additional Resources

• Official Traccar Website
• Traccar Documentation
• Supported Protocols
• Traccar GitHub Repository
• API Reference
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Traccar on Klutch.sh provides a powerful, self-hosted GPS tracking solution supporting virtually any GPS device. Whether you’re managing a small fleet of vehicles or tracking valuable assets, Traccar delivers enterprise features with open-source flexibility.

The combination of real-time tracking, comprehensive reporting, and geofencing capabilities makes Traccar suitable for diverse tracking needs. Deployed on Klutch.sh with persistent storage, your tracking data remains secure and accessible while the reliable infrastructure ensures devices can always report their positions.

With support for over 200 protocols, mobile apps for iOS and Android, and a full REST API, Traccar provides the foundation for sophisticated tracking solutions while keeping your location data under your control.