Build On-Premises

You will need to have a relatively recent version of Docker and Make to build the API server and app UI from source. You’ll also need to add your builder user to the docker group.

From a Working Copy

Before building, commit any changes you’ve made to the source code to a working branch in Git. We also recommend tagging the commit with a custom version number (such as 1.2.3-mybuild-456). The API server and app UI builds will include a build.json file with your HEAD commit hash and tag (which is displayed on the Version page of the app UI); and their Docker builds will incorporate the Git tag in their container image tag.

API

The API binaries must be built on a machine with the same CPU architecture (ie x86 vs ARM) and versions of core libraries (like libc, openssl, odbc, etc) as the API server will be run.

Building a production release from scratch usually will take at least 10 minutes (and possibly more than an hour, depending on the available CPU on the build machine and the target OS version).

On the build machine, download the latest source code:

$ git clone https://git.sr.ht/~arx10/procustodibus-api
$ cd procustodibus-api

Build in a Container

To build the API binaries in a Docker container targeting a specific OS (Operating System) version, find the OS version in the build/dist/ directory:

$ ls -1 build/dist
fedora-38.dockerfile
fedora-38.dockerfile.dockerignore
ubuntu-22.04.dockerfile
ubuntu-22.04.dockerfile.dockerignore
If you do not find an exact match to the OS version under which you want to run Pro Custodibus, you’ll have to create a new Dockerfile for it. Use one of the existing Dockerfiles as a template, and save your new Dockerfile in the same build/dist directory.

Then run the following command from the root of the procustodibus-api/ directory, specifying the name of the OS version:

$ make dist OS=fedora-38
This requires Docker’s BuildKit.

To build the Enterprise Edition (EE), add the EDITION=ee option to the command:

$ make dist OS=fedora-38 EDITION=ee
The distribution and use of any and all EE code, including when in object code form, is governed by the EE EULA.

If the machine on which you want to run Pro Custodibus has a different CPU architecture than the build machine, use the build/dist.sh script directly with the ARCH option to specify the target architecture (either x86_64 or aarch64):

$ ARCH=aarch64 build/dist.sh fedora-38
This requires Docker’s buildx plugin. Also note that building for a different CPU architecture is an order-of-magnitude slower than building for the native CPU architecture.

The build will produce a tarball located in the _build/dist/ directory within your procustodibus-api/ directory tree:

$ ls _build/dist/
procustodibus-api-ce-1.2.3-Linux-x86_64-fedora-38.tar.bz2

Follow the API server’s installation instructions to install this tarball in place of one downloaded from the official download site.

Build Natively

To build outside of a container, you will need to perform a few set-up tasks on the build machine specific to the OS version on which you’re building. Follow the pattern shown by the Dockerfiles from the build/dist directory to set up the build prerequisites:

  1. Ensure the machine is set up with the en_US.UTF-8 locale.

  2. Install the latest version of Erlang/OTP.

  3. Install the latest version of Elixir.

    The Erlang and Elixir packages available in your distribution’s package manager may be too old to work with the latest version of Pro Custodibus.

  4. Install the build dependencies for the API (be sure to also install the header files if installing via package manager):

  5. Install the other tools used by the build scripts:

With these prerequisites fulfilled, you can run the native build script from the root of the procustodibus-api/ directory:

$ make dist.native

If building in a VM with a different architecture than the host machine, run this command with Erlang’s +JMsingle option:

$ ERL_FLAGS="+JMsingle true" make dist.native

To build the Enterprise Edition (EE), add the EDITION=ee option to the command:

$ make dist.native EDITION=ee
The distribution and use of any and all EE code, including when in object code form, is governed by the EE EULA.

This will produce a tarball located in the _build/dist/ directory within your procustodibus-api/ directory tree:

$ ls _build/dist/
procustodibus-api-ce-1.2.3-Linux-aarch64-ubuntu-23.04.tar.bz2

Follow the API server’s installation instructions to install this tarball in place of one downloaded from the official download site.

API Docker

To build the API container image, run the following commands:

$ git clone https://git.sr.ht/~arx10/procustodibus-api
$ cd procustodibus-api
$ make docker

To build the Enterprise Edition (EE), add the EDITION=ee option to the make docker command:

$ make docker EDITION=ee
The distribution and use of any and all EE code, including when in object code form, is governed by the EE EULA.

