Trip Server 2

Introduction and History

TRIP is a web application supporting trip recording and itinerary planning.

The intended use is for a hiker, mountain-biker or other adventurer, to be able to publish and share their planned itinerary, then subsequently log their positions at intervals, allowing someone else to monitor their progress.

In the event of contact being lost, the plans and tracking information can be passed to rescue services etc., to assist with locating the missing adventurer.

Trip Server 2 is a port of Trip Server v1, written mostly in C++.

Features

The following features have been implemented:

Remote tracking server—client applications such as TripLogger Remote for iOS – (on the App Store) or GPSLogger for Android can be used to submit locations to the server.
Sharing tracks with others.
Viewing tracks on a map provided by a tile server, e.g. OpenStreetMap tiles.
Creating and sharing itineraries using the Markdown markup language.
Using the map, interactively creating routes and waypoints for an itinerary.
Uploading and downloading routes, tracks and waypoints for an itinerary as a GPX file.
Viewing routes, tracks and waypoints of an itinerary on the map.
Splitting, simplifying and joining routes and tracks.
Deleting individual points from routes and tracks.
Account maintenance – uploading TripLogger settings.
Account maintenance – password change.
Itinerary shares report – list shared itineraries including nicknames.
Itinerary search by coordinate and radius.
Administration – user management.
Administration – tile usage report.

Documentation

This document describes building the application. Once built and installed, you can view the application's documentation with the info viewer available in the Debian info package:

$ info trip-server

The user guide can also be viewed with:

$ info trip-user-guide

The user guide and application manual are available online.

Source Control

The source is maintained in a Git repository which can be cloned with:

$ git clone --recursive git://www.fdsd.co.uk/trip-server-2.git
$ cd ./trip-server-2/trip-server-common
$ git submodule update --init --recursive

Demo Options

Docker/Podman

You can use either Docker or Podman to run the application, using compose scripts.

docker-compose.yml runs the application without a tile server.
docker-compose-map-demo.yml runs the application with a tile server containing map data for Luxembourg.
Navigate to a directory containing one of those docker compose files.
If you're running the tile server option, create the following docker volumes:
```
$ docker volume create osm-data
$ docker volume create osm-tiles
```
Start the containers with:
```
$ docker compose -f docker-compose-map-demo.yml up -d
```
On the first occasion the tile server is started, it'll take a little while to create the initial database. It will also probably be quiet slow to both startup and also render the tiles. Use the docker container logs command to view the progress.
Use a browser to navigate to http://<docker-host>:8080/trip/app to view the application. Login with the credentials listed below in the 'Play with Docker' section. Refer to the user guide and application manual for more information.
Login using one of the following users and credentials:
- user@trip.test rasHuthlutcew7
- admin@trip.test 7TwilfOrucFeug
Select Help from the menu to view the user guide.

Stop the containers with:

$ docker compose -f docker-compose-map-demo.yml down

Play with Docker

Use Play with Docker to run the application with some test data in a browser, without having to install anything.
Navigate to Play with Docker and login using a Docker ID. If you do not have one, you will see the option to sign up after clicking Login then Docker.
Click + ADD NEW INSTANCE
Create a network for the containers to share:
```
$ docker network create trip-server
```
Optionally, run the Docker container for OpenStreetMap tile server

Note: I couldn't get this container to complete the import in the Play-with-docker environment, possibly due to insufficient resources. It sometimes randomly failed and otherwise failed importing water-polygons-split which uses a lot of resources. Nonetheless, the process is documented here as it may be useful in other environments. Also, 'Play with Docker' doesn't seem to have sufficient resources to run the fdean/tile-server image.
1. The import process temporarily requires a lot of memory. We need to create and mount a swap file:
```
$ sudo dd if=/dev/zero of=/swap bs=1G count=2
$ sudo chmod 0600 /swap
$ sudo mkswap /swap
$ sudo swapon /swap
```
2. Create Docker volumes for storing the database and caching map tiles:
```
$ docker volume create osm-data
$ docker volume create osm-tiles
```
3. Import OSM data for Monaco:
  
  It is recommended to use a small region to minimise resource usage.
