Install On-Premises

Pro Custodibus CE and Pro Custobius EE can be installed as Docker containers, or as individual native components:

  1. API Server

  2. Database

  3. App Web UI

We recommend you that you install the components on a server running a relatively recent version of Linux (such as the current LTS version of your preferred Linux distribution). For a production configuration, you’ll usually also want to set up a few other things:

  • TLS certificate (for the API server and app UI)

  • SMTP relay server (to send alerts and other emails)

  • Geolocation data files (to calculate and display geographic locations of IP addresses)

However, you can use Pro Custodibus without any of these extras.

Docker

We maintain container images for the API server and app UI on Docker Hub; these are the images for the Community Edition:

And these are the images for the Enterprise Edition:

For the database, we recommend you use the latest version of the official PostgresSQL image.

Generate Docker-Compose Script

The generate-docker-compose.sh script will generate a docker-compose.yml file and several other necessary config files to run the core components (API server, database, and app UI) together.

To use it, first create a directory in which to hold the docker-compose.yml file (and the other various config files):

$ sudo mkdir -p /srv/containers/procustodibus
$ sudo chown $USER:$(id -g) /srv/containers/procustodibus
$ cd /srv/containers/procustodibus

Then run the script from that directory, specifying ce as its first argument to use the Community Edition, or ee as its first argument to use the Enterprise Edition:

$ curl https://git.sr.ht/~arx10/procustodibus-api/blob/main/ops/install/generate-docker-compose.sh | bash -s ee
The "canonical" URL is the URL end-users enter into their browser to access
Pro Custodibus. For example, "https://pro.custodib.us" is the canonical URL of
the SaaS edition. With this URL, the host is "pro.custodib.us", the scheme is
"https", and the port is "443" (the default for the scheme).

For on-premises editions, we recommend setting the canonical URL to one like
the following, where your organization controls the domain name "example.com":

https://procustodibus.example.com

Enter the canonical URL host (eg procustodibus.example.com): custos.internal.example.net
Enter the canonical URL scheme (default https):
Enter the canonical URL port (default 443):
Enter the SMTP server address (default host.docker.internal):
NOTE: If this SMTP server requires SSL or authentication, you must configure it
via the environment variables in the api.env file.
Enter the 'From' address emails will use (default procustodibus@custos.internal.example.net): custos-alerts@example.net
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  6070  100  6070    0     0  13363      0 --:--:-- --:--:-- --:--:-- 13399
Use letsencrypt certbot to automatically manage SSL certificates? (default yes):
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   932  100   932    0     0   1800      0 --:--:-- --:--:-- --:--:--  1799
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   769  100   769    0     0   1753      0 --:--:-- --:--:-- --:--:--  1755
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   177  100   177    0     0    350      0 --:--:-- --:--:-- --:--:--   350
Enter the email address to use for the letsencrypt account (eg me@example.com): ops@example.net
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   440  100   440    0     0    973      0 --:--:-- --:--:-- --:--:--   973
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1344  100  1344    0     0   3066      0 --:--:-- --:--:-- --:--:--  3068

With the above example, we configured the canonical URL for Pro Custodibus EE to be https://custos.internal.example.net; and we set up Let’s Encrypt Certbot to generate and maintain a TLS cert for that domain name.

Let’s go through each setting:

Canonical URL Host

This should be a DNS name of the server on which your are installing; or if you will use an HTTP reverse proxy in front of the server, a DNS name of that reverse proxy. For example, if you control the DNS for example.com, you might use procustodibus.example.com as this DNS name. If you have not yet configured your DNS servers with your chosen name, do so now.

If you decide to change this setting later, you’ll have to modify the following files:

  • api.env: change the API_CANONICAL_HOST, APP_URL, and CORS_ENDPOINTS variables.

  • app.env: change the API_URL variable; and if you’re using the Certbot, change the CERTBOT_DOMAINS variable.

  • nginx/procustodibus.conf: change the server_name settings (for each server block); and if you’re using the Certbot, also change the ssl_certificate and ssl_certificate_key paths.

  • letsencrypt/cli.ini: if you’re using the Certbot, change the domains setting.

Canonical URL Scheme

This can be either http or https. Note that some features of the app UI may not work correctly without HTTPS (see MDN’s Secure Contexts documentation for details).

If you will use a reverse proxy in front of the server to terminate TLS, select https. After the docker-compose.yml file has been generated, make the following changes:

Canonical URL Port

