OpenGTS & Traccar GPS tracking

The open-source OpenGTS web-based GPS tracking system is well established and allows the detailed management of tracking devices. However, the mGTS mobile phone client for OpenGTS only works with older versions of Android (a Nexus 5 phone running Android version 6.0.0 in our case). The Traccar open-source web-based GPS tracking system works with a broader range of GPS clients and protocols and the Traccar Client works with recent versions of Android. It is therefore useful to integrate Traccar with OpenGTS. In the case of Jura Mountains' mapping, being able to monitor the routes one actually followed in exploring historic paths and tracks allows us to check the accuracy of the JuraMap map. However, several issues arise so it is probably useful to summarise how to install and integrate self-hosted instances of OpenGTS and Traccar.

These implementation notes are for Ubuntu 18.04 LTS with Apache2 on HPE ProLiant DL20 Gen9 servers.

Traccar installation

a) Installation

As explained, the Traccar installer package (for Linux x64 and other systems) can be downloaded from traccar.org. We have not been able to integrate the latest version of of Traccar (version 5.3) with the latest version of OpenGTS (version 2.6.7) since there is a "tc_attributes" error on starting the Traccar server when it is configured to use an OpenGTS database. So these notes are for the last Traccar version 4 release (4.15) that is available here.

It is probably wise to make sure that Traccar works before carrying out the integration with OpenGTS. traccar-linux-64-4.15.zip is downloaded. Extraction of the .zip into say "/home/user/traccar" gives a shell script ("traccar.run") . In a terminal run, the script:

cd /home/user/traccar
sudo ./traccar.run

One then needs to edit the "traccar.xml" configuration file and maybe the "default.xml" configuration file, both found in "/opt/traccar/conf".

The important entries in "traccar.xml" are for the database. The traccar installation creates a database called "traccar" with "root" as the user so traccar.xml needs to be edited (see OpenGTS integration) in the obvious way (sudo nano /opt/traccar/conf/traccar.xml and assuming one is using an OpenGTS mySQL database, Ver 14.14, Distrib 5.7.33 for Linux x86_64 in our case):

<entry key='database.driver'>com.mysql.cj.jdbc.Driver</entry>

<entry key='database.url'>jdbc:mysql://127.0.0.1:3306/gts?allowMultiQueries=true</entry>

Depending upon the approach used to set up the database,(see below), the "root" user might be replaced by "phpmyadmin".

Other changes to default.xml are given in OpenGTS integration

For default.xml, it is probably wise to disable the geocoder:

<entry key='geocoder.enable'>false</entry>

and to remove the other geocoder entries.

Updating of the database structure should also be disabled by removing the entry:

<entry key='database.changelog'>./schema/changelog-master.xml</entry>

There are also several keys that need to be removed from default.xml. The traccar.xml and default.xml that work for us are available here and reproduced below.

It is perhaps useful to know that the Traccar database uses the InnoDB storage engine. The Traccar installation ensures that InnoDB is used. An OpenGTS database however needs to be MyISAM.

b) Operation

In princple, one can now start Traccar:

sudo systemctl start traccar

and check that Tracar is running:

sudo systemctl status traccar

and that it is listening on port 5055:

sudo netstat -tulpn ¦ grep 5055

Recent versions of the Traccar Client use the OsmAnd protocol to report GPS data. The Traccar server "default.xml" file shows that osmand uses port 5055.

With an Apache2 webserver set up as a reverse proxy for both normal and unencrypted data traffic, the server URL in the Traccar Client can be of the form:

http://mytraccar.mydomain.net:5055

This is also the case for Traccar integrated with OpenGTS where Traccar writes data to an OpenGTS database called as above, for example, "gts".

Both the Traccar and OpenGTS web interfaces will of course require encrypted traffic so the fact that the Traccar Client (and indeed the mGTS Client for OpenGTS) do not require encrypted traffic does not mean that one can ignore setting up a reverse proxy for encrypted traffic.

The integrated Traccar-OpenGTS setup also works with a reverse proxy for port 5055, i.e., for the Traccar Client one can use an https address of the form:

http://mytraccar.mydomain.net

