How to create a systemd for Postgrest

It may be useful not to have to launch postgrest each time the computer start or each time the postgrest API server is needed. For this we will create a systemd service which will launch the postgrest server at startup.

What is systemd

“Systemd is a software suite that provides an array of system components for Linux[6] operating systems.” from Wikipedia

Systemd is a remplacement for the systemV init daemon for Linux.

Its purpose is to offer better managment of dependencies between services and allows parallelism of loading at startup. Some Linux distributions have it adopted by default like: Fedora or Debian.

In summary systemd is a collection of programs, services and librairies:

  • systemctl
  • journalctl
  • Init
  • Process managment
  • Network management (networkd)
  • Login management (logind)
  • Logs (journald)
  • etc …

Any entity managmenet by systemd is called unit. Systemd unit can manage:

  • Services
  • Socket
  • etc …

Here we will focus on services.

A systemd service is a unit supervised by systemd, runs in the background and activates under certain conditions. For exmample the service hddtemp monitors the temperature of your hard drives and triggers an alert if it exceeds a certain threshold.

Documentation:

Create a systemd service for Postgrest

To create a systemd service for Postgrest we need to create 2 files:

  • config
  • postgrest.service

Create the configuration file: config

This config file is almost identical to the one used to start postgrest without systemd with some additional information.

Important

It’s highly recommended to have read the documentation on How to create a RESTfull API with Postgrest and the part Running Postgrest of this documentation.

In this file you need 5 mandatory key:

  • db-uri
  • db-schemas
  • db-anon-role
  • jwt-secret
  • server-port

You need to create postgrest configuration file in /etc/postgrest/config.

Database information

The first db key is: db-uri. Its the URI for the database.

db-uri = "postgres://<authenticator-role-name>:<authenticator-role-password>@<db-host>:<db-port>/<database-name>"

The second is the name of the schema for your API: db-schemas.

db-schemas = "<schema-name>"

And the last is the name of your anon user: db-anon-role.

db-anon-role = "<web_anon-role-name>"

Jwt informations

The JSON Web Token (jwt) is a proposed internet standard for creating data with optional signature. This standard was defined in the RFC 7519.

The jwt-secret configuration key is a string of characteres longer than 32 characters.

jwt-secret = "<your-secret-jwt-token>"

Documentation:

Server informations

The last information is the server-port: The port the server is listening on.

server-port = <listening-port>

The postgrest configuration file

The config file should look something like this:

/etc/postgrest/config:

db-uri = "postgres://authenticator:mysecretpassword@localhost:5432/tuto_postgrest"
db-schemas = "tuto_api"
db-anon-role = "web_anon"
jwt-secret = "AEYIl2Krz2gWHo53vAbTiAgPOx4qsL6LCSujT22e"
server-port = 3000

Documentation:

Create the service file: postgrest.service

You need to create the systemd service file in /etc/systemd/system/postgrest.service.

The service file contains 3 part:

  • Unit
  • Service
  • Install

Unit

The unit part describe your unit (service). Here we used 2 key

  • Description for the description of your service (thanks captain obvious :wink: :wink:)
  • After to indicate the prerequisites necessary for the operation of the service.

Documentation:

Service

Service is used to indicate what the service make when you start, reload, stop, etc.. your service.

  • ExecStart indicate what command is execute when you start your service. This is mandatory In this example the service launch postgrest with our config file, write above.
  • ExecReload indicate what command is execute when you reload your service

Documentation:

Install

Install is information related to the installation of the service.

Here we only use WantedBy to specified in which Target the service is active. multi-user.target, the service is active in Runlevels 2, 3, 4 and 5. To know more on Targets read the systemd page.

Documentation:

The systemd service file

The service file should look like this:

/etc/systemd/system/postgrest.service

[Unit]
Description=REST API for any PostgreSQL database
After=postgresql.service

[Service]
ExecStart=/usr/local/bin/postgrest /etc/postgrest/config
ExecReload=/bin/kill -SIGUSR1 $MAINPID

[Install]
WantedBy=multi-user.target

Documentation:

Run the systemd service

The last thing to do is: run the service.

systemctl enable postgrest
systemctl start postgrest
  • enable is used to add this service to this list of programs launched at startup.
  • start is to start your service.

Some useful command

systemctl restart postgrest ## (to reloading the service)
systemctl status postgrest ## (to see the status of the service (active or inactive))
systemctl stop postgrest ## (to stop the service)