The default port for http is 80; the default port for https is 443. This should be the external TCP port to which browsers and agents initiate a connection to the server.

If you will use a reverse proxy in front of the server, enter the port on which the reverse proxy is listening for new connections. After the docker-compose.yml file has been generated, change the ports setting for its app service to reflect the port on which the server itself should listen.

For example, if the reverse proxy forwards plain HTTP requests to the server’s port 8080, use 8080:80 for the ports setting; or if the reverse proxy forwards HTTPS requests to the server’s port 1234, use 1234:443 for the ports setting.

If you have not yet configured your firewalls to allow new connections through to the server on this port, do so now. Note that if you are using the Certbot, you will also have to allow new connections to port 80 (or manually configure the Certbot to use a DNS plugin instead).

SMTP Server Address

This should be the IP address or DNS name of an SMTP relay server that the API server can send email through. The default setting (host.docker.internal) will cause the API to attempt to send emails through whatever process is listening on TCP port 25 of the container host.

By default, the API server will attempt to send emails without encrypting or authenticating the connection. If your SMTP relay requires encryption or authentication, you’ll need to configure some additional MAIL_* environment variables in the generated api.env file.

If you do not have an SMTP relay server available for Pro Custodibus, just accept the default setting — attempts to send email will simply fail with a harmless error message.

From Email Address

This should be the email address the API will use for the From header when it sends emails.

Set this only to a literal address, such as procustodibus-messages@example.com. To set the From display name (eg “Pro Custodibus Messages”), adjust the MAIL_FROM_NAME variable in the generated api.env file.

Use Let’s Encrypt Certbot

Select yes to use the Let’s Encrypt Certbot to generate and maintain a TLS certificate for the Canonical URL Host you chose; or no to provide your own TLS certificate.

If you select yes, you will either need to expose the server’s TCP port 80 to the Internet, or you will have to manually configure the Certbot to use a DNS plugin instead of the default webroot plugin.

If you will use a reverse proxy in front of the server, you usually would select no for this option — usually you would use the reverse proxy to terminate TLS itself (and therefore not need a globally-trusted TLS certificate for the server).

Email Address for Let’s Encrypt Account

This is the email address at which Let’s Encrypt will send you notifications that the TLS certificate is about to expire (if you chose to Use Let’s Encrypt Certbot).

Generated Files

The generate-docker-compose.sh script will generate the following directory structure:

$ tree
.
├── acme-challenge
├── api.env
├── app.env
├── config
│   └── license
├── docker-compose.yml
├── initdb
│   └── init.sql
├── letsencrypt
│   └── cli.ini
├── nginx
│   └── procustodibus.conf
└── work

7 directories, 6 files

Let’s go through each directory and file:

acme-challenge

This directory is for the responses to Let’s Encrypt challenges. It’s mapped to the /.well-known/acme-challenge/ directory in the NGINX config of the app container. You’d need to access this directory only if you’re trying to satisfy the challenges manually (or through your own automation scripts).

api.env

This file contains the configuration for the API server (in the form of environment variables). You may want to review this file and adjust some settings before running the API server.

If you modify this file while the api container is running, you must restart it for your changes to take effect.

You can find the latest source for this file at https://git.sr.ht/~arx10/procustodibus-api/tree/main/item/env.example.

app.env

This file contains the configuration for the app UI (in the form of environment variables). These settings are mainly for display values; the only true functional setting is the API_URL variable (which the app UI uses, when running in a browser, to connect to the API).

If you modify this file while the app container is running, you must restart it for your changes to take effect.

You can find the latest source for this file at https://git.sr.ht/~arx10/procustodibus-app/tree/main/item/env.example.

config/license

This is the directory where you place license key files (when using Pro Custodibus EE).

docker-compose.yml

This is file contains the container configuration. You may want to review this file before running Docker Compose.

You can find the latest source for this file at https://git.sr.ht/~arx10/procustodibus-api/tree/main/item/ops/install/docker-compose.yml.

initdb/init.sql

This file is run by the database when it starts up the first time. It creates the database and user that the API server will use. After the database is initialized, this file is never used again.

You can find the latest source for this file at https://git.sr.ht/~arx10/procustodibus-api/tree/main/item/ops/db/init.sql.

letsencrypt/cli.ini

This is the configuration for the Certbot. If you are using the Certbot, it will save its certificate and account information in the letsencrypt/ directory (which is mapped to the /etc/letsencrypt/ directory of the app container, in which the Certbot runs).