```
$ docker run -v osm-data:/data/database/ \
-e DOWNLOAD_PBF=https://download.geofabrik.de/europe/monaco-latest.osm.pbf \
-e DOWNLOAD_POLY=https://download.geofabrik.de/europe/monaco.poly \
overv/openstreetmap-tile-server:2.3.0 import
```
  The process must complete without error. Check the final output carefully. If it fails, it is necessary to delete and re-create the Docker osm-data volume.
```
$ docker volume rm osm-data
$ docker volume create osm-data
```
4. Once the import completes successfully, run the map tile server:
```
$ docker run -v osm-tiles:/data/tiles/ -v osm-data:/data/database/ \
--network trip-server --network-alias map \
-d overv/openstreetmap-tile-server:2.3.0 run
```

Run the Trip Server database container:

    $ docker run --network trip-server --network-alias postgis \
    -e POSTGRES_PASSWORD=secret -d fdean/trip-database

Run the Trip Server web container:

    $ docker run --network trip-server -e TRIP_SIGNING_KEY=secret \
    -e TRIP_RESOURCE_SIGNING_KEY=secret -e POSTGRES_PASSWORD=secret \
    -e CONFIGURE_TILE_SERVER=no \
    --publish 8080:8080 -d fdean/trip-server-2

Set CONFIGURE_TILE_SERVER to yes if you have the map tile container running. When not set to yes, dummy map tiles are created showing their x, y and z values.

Once the application is running a link titled 8080 will be shown next to the OPEN PORT button at the top of the page. Click on the 8080 link to open a new browser window to the running web server. If the port number doesn't show up, click on OPEN PORT and enter the port number as 8080.
Login using one of the following users and credentials:
- user@trip.test rasHuthlutcew7
- admin@trip.test 7TwilfOrucFeug
Select Help from the menu to view the user guide.

Building

These instructions are for building and installing from the source distribution tarball, which contains additional artefacts to those maintained under Git source control. Building from a cloned Git repository requires additional packages to be installed as described in the next sub-sections, 'Additional Resources'.

Generally the application is built and installed with:

$ ./configure
$ make
$ sudo make install

Add CXXFLAGS='-g -O0' to disable compiler optimisation. E.g.

$ ./configure 'CXXFLAGS=-g -O0'

Optionally install the HTML and PDF documentation:

$ make html pdf
$ sudo make install-pdf install-html

By default links to the user guide within the application (e.g. the Help menu option), serve the locally installed user guide. The location can be overridden in the application's configuration file, see the Configuration section in the trip-server info manual.

See the PostgreSQL Database Configuration section in the instructions for TripServer v1 to install PostgreSQL and create the database. Upgrade the database to support the latest version of Trip Server v2 by running:

$ trip-server --upgrade

The upgrade option is re-runable. If the pgcrypto extension has already been created, a warning is issued but can be ignored.

You may need to add arguments to the ./configure command. Run ./configure --help to see available options. E.g. on a Raspberry Pi running Debian 10 (Buster) or Debian 11 (Bullseye), the following is required to successfully link against the Boost Locale library:

$ ./configure --with-boost-locale=boost_locale

If you are developing the application and need to add flags to the make distcheck command, set them in the DISTCHECK_CONFIGURE_FLAGS variable. You can also pass flags to make with the MAKEFLAGS variable, e.g.

$ PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$(pg_config --libdir)/pkgconfig" \
MAKEFLAGS='-j 4' \
DISTCHECK_CONFIGURE_FLAGS='--with-boost-locale=boost_locale' \
make distcheck

See http://www.randspringer.de/boost/ucl-sbs.html for help with the Boost library arguments.

GDAL is only required for extracting elevation data from elevation tile datasets. If you don't need this feature, disable GDAL.

$ ./configure --disable-gdal

Cairo is only used to create dummy map tiles which may be useful in a development environment where you do not wish to use a map tile server. Enable it with:

$ ./configure --enable-cairo

There are separate sections below with more information for building for 'Debian', 'Fedora', 'FreeBSD' and 'macOS'.

Additional Resources

