Self-Host Traccar and Access It with Localtonet

Understand the Traccar deployment architecture

Traccar is a free, open-source GPS tracking platform for vehicles, assets, people, and other connected devices. Its Java-based server supports more than 200 GPS protocols and more than 2,000 tracker models. Available application features include real-time tracking, account and device management, geofences, reports, alarms, notifications, and driver-behavior monitoring.

The Traccar project publishes a Docker Compose quick start that combines the application with MySQL. Docker Compose creates the services, network, published ports, environment settings, and persistent storage described by the Compose definition. Traccar's browser application and REST API are available through the web service on port 8082.

This tutorial selects Traccar v6.16.0 as its review baseline instead of treating the mutable master branch as a stable release. The release is associated with source commit cfab560. Pinning the source revision lets you retain the exact Compose definition that was reviewed. It does not automatically pin every container image if that definition itself refers to a moving image tag such as latest. Image references must therefore be checked separately before startup.

Dashboard traffic is not tracker ingestion traffic

Port 8082 is the verified web endpoint for the dashboard and Traccar web service. It is not a universal ingestion port for all GPS hardware. Physical trackers generally connect to protocol-specific TCP or UDP listeners selected according to their model, firmware, and configured Traccar protocol.

The reviewed Traccar Compose pattern may publish a range of TCP and UDP ports so supported tracker protocols can reach their listeners. That broad publication is different from exposing the dashboard. Administrators should compare the rendered Compose configuration with the protocols actually required and reduce unnecessary host exposure where practical. Do not select a tracker port by guessing from a model name or by substituting port 8082.

Prepare the Docker host

This tutorial begins with an already functioning Docker host. Installing an operating system, configuring storage hardware, and designing production host security are outside its scope. The host must have Docker Engine and the modern Docker Compose plugin installed and operational before you continue.

Docker installation procedures vary by Linux distribution, Windows edition, macOS version, and whether Docker Desktop or Docker Engine is used. Follow the official Docker Engine installation instructions and Docker Compose installation instructions for your platform rather than applying an unverified cross-platform command.

Confirm these requirements before downloading anything:

• Docker is running and your account is authorized to manage containers.
• The modern docker compose command is available.
• curl is installed, or you have another controlled method for downloading a file.
• The host can reach the container registry and Traccar repository over the internet.
• Host TCP port 8082 is not already occupied.
• You have a dedicated deployment directory with restricted access.
• You have enough storage for MySQL, application logs, backups, and retained location history.
• You have selected a separate location for backups, ideally outside the active Docker data path.

Check Docker, Compose, and curl

docker --version
docker compose version
docker info
curl --version

The first two commands confirm the client tools. docker info also tests communication with the Docker daemon. Resolve daemon permission or connectivity errors before proceeding. Membership in a Docker management group can provide substantial host-level control, so grant that access only to trusted administrators.

Create and protect a deployment directory

Use a dedicated directory for the retained Compose file, review notes, backup scripts, and any deployment-specific configuration. Run all later Compose commands from this directory unless you explicitly supply a file path.

mkdir traccar-compose
cd traccar-compose

Resource requirements depend on the number of trackers, reporting frequency, database size, retained history, concurrent dashboard users, and enabled features. The reviewed project evidence does not establish a universal CPU, memory, or disk minimum, so monitor actual usage and maintain enough free space for database growth and backups.

Download, inspect, validate, and start Traccar

Traccar's repository shows a convenient command that downloads the Compose file from its master branch. That branch can change after publication, so it is not a reproducible release reference. For this tutorial, download the definition from the release-associated commit cfab560 and retain that exact file with your deployment records.

curl --fail --location \
  --output compose.yaml \
  https://raw.githubusercontent.com/traccar/traccar/cfab560/docker/compose/traccar-mysql.yaml

sha256sum compose.yaml
cat compose.yaml

docker compose config

docker compose up -d

What to verify in the reviewed Compose definition

The Traccar MySQL deployment has two functional services: the Traccar application and a MySQL database. The application receives its database connection settings through the Compose configuration and reaches MySQL over the Compose network. The database uses persistent storage so recreating a container does not intentionally erase all records. Traccar also retains application logs through the configured storage mapping.

The definition publishes host port 8082 for the Traccar web service. It can also publish TCP and UDP ranges associated with tracker protocol listeners. Review those additional mappings instead of assuming they are required for your fleet. Database port 3306 does not need to be published publicly for Traccar to communicate with MySQL inside the Compose project.

The upstream quick-start pattern has historically used example database values suitable for demonstrating connectivity, not organization-specific secret management. The exact values in your retained file are the values that matter. Replace predictable or shared passwords before first startup. Prefer a protected environment file or a secret-management mechanism appropriate to your platform, and ensure rendered output, shell history, screenshots, and support bundles do not disclose those values.

Complete the Traccar 6.16.0 first-run account flow

Wait for MySQL initialization and Traccar startup before opening the dashboard. A newly created database has no existing organization accounts. In the selected Traccar 6.16.0 workflow, the first account registered against a fresh installation receives administrative access. Complete this step locally before making the login surface public.