You can find the latest source for this file at https://git.sr.ht/~arx10/procustodibus-app/tree/main/item/ops/run/letsencrypt.ini.

nginx/procustodibus.conf

This is the configuration for NGINX, which is used to serve the app UI, as well as to reverse-proxy the API server. NGINX is run in the app container.

You can find the latest source for this file at https://git.sr.ht/~arx10/procustodibus-app/tree/main/item/ops/run/nginx.conf.

work

This is a scratch directory, mounted to each of the containers as /work. It exists merely for convenience (in case you need to perform some administrative tasks that require files to be copied back and forth).

TLS Certificates

To run Pro Custodibus with HTTPS when you don’t use a reverse proxy in front of it and you don’t Use Let’s Encrypt Certbot, you will need to provision Pro Custodibus with a TLS certificate manually (or through your own automation scripts). This certificate should match the DNS name of the Canonical URL Host.

For example, if the DNS name is procustodibus.example.com, create a live/procustodibus.example.com subdirectory of the letsencrypt/ directory; and place the full chain and private key for the certificate in that subdirectory, as the fullchain.pem and privkey.pem files respectively:

$ find letsencrypt -type f
letsencrypt/live/procustodibus.example.com/fullchain.pem
letsencrypt/live/procustodibus.example.com/privkey.pem

Alternately, you can adjust the SSL configuration settings in the NGINX configuration file at nginx/procustodibus.conf to use your preferred SSL settings (note that the letsencrypt/ directory on the container host is mapped to the /etc/letsencrypt/ directory in the app container).

API Server

To install the API server natively, download the latest version from the Download page (or build it yourself).

The API server binaries must be built on a machine (or virtual machine or container) using the exact same CPU architecture and OS (operating system) version as it will be run on. If you do not find an exact match to the CPU architecture and OS version on the Download page, you must build it yourself.

On your server, extract the API tarball, and move its api/ directory to a convenient location (like the /srv/procustodibus/api/ directory):

$ tar xf procustodibus-api-ce-1.2.3-Linux-aarch64-fedora-38.tar.bz2
$ sudo mkdir -p /srv/procustodibus
$ sudo mv api /srv/procustodibus/.

On a minimal system, you may need to install the bzip2 package to extract this tarball.

Required Libraries

The machine on which you run the API server must have the following libraries installed:

Alpine

On Alpine, install the following packages:

$ doas apk add libsodium openssl postgresql15-client zlib

Arch

On Arch, install the following packages:

$ sudo pacman -S libsodium openssl postgresql-libs zlib

Debian

On Debian and derivatives (such as Ubuntu), install the following packages:

$ sudo apt install libsodium23 openssl postgresql-client zlib1g

Fedora

On Fedora and derivatives (such as RHEL), install the following packages:

$ sudo dnf install libsodium openssl postgresql zlib

The libsodium package is included in Fedora’s package repositories, but not in some of its derivatives. If the distro uses the EPEL repositories, make sure you enable those repositories first:

$ sudo dnf install epel-release elrepo-release

For distros that don’t use the EPEL repositories (such as Amazon Linux 2023), you will need to install libsodium from source.

FreeBSD

On FreeBSD, install the following packages:

# pkg install libsodium openssl postgresql15-client

openSUSE

On openSUSE, install the following packages:

$ sudo zypper install libsodium23 openssl postgresql libz1

Required Locale

The machine on which you run the API server must have the en_US.UTF-8 locale definition installed. Run the following command to check:

$ locale -a | grep en_US
en_US
en_US.iso885915
en_US.utf8

If the result of this command does not include en_US.utf8, you must install the en_US.UTF-8 definition.

Alpine

On Alpine, run the following commands to install the necessary locale definition:

$ doas apk add musl-locales

On Alpine, locale -e | grep en_US will simply report en_US, which is fine.

Arch

On Arch, run the following commands to install the necessary locale definition:

$ sudo sed -i -e 's/#en_US.UTF-8/en_US.UTF-8/' /etc/locale.gen
$ sudo locale-gen

Debian

On Debian (and derivatives), run the following commands to install the necessary locale definition:

$ sudo apt install locales
$ sudo sed -i -e 's/# en_US.UTF-8/en_US.UTF-8/' /etc/locale.gen
$ sudo locale-gen

Fedora

On Fedora (and derivatives), run the following commands to install the necessary locale definition:

$ sudo dnf install glibc-langpack-en glibc-locale-source
$ sudo localedef -f UTF-8 -i en_US en_US.UTF-8

openSUSE

On openSUSE, run the following commands to install the necessary locale definition:

$ sudo zypper install glibc-locale-base

Environment Variables

Copy the env.example file from the API tarball to /etc/default/procustodibus-api:

$ sudo cp /srv/procustodibus/api/env.example /etc/default/procustodibus-api

This file contains all the core configuration settings for Pro Custodibus — including several secrets, like the database password. Therefore, restrict its permissions so that only the root user can access it:

$ sudo chown root:root /etc/default/procustodibus-api
$ sudo chmod 640 /etc/default/procustodibus-api

On FreeBSD, substitute the /etc/defaults/ directory for /etc/default/.

On Alpine (or any system using OpenRC), substitute the /etc/conf.d/ directory for /etc/default/, and add an export command before each variable:

$ doas sed -i -r 's/^(#?)([A-Z_]+=)/\1export \2/' /etc/conf.d/procustodibus-api

Edit this file as root, and configure at least the following settings:

API_CANONICAL_HOST

The API_CANONICAL_HOST, API_CANONICAL_PATH, API_CANONICAL_PORT, and API_CANONICAL_SCHEME environment variables should represent the canonical URL to the API server as client browsers (and agents) should see it. The API_PORT and API_SSL_PORT variables should specify the actual plaintext or TLS port on which the API listens. The API_FORWARDED variable should be true if you are going to reverse-proxy the API (and blank if not).

For example, if you are going to reverse-proxy the API through the same webserver that serves the app UI, and you want the canonical URL of the API server to be https://custos.internal.example.net/api, this is what you’d specify for API_CANONICAL_HOST and friends:

API_CANONICAL_HOST=custos.internal.example.net
API_CANONICAL_PATH=/api
API_CANONICAL_PORT=443
API_CANONICAL_SCHEME=https
API_FORWARDED=true
#API_PORT=4000
#API_SSL_PORT=0

If you are not going to reverse-proxy the API, and want it to terminate its own TLS with a canonical URL of https://api.procustodibus.example.com, this is what you’d specify for API_CANONICAL_HOST and friends:

API_CANONICAL_HOST=api.procustodibus.example.com
#API_CANONICAL_PATH=
#API_CANONICAL_PORT=0
API_CANONICAL_SCHEME=https
#API_FORWARDED=
API_PORT=0
API_SSL_PORT=443

(You’d also specify the API server’s TLS cert and key via the other API_SSL_* environment variables.)

If you are not going to reverse-proxy the API, and are not going to use TLS with it, and want to use a canonical URL of http://api.procustodibus.corp:8081, this is what you’d specify for API_CANONICAL_HOST and friends:

API_CANONICAL_HOST=api.procustodibus.corp
#API_CANONICAL_PATH=
#API_CANONICAL_PORT=0
#API_CANONICAL_SCHEME=http
#API_FORWARDED=
API_PORT=8081
#API_SSL_PORT=0

APP_URL

Set the APP_URL environment variable both to the canonical URL of the app UI, such as https://custos.internal.example.net, https://app.procustodibus.example.com, or http://app.procustodibus.corp:8080.

This is the URL that you want client browsers to use to access the app UI. It must be different that the API’s canonical URL; and must use a different domain name or port unless the webserver hosting the app UI is also going to reverse-proxy the API (in which case the API’s canonical URL would usually be the same as the app UI’s, except for the addition of an /api path for the API).

DB_ALEK_1

Generate a random 32-byte Base64-encoded value for the database application-level encryption key:

$ openssl rand -base64 32
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

Copy the random key and paste it in as the value for the DB_ALEK_1 environment variable:

DB_ALEK_1="value:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="

DB_HOSTNAME

Once you set up the Database, set the DB_HOSTNAME environment variable to the IP address or hostname of database server.

Use localhost if the database is running on the same machine as the API.

DB_DATABASE

Once you set up the Database, if you create the Pro Custodibus database as anything other than procustodibus_db, set the DB_DATABASE environment variable to the name of this database.

DB_USERNAME

Once you set up the Database, if you create the Pro Custodibus user as anything other than procustodibus_user, set the DB_USERNAME environment variable to the name of this user.

DB_PASSWORD

Once you set up the Database, if you create the Pro Custodibus user with a password of anything other than procustodibus_password, set the DB_PASSWORD environment variable to the password.