The Traccar web interface runs on port 8082 (http://localhost:8082) and the Traccar installation creates a default user (login = "admin"; password = "admin") and the IMEI number of a mobile device is used as the unique identifier (for an Android phone, the IMEI number is found under "Settings -> About phone").

Traffic between a client and the Traccar server can be monitored using the Traccar log file at "/opt/traccar/log/traccar-server.log".

It is sometimes useful to start traccar manually, especially if there is an error in the traccar.xml configuration file:

sudo /opt/traccar/jre/bin/java -jar tracker-server.jar conf/traccar.xml

and it is perhaps useful to note that Traccar is installed with its own Java so there is no need to worry about one's globally installed Java versions.

It was felt at some stage that it might be wise to increase the systemd restart time delay by editing the traccar service configuration. For example, set "WatchdogSec = 600" using:

sudo systemctl edit --full traccar.service

c) Apache reverse proxies

For client traffic, support for the tunnelling of web socket connections from a Traccar client to a self-hosted backend Traccar server websocket at say http://192.168.1.133 is needed. Apache modules are installed:

sudo a2enmod ssl proxy_http proxy_wstunnel rewrite

For unencrypted traffic, the standard default configuration "/etc/apache2/sites-available/000-default.conf" entry is:

ServerName traccar.peterboswell.net

ErrorLog ${APACHE_LOG_DIR}/error.log

CustomLog ${APACHE_LOG_DIR}/access.log combined

ProxyRequests Off

ProxyPass /api/socket ws://192.168.1.133:5055/api/socket

ProxyPassReverse /api/socket ws://192.168.1.133:5055/api/socket

ProxyPass / http://192.168.1.133:5055/

ProxyPassReverse / http://192.168.1.133:5055/

RewriteEngine on

RewriteCond %{SERVER_NAME} =map.opennbs.net

RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]

</VirtualHost>

For encrypted traffic, the "/etc/apache2/sites-available/000-default-le-ssl.conf" entry is (we are using Certbot-install LetsEncrypt certificates):

ServerName traccar.mydomain.net

DocumentRoot /var/www/html

ErrorLog ${APACHE_LOG_DIR}/error.log

CustomLog ${APACHE_LOG_DIR}/access.log combined

ProxyRequests Off

Order deny,allow

Allow from all

</Proxy>

ProxyPass /api/socket ws://192.168.1.133:5055/api/socket

ProxyPassReverse /api/socket ws://192.168.1.133:5055/api/socket

ProxyPass / http://192.168.1.133:8082/

ProxyPassReverse / http://192.168.1.133:8082/

Order allow,deny

Allow from all

</Location>

SSLCertificateFile /etc/letsencrypt/live/edit.opennbs.net/fullchain.pem

SSLCertificateKeyFile /etc/letsencrypt/live/edit.opennbs.net/privkey.pem

Include /etc/letsencrypt/options-ssl-apache.conf

</VirtualHost>

</IfModule>

Certificates are created using certbot:

sudo certbot certonly --standalone --preferred-challenges http -d mytraccar.mydomain.net -d subdomain.mydomain.net .....

where mytraccar.mydomain.net is added to the list of subdomains that need certificates. Best to add --dry-run for a dry run. Apache will need to be stopped to allow certification of mytraccar.mydomain.net.

OpenGTS integration

A. Database

Assume for now the OpenGTS is installed at "/usr/local/OpenGTS_2.6.7" (see guide) in the sense that in our case Apache Tomcat version 3 installed at "/usr/local/apache-tomcat-7.0.13" has a "webapps" folder with an OpenGTS folder called "track" and a "track.war" file. The OpenGTS web interface is available at "https://myopengts.mydomain.net/track/Track/"

The key aspect in integrating Traccar with OpenGTS is the OpenGTS MySQL database.

It is unclear what is best for setting up the mySQL database.

A1. Approach 1

Stop the Traccar server and the terminal commands:

cd /usr/local/apache-tomcat-7.0.13
bin/initdb.sh -rootUser=root -rootPass=root
bin/admin.sh Account -account=phpmyadmin -pass=password -create