If the installation uses a restored or previously initialized database, it is not a first-run deployment. The dashboard will use the accounts and permissions already stored in that database. Do not expect first-account registration to reset an existing administrator or replace forgotten credentials.

Registration behavior and administrative controls can change between Traccar releases. If you select a version other than 6.16.0, verify its first-run behavior before deployment. Never apply default credentials copied from an old tutorial to an internet-reachable installation.

Verify Traccar locally before remote access

Check container state

docker compose ps
docker compose images

Confirm that both application and database services remain running. Record the resolved image references shown by Docker. A container that repeatedly restarts, exits, or remains unhealthy indicates an application, database, storage, resource, or configuration problem.

Inspect recent logs

docker compose logs --tail=100

Look for database initialization progress, connection failures, permission errors, invalid settings, port-binding failures, and repeated restart messages. Temporary retries can occur while MySQL initializes. Persistent errors after initialization deserve investigation.

Follow new messages while reproducing a problem with:

docker compose logs -f

Review output before sharing it. Logs can contain hostnames, device identifiers, account details, coordinates, network addresses, and other sensitive operational information.

Test the local dashboard and authentication

http://localhost:8082

If the browser runs on another trusted LAN device, use the Docker host's reachable LAN address and port 8082, provided the host firewall and port publication permit it. A successful loopback test does not prove that another machine can reach the service.

• Confirm the expected Traccar page loads without a connection error.
• Sign in with the intentionally created account.
• Sign out and verify that protected content is no longer accessible.
• Test a restricted user and confirm it cannot view unauthorized devices or administrative settings.
• Refresh the browser and confirm the session behaves as expected.
• Check that both containers remain stable during use.
• Review available application or server activity records for unexpected authentication behavior.

Test device ingestion separately

If a physical or software tracker is part of the deployment, configure it with the verified Traccar protocol, device identifier, destination, and listener port. Confirm that a new position reaches the intended device record and that its timestamp and location are plausible. Dashboard availability alone does not verify tracker ingestion.

Back up, restore, update, and roll back the deployment

Keep routine Compose commands in the directory containing the reviewed compose.yaml. Preserve that file, its checksum, any protected environment file, the resolved image references, and a record of intentional modifications.

Create a database-aware backup

A copy of compose.yaml is not a backup of Traccar records. The MySQL database contains the important operational state. The following pattern runs mysqldump inside the database service and uses the database environment already provided to that container. Confirm the database service name in your rendered configuration before using it.

mkdir -p backups
docker compose exec -T mysql sh -c \
  'exec mysqldump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' \
  > backups/traccar.sql

Restrict access to the resulting SQL file because it can contain account information, device identifiers, coordinates, event history, and other sensitive data. Also preserve the reviewed Compose file, checksum, protected environment file, and any retained Traccar configuration or log data required by your recovery plan.

The command assumes the reviewed database service is named mysql and exposes the listed environment variables inside the container. If your rendered configuration differs, adapt the command to that exact deployment instead of copying credentials into the shell command.

Test restoration in an isolated environment

A backup is not proven until it has been restored and checked. Restoration replaces or merges database state depending on the target database, so do not test it against the active production database.

1. Create an isolated test deployment using the same reviewed Traccar and MySQL versions.
2. Stop the test Traccar application so it does not write while the database is being restored.
3. Confirm the test database is empty or intentionally prepared for restoration.
4. Import the dump through the test MySQL service.
5. Start Traccar and verify accounts, devices, recent positions, permissions, and reports.
6. Destroy or securely retain the test copy according to your location-data policy.

cat backups/traccar.sql | docker compose exec -T mysql sh -c \
  'exec mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"'

Exact recovery steps can differ when image versions, database schema, service names, storage drivers, or credentials differ. Preserve a deployment-specific runbook after completing a successful test restoration. Do not rely solely on copying live MySQL volume files while the database is running.

Update through a controlled change

1. Record the current Compose checksum and resolved image references.
2. Create and verify a fresh database backup.
3. Retain the currently deployed Compose file and any local modifications.
4. Read the target Traccar release information and database compatibility notes.
5. Download the new definition from a fixed release tag or commit.
6. Compare it with the deployed definition and inspect changed images, ports, volumes, variables, and secrets.
7. Run docker compose config before startup.
8. Schedule maintenance and stop public access if appropriate.
9. Deploy the tested update.
10. Verify login, user restrictions, reports, device ingestion, logs, and the Localtonet path.

Plan rollback before deployment

A rollback requires more than restoring an old YAML file. A newer application can introduce database changes that an older application does not understand. Preserve the pre-update database backup, old Compose definition, configuration, and image identifiers. If rollback is required, stop the updated stack, restore the compatible database state in accordance with the tested recovery runbook, restore the prior deployment definition, and repeat both dashboard and ingestion tests.

Provide remote dashboard access with Localtonet