SIGNUP_KEY

Generate a short random value for the Signup Key on the Sign Up form:

$ openssl rand -base64 6
abcd1234

Copy the random key and paste it in as the value for the SIGNUP_KEY environment variable:

SIGNUP_KEY="abcd1234"

SITE

Set the SITE environment variable to prod.

Daemon User

Create a daemon user and group for the API. On most Linux distributions, you can use the useradd command for this, which has set of standard options:

$ sudo useradd \
    --home-dir /srv/procustodibus/api \
    --shell /usr/sbin/nologin \
    --system \
    --user-group \
    procustodibus

On other distributions, you may need to use the adduser command, whose options vary on different operating systems (and you may need to create a group separately).

Alpine

On Alpine, run the following addgroup and adduser commands:

$ doas addgroup -S procustodibus
$ doas adduser -G procustodibus -h /srv/procustodibus/api -S procustodibus

FreeBSD

On FreeBSD, run the following pw useradd command:

# pw useradd -n procustodibus -d /srv/procustodibus/api -s /usr/sbin/nologin -w no

Directory Permissions

Make sure you grant the daemon user access to the directory hierarchy from the extracted tarball:

$ sudo chmod o+rx /srv/procustodibus
$ sudo chown -R procustodibus:procustodibus /srv/procustodibus/api

And if you are using SELinux, you will also need to relabel the binaries in this directory hierarchy with the bin_t label to allow them to be executed:

$ sudo semanage fcontext -a -t bin_t '/srv/procustodibus/api/(bin|ops/run)/.*'
$ sudo restorecon -R /srv/procustodibus/api

Service Definition

Set up the API as service to run the /srv/procustodibus/api/ops/run/start.sh command as the procustodibus user with environment variables loaded from the /etc/default/procustodibus-api file.

Systemd

For Linux distributions using systemd, copy the /srv/procustodibus/api/ops/install/systemd.service service definition to the /etc/systemd/system/ directory as the procustodibus-api service:

$ sudo cp /srv/procustodibus/api/ops/install/systemd.service /etc/systemd/system/procustodibus-api.service

You may need to make the following adjustments to it:

  • If you named your Daemon User (and group) something other than procustodibus, change the service’s User and Group settings to match.

  • If you placed your Environment Variables somewhere other than /etc/default/procustodibus-api, change the service’s EnvironmentFile to match.

  • If you moved the tarball’s api/ directory to somewhere other than /srv/procustodibus/api/, adjust the directory paths in the service’s ExecStart, ExecStop, WorkingDirectory, and ReadWritePaths settings.

After adjusting the service definition, enable it to start on boot:

$ sudo systemctl enable procustodibus-api
Created symlink /etc/systemd/system/default.target.wants/procustodibus-api.service → /etc/systemd/system/procustodibus-api.service.

OpenRC

For Linux distributions using OpenRC (such as Alpine), copy the /srv/procustodibus/api/ops/install/openrc.service service definition to the /etc/init.d/ directory as the procustodibus-api service:

$ doas cp /srv/procustodibus/api/ops/install/openrc.service /etc/init.d/procustodibus-api

You may need to make the following adjustments to it:

  • If you named your Daemon User something other than procustodibus, change the service’s command_user setting to match.

  • If you moved the tarball’s api/ directory to somewhere other than /srv/procustodibus/api/, adjust the service’s directory setting to match.

After adjusting the service definition, enable it to start on boot:

$ doas rc-update add procustodibus-api
 * service procustodibus-api added to runlevel default

FreeBSD

For FreeBSD, copy the /srv/procustodibus/api/ops/install/freebsd.service service definition to the /etc/rc.d/ directory as the procustodibus-api service:

# cp /srv/procustodibus/api/ops/install/freebsd.service /etc/rc.d/procustodibus-api

You may need to make the following adjustments to it:

  • If you named your Daemon User something other than procustodibus, change the service’s user setting to match.

  • If you placed your Environment Variables somewhere other than /etc/defaults/procustodibus-api, change the service’s procustodibus_api_env_file to match.

  • If you moved the tarball’s api/ directory to somewhere other than /srv/procustodibus/api/, adjust the directory paths in the service’s program and procustodibus_api_chdir settings.

After adjusting the service definition, enable it to start on boot:

# service procustodibus-api enable
procustodibus_api enabled in /etc/rc.conf

Database