This will produce an image with a tag like procustodibus/api-ce:1.2.3:

$ docker image ls procustodibus/api-ce
REPOSITORY             TAG                    IMAGE ID       CREATED          SIZE
procustodibus/api-ce   1.2.3                  f5c54c5ee5a9   18 seconds ago   317MB
procustodibus/api-ce   1.2.3-i230801-012401   f5c54c5ee5a9   18 seconds ago   317MB

Export this image (or push it to a private repository) and copy it to the host on which you want to run Pro Custodibus:

$ docker save procustodibus/api-ce:1.2.3 | bzip2 > procustodibus-api-image.tar.bz2
$ scp procustodibus-api-image.tar.bz2 procustodibus.example.com:.

Then import it (or pull it from the private repository) on that host:

$ docker import procustodibus-api-image.tar.bz2

Run this image using the exact same tag as you exported it with (procustodibus/api-ce:1.2.3 in this example). See the full Docker installation instructions for details.

App

To build the static app UI files, run the following commands:

$ git clone https://git.sr.ht/~arx10/procustodibus-app
$ cd procustodibus-app
$ make init
$ make rel

To build the Enterprise Edition (EE), add the EDITION=ee option to the command:

$ rel EDITION=ee

This will produce a tarball located at out/app.tar.bz2 within your procustodibus-app/ directory tree. Follow the app UI’s installation instructions to install this tarball in place of one downloaded from the official download site.

App Docker

To build the app container image, run the following commands:

$ git clone https://git.sr.ht/~arx10/procustodibus-app
$ cd procustodibus-app
$ make init
$ make docker

To build the Enterprise Edition (EE), add the EDITION=ee option to the make docker command:

$ make docker EDITION=ee

This will produce an image with a tag like procustodibus/app-ce:1.2.3:

$ docker image ls procustodibus/app-ce
REPOSITORY             TAG                    IMAGE ID       CREATED          SIZE
procustodibus/app-ce   1.2.3                  f33c2da4df51   21 seconds ago   121MB
procustodibus/app-ce   1.2.3-i230801-013821   f33c2da4df51   21 seconds ago   121MB

Export this image (or push it to a private repository) and copy it to the host on which you want to run Pro Custodibus:

$ docker save procustodibus/app-ce:1.2.3 | bzip2 > procustodibus-app-image.tar.bz2
$ scp procustodibus-app-image.tar.bz2 procustodibus.example.com:.

Then import it (or pull it from the private repository) on that host:

$ docker import procustodibus-app-image.tar.bz2

Run this image using the exact same tag as you exported it with (procustodibus/app-ce:1.2.3 in this example). See the full Docker installation instructions for details.

Agent

To build a package of the agent so it can be installed natively on another host, run the following commands:

$ git clone https://git.sr.ht/~arx10/procustodibus-agent
$ cd procustodibus-agent
$ git archive --output dist/agent.tar.gz --prefix agent/ HEAD
If you have made changes to this repository, this command will package only the changes you have committed — it will ignore anything you have not yet committed.

This will produce a tarball located at dist/agent.tar.gz within your procustodibus-agent/ directory tree. Follow the agent’s installation instructions to install this tarball in place of one downloaded from the official download site.

Agent Docker

To build the agent container image, run the following commands:

$ git clone https://git.sr.ht/~arx10/procustodibus-agent
$ cd procustodibus-agent
$ docker/agent.sh

This will produce an image with a tag like procustodibus/agent:1.2.3:

$ docker image ls procustodibus/agent
REPOSITORY            TAG                    IMAGE ID       CREATED          SIZE
procustodibus/agent   1.2.3                  f9d0a3980a7c   51 seconds ago   314MB
procustodibus/agent   1.2.3-i230801-014722   f9d0a3980a7c   51 seconds ago   314MB

Export this image (or push it to a private repository) and copy it to the host on which you want to run Pro Custodibus:

$ docker save procustodibus/agent:1.2.3 | bzip2 > procustodibus-agent-image.tar.bz2
$ scp procustodibus-agent-image.tar.bz2 wireguard.example.com:.

Then import it (or pull it from the private repository) on that host:

$ docker import procustodibus-agent-image.tar.bz2

Run this image using the exact same tag as you exported it with (procustodibus/agent:1.2.3 in this example). See the full agent container instructions for details.