Once Traccar works locally, a Localtonet HTTP tunnel can provide a public HTTPS address for the dashboard. Our client runs on a device that can reach Traccar and establishes an outbound connection to a Localtonet relay server. The tunnel does not require inbound router port forwarding, VPN setup, firewall changes, or a public IP address.

Creating a tunnel configuration does not make it active. The selected client must be connected, and you must press Start. The public endpoint remains available only while that client is connected and the tunnel is running.

See the Localtonet HTTP tunnel documentation for the current dashboard workflow. Exact relay choices, plan availability, interface details, and custom-domain requirements should be verified in the current product.

Select the target from the client's point of view

Protect location data, accounts, and public access

Traccar can hold precise location history, device identifiers, geofences, account data, movement patterns, operational schedules, and driver information. This information can create personal safety, privacy, employment, and business risks if exposed. Collect only what your use case requires, restrict retention where appropriate, and follow applicable privacy and tracking laws.

Review account permissions regularly

Do not use one administrator account for every user. Remove obsolete accounts promptly, review device assignments, and confirm that restricted users cannot see unrelated trackers. Recheck permissions after imports, upgrades, organizational changes, or administrator actions.

Monitor authentication and service activity where supported

Review the activity and logging capabilities available in the selected Traccar version, along with container and host logs. Look for repeated login failures, unexpected successful sessions, new accounts, permission changes, unexplained exports, and access at unusual times. Do not claim an audit event exists unless the installed version actually records it.

Protect the logs themselves. They may reveal device identifiers, account names, IP addresses, coordinates, or internal network details. Limit access and avoid sending unredacted logs through public support channels.

Review whether public access is still justified

A public HTTPS address makes the Traccar login surface reachable from the internet. Periodically confirm that remote access is still required, that all active users are authorized, and that the selected tunnel points only to the intended dashboard. Stop the tunnel during extended periods when public access is unnecessary.

Do not publish MySQL through the dashboard tunnel

The HTTP tunnel target is Traccar's web endpoint on port 8082. MySQL is a separate internal service and does not need to be made publicly reachable for browser access. Traccar communicates with it through the network defined by Docker Compose.

Test two paths after every change

After an application, database, networking, account, or tunnel change, test both the dashboard and tracker ingestion. A successful login does not prove that GPS messages are arriving. A device appearing online does not prove that browser permissions and remote authentication remain correct.

Troubleshoot installation and access problems

The Compose command is unavailable

If docker compose version fails, install or enable the Docker Compose plugin using Docker's platform-specific documentation. The Traccar workflow uses the modern space-separated command. Do not assume an older standalone docker-compose binary behaves identically.

The downloaded file is empty or invalid

Confirm that curl completed successfully and that compose.yaml contains YAML rather than an error page. The --fail option prevents many HTTP errors from being silently saved as successful output. Run docker compose config and do not continue until validation succeeds.

The image reference is not reproducible

A fixed Git commit does not make a moving image tag immutable. Inspect docker compose config, record docker compose images, and select a tested version tag or image digest when required by your deployment controls. Test any substitution because tags and digests must correspond to artifacts actually available from the registry.

Docker cannot bind port 8082

Another process may already occupy the host port, or host policy may prevent publication. Identify the conflict before editing the Compose file. If you deliberately select a different host-side port, preserve the container-side mapping required by Traccar and use the new host port for local tests and the Localtonet target.

The containers start and then exit

Run docker compose ps and inspect logs. Look for invalid database settings, rejected credentials, unavailable storage, permission failures, incompatible images, or resource termination. Preserve the first useful error instead of repeatedly recreating containers.

The dashboard is not immediately available

MySQL initialization can take time on first startup. Watch logs and service state for progress. If errors persist after initialization, investigate the reported failure rather than assuming additional waiting will repair it.

The dashboard works locally but not from another LAN device

Confirm the Docker host's LAN address, effective port publication, host firewall policy, and network reachability. A successful request to localhost proves only that the host can reach its own published service.

The Localtonet URL reports a connection failure

1. Confirm the Traccar and MySQL containers are running.
2. Open the exact target URL from the Localtonet client environment.
3. Confirm the target uses the correct host address and port.
4. Confirm the selected Localtonet client is connected.
5. Confirm the tunnel has been started, not merely created.
6. Check whether a host firewall or container boundary blocks the client.

The public URL loads the wrong application

The tunnel probably points to the wrong local port, or another service occupies the expected port. Compare the configured target with the URL that successfully loads Traccar from the Localtonet client device.

A tracker does not appear in Traccar

Verify the device model, configured Traccar protocol, unique device identifier, destination address, transport, and documented listener port. Some protocols use TCP, others use UDP, and some can involve both. Port 8082 is the web endpoint and must not be substituted for an unknown tracker listener.

The restored database does not start correctly

Check that the MySQL and Traccar versions are compatible with the backup, that the import completed without errors, and that the target database was prepared as intended. Review logs for schema, permission, encoding, and connection errors. Keep the failed restoration isolated and preserve the original backup unchanged.

Frequently asked questions