To install the database natively, install it with your package manager’s PostgreSQL package:

  • On Arch, the postqresql package.

  • On Alpine, the postqresql package.

  • On Debian and derivatives (such as Ubuntu), the postqresql package.

  • On Fedora and derivatives (such as RHEL), the postqresql-server package.

  • On FreeBSD, the postqresql*-server package (where * is the PostgreSQL version).

  • On openSUSE, the postqresql-server package.

Pro Custodibus requires PostgreSQL version 13 or newer.

OS Setup

On some distributions, such as Debian (and derivatives), once you install the PostgreSQL package, the server is usable out-of-the-box. However, on other distributions, you have to run a set-up script first.

Alpine

On Alpine, start the postgresql service, which will trigger the initdb script on first run:

$ doas rc-service postgresql start
 * Caching service dependencies ...                                       [ ok ]
 * Creating a new PostgreSQL 15 database cluster ...
The files belonging to this database system will be owned by user "postgres".
This user must also own the server process.

...

initdb: warning: enabling "trust" authentication for local connections
initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.

Success.                                                                  [ ok ]
 * /run/postgresql: creating directory
 * /run/postgresql: correcting owner
 * Starting PostgreSQL 15 ...

After that succeeds, enable the service to start on boot:

$ doas rc-update add postgresql
 * service postgresql added to runlevel default

Arch

On Arch, run the following command:

$ sudo -iu postgres initdb -D /var/lib/postgres/data

Then start the postgresql service (and enable it to start on boot):

$ sudo systemctl enable --now postgresql

See the PostgreSQL page on the Arch wiki for details.

Fedora

On Fedora (and derivatives), first run the postgresql-setup command:

$ sudo postgresql-setup --initdb --unit postgresql
 * Initializing database in '/var/lib/pgsql/data'
 * Initialized, logs are in /var/lib/pgsql/initdb_postgresql.log

Then start the postgresql service (and enable it to start on boot):

$ sudo systemctl enable --now postgresql
Created symlink /etc/systemd/system/multi-user.target.wants/postgresql.service → /usr/lib/systemd/system/postgresql.service.

FreeBSD

On FreeBSD, enable the postgresql service:

# service postgresql enable
postgresql enabled in /etc/rc.conf

Then run the initdb script:

# service postgresql initdb
The files belonging to this database system will be owned by user "postgres".
This user must also own the server process.

...

initdb: warning: enabling "trust" authentication for local connections
initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.

Success. You can now start the database server using:

    /usr/local/bin/pg_ctl -D /var/db/postgres/data15 -l logfile start

Then start the service:

# service postgresql start
2023-08-15 18:20:39.300 UTC [9585] LOG:  ending log output to stderr
2023-08-15 18:20:39.300 UTC [9585] HINT:  Future log output will go to log destination "syslog".

openSUSE

On openSUSE, run the following command:

$ sudo -iu postgres initdb -D /var/lib/pgsql/data
The files belonging to this database system will be owned by user "postgres".
This user must also own the server process.

...

initdb: warning: enabling "trust" authentication for local connections
initdb: hint: You can change this by editing pg_hba.conf or using the option -A, or --auth-local and --auth-host, the next time you run initdb.

Success. You can now start the database server using:

    pg_ctl -D /var/lib/pgsql/data -l logfile start

Then start the postgresql service (and enable it to start on boot):

$ sudo systemctl enable --now postgresql
Created symlink /etc/systemd/system/multi-user.target.wants/postgresql.service → /usr/lib/systemd/system/postgresql.service.

Init SQL

Once the PostgreSQL service is up and running, download and run the Pro Custodibus init.sql script. This script will create a new user with a username of procustodibus_user and password of procustodibus_password; and create a new database with a name of procustodibus_db, owned by the new user.

You may alter the username, password, and database name before running the init.sql script (in particular, we recommend you change the password to an unguessable value). If you do, change the API server’s DB_USERNAME, DB_PASSWORD, and DB_DATABASE environment variables to match.

Then run the init.sql script:

$ wget https://git.sr.ht/~arx10/procustodibus-api/blob/main/ops/db/init.sql
$ vi init.sql
$ sudo -iu postgres psql < init.sql
CREATE ROLE
CREATE DATABASE

Client Authentication