create a MySQL database called "gts" with a user account called "phpmyadmin" (it is convenient to use the same username as for phpmyadmin that can be used to manage MySQL databases). Note that the OpenGTS database tables use the MyISAM storage engine. One can of course create the MySQL database and its users and accounts manually using mysql.

A2. Approach 2

Moving traccar between servers has suggested that it is more reliable to have "root" as the user in the traccar.xml configuration file and to start with a mySQL database that has been initialised using the OpenGTS using its bin/admin.sh script. This creates the user "acct" with a password "acct".

Whichever approach is used, once the database has been, following the usual OpenGTS practice, create a user and a vehicle (essentially an account for a phone) that has both the "Unique ID" and the "Vehicle ID" set to the phone's IMEI number.

B. Communications

Not to be forgotten is that port number 5055 will need to be opened on any router.

Traccar can now be started:

sudo systemctl start traccar.service

The Traccar log will show some rather odd records after the " Starting server ..." statement such as "Port disabled due to conflict....." which can be ignored. Once a Traccar Client is installed on a phone and configured, the client uses the OsmAnd protocol so what one is looking for are the statements:

connected
[{a message code} osmand ] < {an IP} number HEX: {a hex message}

which means that the client has communicated. The HEX message can be decoded. There follow various comments about "Query not provided" and "error - NullPointerException" that can be ignored. If integration is working, a record appears in the OpenGTS database's "EventData" table and in the OpenGTS web interface under "Vehicle Data Reports".

In terms of checking, Traccar's port check tool will say that port 5055 is closed in spite of netstat showing that it is open using the terminal command:

sudo netstat -tulpn ¦ grep 5055

Integration of Tracar with OpenGTS of course does not affect the OpenGTS GPS tracking service. In our case, the OpenGTS web interface is stll available at the URL of the form:

https://myopengts.mydomain.net/track/Track

and the mGTS client is configured to comunicate with the OpenGTS port (8080 in our case).

APPENDIX

traccar.xml & default.xml

The files are available here . "/opt/traccar/conf/traccar.xml" must be edited as follows:

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

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

<entry key='config.default'>./conf/default.xml</entry>

<entry key='web.enable'>false</entry>

<entry key='database.driver'>com.mysql.cj.jdbc.Driver</entry>

<entry key='database.url'>jdbc:mysql://127.0.0.1:3306/gts?allowMultiQueries=true</entry>

<entry key='database.user'>phpmyadmin</entry>

<entry key='database.password'>password</entry>

SELECT CONCAT('1', imeiNumber) AS id, imeiNumber AS uniqueId FROM Device WHERE imeiNumber REGEXP '^[0-9]+$';

</entry>

SELECT CONCAT('1', imeiNumber) AS id, imeiNumber AS uniqueId FROM Device WHERE imeiNumber REGEXP '^[0-9]+$';

</entry>

START TRANSACTION;

UPDATE Device SET lastValidLatitude = :latitude, lastValidLongitude = :longitude, lastGPSTimestamp = UNIX_TIMESTAMP(:fixTime), lastUpdateTime = UNIX_TIMESTAMP(NOW()) WHERE imeiNumber = SUBSTRING(CAST(:deviceId AS CHAR(32)), 2);

SELECT @accountID := accountID, @deviceID := deviceID FROM Device WHERE imeiNumber = SUBSTRING(CAST(:deviceId AS CHAR(32)), 2);

INSERT INTO EventData (accountID, deviceID, timestamp, statusCode, latitude, longitude, speedKPH, heading, altitude, rawData, creationTime, address)

VALUES (@accountID, @deviceID, UNIX_TIMESTAMP(:fixTime), 0, :latitude, :longitude, :speed * 1.852, :course, :altitude, '', UNIX_TIMESTAMP(NOW()), :address);

COMMIT;

</entry>

</properties>

The "/opt/tracar/conf/default.xml" file also needs editing as follows:

remove: <entry key='web.enable'>false</entry>
remove <entry key='database.changelog'>./schema/changelog-master.xml</entry>
set <entry key='geocoder.enable'>false</entry>
remove: <entry key='event.ignoreDuplicateAlerts'>true</entry>

5 March 2024