The following resources are included in the tarball distributions of this application and will need to be separately installed under ./resources/static/ when building from a git clone of the repository. See ./Makefile.am for details of their expected locations.

Optional Text-based User Interface (TUI)

The application can optionally be built with the --enable-tui configure option to include an interactive TUI which can be used to create an initial admin user.

Download and install the Final Cut library. Note when building Final Cut for Linux, to enable mouse support you need to also install the gpm library. If you need to install additional libraries to fix a failed build, re-run Final Cut's configure script so that it re-configures the build to use those libraries.

On Debian 11 (Bullseye), install the following packages:
- libgpm-dev
- libncurses-dev
E.g.
```
$ sudo apt-get install libtool libgpm-dev libncurses-dev
$ mkdir work
$ cd work
$ curl -L -o finalcut-0.9.0.tar.gz \
https://github.com/gansm/finalcut/archive/refs/tags/0.9.0.tar.gz
$ tar -xf finalcut-0.9.0.tar.gz
$ cd finalcut-0.9.0
$ autoreconf --install
$ ./configure
$ make
$ sudo make install
$ sudo ldconfig
```
On macOS, install the ncurses port from MacPorts. The ./configure command will need to use the appropriate flags specifying the include directory for the for ncurses headers, otherwise term.h from macOS will be included first, producing errors similar to the following during the build phase:
```
    /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/term.h:728:1: error: a type specifier is required for all declarations
    __OSX_AVAILABLE(14.0) __IOS_AVAILABLE(17.0) __WATCHOS_AVAILABLE(10.0)
```
Where MacPorts has been installed under the /opt/local prefix, the ./configure command should be:
```
$ ./configure CXX=/usr/bin/g++ CPPFLAGS=-I/opt/local/include
```
Include the --enable-tui option when running configure for trip-server, e.g.:
```
$ ./configure --enable-tui
$ make
```
After creating the initial database, (see the PostgreSQL Setup section of the application manual (info trip-server)), execute trip-server with the --interactive option:
```
$ ./src/trip-server --interactive
```
Select the option to create a new user from the menu.

Debian

For Debian version 11 (Bullseye).

Minimal packages required to build from the source distribution tarball:

g++
gawk
info
libboost-dev
libboost-locale-dev
libcairomm-1.0-dev (optional)
libcmark-dev
libgdal-dev (optional)
libpqxx-dev
libpugixml-dev
libyaml-cpp-dev
make
nlohmann-json3-dev
postgis (optional)
postgresql (optional)
texinfo
texlive (optional for building PDF documentation)
uuid-dev

To build the application:

$ ./configure
$ make

The version of [nlohmann-json][] in Debian 10 (Buster) is too old for this application. Uninstall the package and download version v3.11.2 or later of json.hpp as described in the 'nlohmann/json' sub-section of the 'Dependencies' section below.

Building with GCC on ARM devices (e.g. Raspberry Pi) produces warnings about an ABI change in GCC 7.1.

Optionally, disable the warning by passing -Wno-psabi in CXXFLAGS, e.g.:

$ ./configure 'CXXFLAGS=-Wno-psabi'

Optionally, run the tests:

$ make check

Install:

$ sudo make install

The build requires resources from the Bootstrap and OpenLayers distributions. These are included in the distribution tarballs of this application or can be downloaded from the respective websites. (In this case, view the contents of ./Makefile.am to determine the required versions and directory structure for the build.)

Additional packages required to build from a Git clone:

autoconf
autoconf-archive
automake
autopoint
intltool

To re-create the required Gnu autotools files:

$ aclocal
$ autoheader
$ autoreconf --install
$ automake --add-missing --copy

Optionally install the uuid-runtime package which runs a daemon that libuuid uses to create secure UUIDs.

To run Trip Server as a daemon, create a system user, e.g.

$ sudo adduser trip --system --group --home /nonexistent --no-create-home

For further ideas on configuring your environment, see the scripts and files under the ./provisioning directory, which can be used to create a development environment using Vagrant. See the Testing and Developing Trip section of the application manual (info trip-server) for more information on using and running the application with both Vagrant and Qemu.

Fedora

Minimal packages required to build from the source distribution tarball, for Fedora version 40.