On most systems you will have to modify the pg_hba.conf file to allow password authentication from the IP address used by the API server. This file is located in different places on different distributions:

  • On Alpine, the /etc/postgresql*/pg_hba.conf file (where * is the major version number for PostgreSQL, such as 14).

  • On Arch, the /var/lib/postgres/data/pg_hba.conf file.

  • On Debian (and derivatives), the /etc/postgresql/*/main/pg_hba.conf file (where * is the major version number for PostgreSQL, such as 14):

  • On Fedora (and derivatives), the /var/lib/pgsql/data/pg_hba.conf file.

  • On FreeBSD, the /var/db/postgres/data*/pg_hba.conf file (where * is the major version number for PostgreSQL, such as 14).

  • On openSUSE, the /var/lib/pgsql/data/pg_hba.conf file.

Locate this file and edit it. Before any of the other host entries, insert the following entry if the database is on the same server as the API:

# TYPE  DATABASE          USER                ADDRESS   METHOD
host    procustodibus_db  procustodibus_user  samehost  scram-sha-256

If the API is on a different server, replace samehost with the IP address of the API server (for example, 10.1.2.3):

# TYPE  DATABASE          USER                ADDRESS   METHOD
host    procustodibus_db  procustodibus_user  10.1.2.3  scram-sha-256

If you customized the Pro Custodibus database name or username, use your customized names:

# TYPE  DATABASE    USER          ADDRESS   METHOD
host    my_db_name  my_user_name  samehost  scram-sha-256

If multiple entries from the pg_hba.conf file match a connection, the first entry is used (and the others are ignored). Therefore, make sure you insert the Pro Custodibus entry before any other entries that may match connections from the API server.

If PostgreSQL is configured with password_encryption = md5 in its postgresql.conf file, use md5 instead of scram-sha-256 in its pg_hba.conf file.

Reload PostreSQL’s configuration after modifying the pg_hba.conf file:

$ sudo systemctl reload postgresql

App Web UI

To install the app UI natively, download the latest version from the Download page (or build it yourself). Make sure you download (or build) the app UI edition that matches the edition of the API you installed above.

On your webserver, extract the tarball, and move its dist/ directory to a convenient location from which to serve its content (like the /srv/procustodibus/app/ directory):

$ tar xf procustodibus-app-ce-1.2.3.tar.bz2
$ sudo mkdir -p /srv/procustodibus
$ sudo mv dist /srv/procustodibus/app

Directory Permissions

Make sure you grant the user that runs your webserver permission to access this directory hierarchy. There aren’t any secrets in it, so you can safely grant everybody read access to it:

$ sudo chmod o+rx /srv/procustodibus
$ sudo chmod -R o+rX /srv/procustodibus/app

If you are using SELinux, you may also need to relabel this directory hierarchy with the httpd_sys_content_t label to allow your webserver to access it:

$ sudo semanage fcontext -a -t httpd_sys_content_t '/srv/procustodibus/app(/.*)?'
$ sudo restorecon -R /srv/procustodibus/app

Environment Variables

The app UI configuration settings and stored in the root index.html file. Edit this file, and adjust the configuration defaults as necessary:

    <script>window.ENV = {
      AGENT_SIGNING_KEYS: "98EE78FAB506BEABC0DADE15EFC1AE969DD8159F",
      AGENT_VERSION: "1.2.3",
      API_URL: "https://procustodibus.example.com/api",
      DOC_URL: "https://docs.procustodibus.com",
      DOWNLOAD_URL: "https://ad.custodib.us",
      SITE: "prod",
      SUPPORT_EMAIL: "support@example.com",
      SUPPORT_PHONE: "",
      TITLE: "Pro Custodibus",
      WWW_URL: "https://www.procustodibus.com",
    }</script>

The one setting you must configure is API_URL: change it to the canonical URL of your API server. See the app’s env.example file for a description of each setting.

You can use the app-env.sh script from the app’s Git repo to update the index.html file with the settings from an environment variables file. For example, if you run the following commands to download this script:

$ wget https://git.sr.ht/~arx10/procustodibus-app/blob/main/ops/run/app-env.sh
$ chmod +x app-env.sh
$ sudo mv app-env.sh /usr/local/bin/procustodibus-app-env.sh

And then run the following commands to download the environment variables example file:

$ wget https://git.sr.ht/~arx10/procustodibus-app/blob/main/env.example
$ sed -i -e 's/VITE_APP_//; s/=\(.*\)/="\1"/' env.example
$ sudo mv env.example /etc/default/procustodibus-app

You can then edit the /etc/default/procustodibus-app file so that it contains your preferred settings; and then run the following command to apply those settings to the app’s index.html file:

$ sudo sh -c 'set -a; . /etc/default/procustodibus-app; procustodibus-app-env.sh /srv/procustodibus/app'

Webserver Configuration

Configure your webserver to serve the /srv/procustodibus/app/ directory (or as whatever directory you copied dist above). In most cases, you’ll want to serve this directory as the root of a custom domain name (such as procustodibus.example.com), and with TLS.

General

The app UI is Single Page Application (SPA), consisting solely of static files. Nothing in its directory hierarchy requires executable permissions, directory listings, or anything other than basic GET requests.

Two things to note when configuring your webserver:

  1. The app’s root index.html should be configured as the fallback resource (or 404 error page) when the webserver cannot find a file matching the request URI.

  2. The files under the /assets/ directory (as well as the /workbox-* files) can be cached indefinitely (as they contain a hash of their content in their own filenames); other files generally should not be cached (as they may change from version to version).

Certbot

Follow the instructions from the Certbot website in order to acquire a TLS certificate for the domain name you want to use with Pro Custodibus (eg procustodibus.example.com); or acquire a TLS cert via your preferred mechanism.

Apache

To serve the app UI via Apache, use the example apache.conf file from the app’s Git repo as a template for the app’s Apache configuration. Make the following adjustments to it:

  • Replace procustodibus.example.com with the custom domain name that you will use for your on-premises Pro Custodibus app UI.

  • Update the /srv/procustodibus/app document root if you moved the dist/ directory to a different path above.

  • Update the /var/www/certbot rewrite rule if you’re using a different path; or remove it entirely if you’re not using the Certbot.

  • Adjust the ProxyPass and ProxyPassReverse directive to point to API server’s host and port; or remove the /api/ location if you’re not reverse-proxying the API server.

  • Adjust the SSLCertificateFile and SSLCertificateKeyFile directives to point to your actual TLS certificate chain and key files.

  • Adjust the ErrorLog and CustomLog directives if you’re not using the standard log-file locations.

    If the APACHE_LOG_DIR variable is not defined, you may wish to define it in Apache’s root config file:

    Define APACHE_LOG_DIR /var/log/httpd

You may also need to install or activate the following modules:

After adjusting this config file, move it to the webserver’s /etc/httpd/conf.d/ directory (or other directory as appropriate), and reload Apache’s configuration:

$ sudo mv apache.conf /etc/httpd/conf.d/procustodibus.conf
$ sudo systemctl reload httpd

On Debian and its derivatives (eg Ubuntu), Apache’s configuration directory is /etc/apache2 instead of /etc/httpd, and its service name is apache2 instead of httpd. On Debian, run the following commands:

$ sudo mv apache.conf /etc/apache2/sites-available/procustodibus.conf
$ sudo a2ensite procustodibus.conf
Enabling site procustodibus.
To activate the new configuration, you need to run:
  systemctl reload apache2
$ sudo systemctl reload apache2

NGINX

To serve the app UI via NGNIX, use the example nginx.conf file from the app’s Git repo as a template for the app’s NGINX configuration. Make the following adjustments to it:

  • Replace procustodibus.example.com with the custom domain name that you will use for your on-premises Pro Custodibus app UI.

  • Update the /srv/procustodibus/app document root if you moved the dist/ directory to a different path above.

  • Update the /var/www/certbot document root if you’re using a different path; or remove the /.well-known/acme-challenge/ location if you’re not using the Certbot.

  • Adjust the proxy_pass directive to point to API server’s host and port; or remove the /api/ location if you’re not reverse-proxying the API server.

  • Adjust the ssl_certificate and ssl_certificate_key directives to point to your actual TLS certificate chain and key files.

  • Download the Certbot’s recommended NGINX TLS settings and save it to /etc/nginx/ssl.conf; or remove the include directive for it.

  • Download Mozilla’s recommended DH parameters and save it to /etc/ssl/dhparams.conf; or remove the ssl_dhparam directive.

After adjusting this config file, move it to the webserver’s /etc/nginx/conf.d/ directory, and reload NGINX’s configuration:

$ sudo mv nginx.conf /etc/nginx/conf.d/procustodibus.conf
$ sudo systemctl reload nginx

If your are using SELinux on the machine running your webserver, and you want to reverse-proxy the API, you will have to run the following command on it to allow your webserver to initiate outgoing connections:

$ sudo setsebool -P httpd_can_network_connect true

Next Steps

Run the server components.