Audit trail logging service

Usage no npm install needed!

<script type="module">
  import nearformTrail from 'https://cdn.skypack.dev/@nearform/trail';




Trail is a audit trail log service. It supports logging all kind of actions with a flexible model scheme.

For information about the model scheme, see the trail-core package README. This repository is home to Trail's three main modules:

Module Package
@nearform/trail-core ./packages/trail-core
@nearform/trail-hapi-plugin ./packages/trail-hapi-plugin
@nearform/trail-hapi-server ./packages/trail-hapi-server

Node.js support

Trail requires Node.js 8.9.0+.

The Hapi plugin and server packages require Hapi 17+.

Database support

Trail requires an instance of Postgres (version 9.5+) to function correctly. For simplicity, a preconfigured docker-compose file has been provided. To run:

docker-compose up
  • Note: Ensure you are using the latest version of Docker for (Linux/OSX/Windows)
  • Note: Trails needs PostgreSQL >= 9.5

Populate the database

The initial tables can be created by executing:

npm run pg:init

pgAdmin database access

As the Postgresql docker container has its 5432 port forwarded on the local machine the database can be accessed with pgAdmin.

To access the database using the pgAdmin you have to fill in also the container IP beside the database names and access credentials. The container IP can be seen with docker ps. Use IP and use postgres as username/password to connect to database server.


We use postgrator for database migrations. You can find the sql files in the packages/trail-core/database/migrations folder. To run the migrations manually:

node packages/trail-core/database/migrate.js --version=<version>`

Note: Running the tests or init commands will automaticaly bring the db to the latest version.

Swagger API Documentation

The Swagger API documentation can be accessed from trail itself. Simply start the server:

npm run start

and then go to http://localhost:8080/documentation

The Swagger documentation also gives the ability to execute calls to the API and see their results.

ENV variables to set configuration options

Each package uses a default configuration file and then a environment (the value of the NODE_ENV environment variable, with a default of development) configuration file.

If you put a file named after the enviroment in the config folder of the current working directory, it will be parsed and it will override any existing setting.

To get started, look at the files defined in the config folder of each package.

Testing, benching & linting

Before running tests, ensure a valid Postgres database is running. The simplest way to do this is via Docker. Assuming docker is installed on your machine, in the root folder, run:

docker-compose up -d
npm run pg:test:init

This will start a Postgres database. Running test or coverage runs will automatically populate the database with the information it needs.

Note: you can tail the Postgres logs if needed with docker-compose logs --tail=100 -f

To run tests:

npm run test

Note: running the tests will output duplicate keys errors in Postgres logs, this is expected, as the error handling of those cases is part of what is tested.

To lint the repository:

npm run lint

To fix (most) linting issues:

npm run lint -- --fix

To create coverage reports:

npm run coverage


Copyright nearForm Ltd 2018. Licensed under MIT.