The application requires the nlohmann/json package, which is not included in the Fedora distribution. Follow the instructions in the 'nlohmann/json' section below to install it. Tested on Fedora with nlohmann/json version 3.11.3.

gcc
gcc-c++
gawk
boost-devel
cairomm-devel (optional)
cmark
gdal-devel (optional)
libpq-devel
libpqxx-devel
yaml-cpp-devel
pugixml-devel
libuuid-devel

Optionally install the uuidd package which runs a daemon that libuuid uses to create secure UUIDs.

GDAL is only required for extracting elevation data from elevation tile datasets. If you don't need this feature, disable GDAL.

$ ./configure --disable-gdal

Cairo is only used to create dummy map tiles which may be useful in a development environment where you do not wish to use a map tile server. Enable it with:

$ ./configure --enable-cairo

To build from source other than a tarball release, e.g. a git clone, examine the contents of ./provisioning/bootstrap.sh to see which packages are installed using dnf.

FreeBSD

Minimal packages required to build from the source distribution tarball, for FreeBSD version 14.

boost-all
cmark-devel
gdal (optional)
yaml-cpp
postgresql15-client
postgresql-libpqxx
pugixml
e2fsprogs-libuuid
nlohmann-json

GDAL is only required for extracting elevation data from elevation tile datasets. If you don't need this feature, disable GDAL.

$ ./configure --disable-gdal

Cairo is only used to create dummy map tiles which may be useful in a development environment where you do not wish to use a map tile server. Enable it with:

$ ./configure --enable-cairo

To build from source other than a tarball release, e.g. a git clone, examine the contents of ./provisioning/bootstrap.sh to see which packages are installed using pkg.

macOS

To build from a Git clone, install the following ports from MacPorts:

autoconf
automake
autoconf-archive
boost
cairomm (optional)
cmark
gawk
gdal +postgresql15+proj9 (optional)
intltool
libpqxx
nlohmann-json
pkgconfig
postgresql13-server
postgis3 +postgresql15+proj9
pugixml
yaml-cpp

Note: If make distcheck fails on macOS, install the texinfo and texlive packages from MacPorts, as the behaviour of the system installed /usr/bin/texi2dvi differs from the GNU version.

In recent macOS versions you may wish to define the -Wno-deprecated-builtins compiler flag to disable warnings in the Boost libraries related to __has_trivial_copy being deprecated in clang. E.g.

./configure PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$(pg_config --libdir)/pkgconfig" \
CXXFLAGS=-Wno-deprecated-builtins

It is safest to build the application with the same compiler used to compile the libraries by setting the CXX variable. Linking errors to the libraries is symptomatic of this issue. E.g.

./configure PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$(pg_config --libdir)/pkgconfig" \
CXX=/usr/bin/g++

A specific version of Boost can be specified with the location of the boost installation by specifying the --with-boost option to configure, e.g.:

./configure --with-boost=/opt/local/libexec/boost/1.81

Dependencies

This section describes how to manually download and installed required dependencies, should they not be available as a package.

libpqxx

Download, build and install the latest 6.x or 7.x release of libpqxx from https://github.com/jtv/libpqxx/releases/.

libpqxx needs the doxygen and xmlto packages installed to build the reference documentation and tutorial. Pass --disable-documentation to the ./configure command if you wish to skip building the documentation.

When running the ./configure command to build this application, define the PKG_CONFIG_PATH to include where libpqxx.pc and libpq.pc are installed. Also, it is safest to build the all the libraries with the same compiler as the Trip application will be built with. You may need to specify the compiler by defining the CXX environment variable when building both libpqxx and Trip.

e.g.:

$ export PATH="/opt/local/lib/postgresql15/bin:$PATH"
$ ./configure \
PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$(pg_config --libdir)/pkgconfig" \
CXX=/usr/bin/g++
$ make
$ sudo make install

nlohmann/json

Download the appropriate version of json.hpp from https://github.com/nlohmann/json/releases.

$ cd /usr/local/include
$ sudo mkdir nlohmann
$ sudo cp ~/Downloads/json.hpp /usr/local/include/nlohmann

Changelog

See CHANGELOG