io7m | single-page | multi-page | epub | Cardant User Manual 1.0.0-beta0001
1. Introduction
Previous
Front Matter
Up
3. Configuration
Next

# 2. Installation

- 2.1. Overview
- 2.2. PostgreSQL
- 2.3. Idstore
- 2.4. Maven Central
- 2.5. OCI Images
  - 2.5.1. Quay.io
  - 2.5.2. Health Checks
- 2.6. Running The Server
  - 2.6.1. Initialization
  - 2.6.2. Running
- 2.7. Running The Shell
- 2.8. Database
  - 2.8.1. Overview
  - 2.8.2. Roles
    - 2.8.2.1. Overview
    - 2.8.2.2. Owner
    - 2.8.2.3. Worker
    - 2.8.2.4. Reader

## 2.1. Overview

1
The cardant server package is available from the following sources:

### 2.1.2. Sources

- Maven Central
- Quay.io

3
Regardless of the distribution method, the cardant package will contain a command named cardant that acts as the main entrypoint to all of the server and client functionality.

## 2.2. PostgreSQL

1
The cardant server requires a PostgreSQL server. The cardant server will create the required tables and database objects on first startup, given the name of a running PostgreSQL database, and a PostgreSQL role and password.

## 2.3. Idstore

1
The cardant server delegates all user and password management to idstore and therefore requires a running idstore server in order to work.

## 2.4. Maven Central

1
A distribution package can be found at Maven Central.
2
The cardant command requires that a Java 21+ compatible JVM be accessible via /usr/bin/env java.
3
Verify the integrity of the distribution zip file:

### 2.4.4. Verify

    $ gpg --verify com.io7m.cardant.main-1.0.0-beta0001-distribution.zip.asc
    gpg: assuming signed data in 'com.io7m.cardant.main-1.0.0-beta0001-distribution.zip.asc'
    gpg: Signature made Tue 28 Jun 2022 15:01:56 GMT
    gpg:                using RSA key 3CCE59428B30462D10459909C5607DA146E128B8
    gpg:                issuer "contact@io7m.com"
    gpg: using pgp trust model
    gpg: Good signature from "io7m.com (2022 maven-rsa-key) <contact@io7m.com>" [unknown]

5
Unzip the zip file, and set up the environment appropriately. The cardant command expects an environment variable named CARDANT_HOME to be defined that points to the installation directory.

### 2.4.6. Extract

    $ unzip com.io7m.cardant.main-1.0.0-beta0001-distribution.zip
    $ export CARDANT_HOME=$(realpath cardant)
    $ ./cardant/bin/cardant
    cardant: usage: cardant [command] [arguments ...]
    ...

## 2.5. OCI Images

## 2.5.1. Quay.io

1
OCI images are available from Quay.io for use with podman or docker.

### 2.5.1.2. Podman/Docker

    $ podman pull quay.io/io7mcom/cardant:1.0.0-beta0001
    $ podman run quay.io/io7mcom/cardant:1.0.0-beta0001
    cardant: usage: cardant [command] [arguments ...]
    ...

## 2.5.2. Health Checks

1
The OCI image includes a cardant-healthcheck command that makes a request to a health endpoint on the Inventory API server. The command expects the server to be accessible on localhost inside the container, and requires that the CARDANT_HEALTHCHECK_PORT environment variable be set to the port used by the Admin API. By default, the container sets CARDANT_HEALTHCHECK_PORT to 30000 and therefore there is no need to set this variable manually if the server is configured with the default settings.
2
This feature may only be available when running the image under docker due to limitations in the OCI image specification. The functionality of the health check service can be used directly via the Inventory API.

### 2.5.2.3. Health Example

    $ curl http://localhost:30000/health
    OK

## 2.6. Running The Server

## 2.6.1. Initialization

1
Given an appropriate configuration file in server.conf, it's necessary to tell cardant to configure the database and create an initial administrator. It's necessary to specify the idstore user ID of a user that will be considered to be the administrator of the cardant server:

### 2.6.1.2. Initialize

    $ cardant initialize \
      --admin-id '92f83bce-3973-4db8-8aaf-d401443a9772' \
      --admin-name 'someone' \
      --configuration server.conf

3
It is not critical that the username given match the user ID on the idstore server; the name will be updated automatically from that server when a user logs in.

## 2.6.2. Running

1
The server can now be run with cardant server:

### 2.6.2.2. Run

    $ cardant server --configuration server.conf
    info: [localhost/<unresolved>:30000] Inventory API server started

3
The server does not fork into the background and is designed to be run under process supervision.

## 2.7. Running The Shell

1
Run cardant shell [1] to start the shell:

### 2.7.2. Shell

    $ cardant shell
    [cardant]# version
    com.io7m.cardant 0.0.1-SNAPSHOT 20af71248a7784b0e5247eab4b1ebd28de284739

## 2.8. Database

## 2.8.1. Overview

1
The cardant package uses PostgreSQL for all persistent data.

## 2.8.2. Roles

## 2.8.2.1. Overview

1
The cardant package sets up multiple roles during database initialization. The configured roles have different degrees of privileges in order to allow, for example, external systems such as database metrics collectors read-only access to the database. All the defined rules are declared with the built-in PostgreSQL restrictions such as nocreatedb, nocreaterole, etc.
2
During the startup of the cardant server, the server will connect to the database using the owner role and do any database table initialization and/or schema upgrades necessary. The server will then disconnect from the database, and then connect to the database again using the worker role. The worker role is then used for normal operation of the server; if this role is somehow compromised, the role only has a limited ability to do any damage to the database, and cannot affect the audit log at all.

## 2.8.2.2. Owner

1
The owner role is the role that owns the database and is permitted to create tables, create new roles, etc. This role is used by the cardant package when creating the database during the first run of the server, and for upgrading database schemas later. Administrators are free to pick the name of the role, although it is recommended that the role be named cardant_install to make it clear as to the purpose of the role.
2
If the PostgreSQL OCI image is used, it is common to have the image create this role automatically using the POSTGRES_USER and POSTGRES_PASSWORD variables:

### 2.8.2.2.3. Example

    $ podman run \
      --name some-postgres \
      -e POSTGRES_USER=cardant_install \
      -e POSTGRES_PASSWORD=mysecretpassword \
      -d postgres

## 2.8.2.3. Worker

1
The worker role is the role that is used for normal database operation. It is a role that has read/write access to all tables (except for the audit log which is restricted to being append-only), although it is not granted the ability to create new tables, drop tables, or do other schema manipulation. The role is always named cardant, and adminstrators are required to set a password for this role.

## 2.8.2.4. Reader

1
The reader role is a role that is permitted read-only access to some of the database. It is effectively an optional role that can be used by various database metrics systems if required. If a password is not specified for the role in the server's configuration file, then logging in is not permitted at all.

## Footnotes

1 | If running under podman or docker, remember to use the -i and -t options. References to this footnote: 1

1. Introduction
Previous
Front Matter
Up
3. Configuration
Next
io7m | single-page | multi-page | epub | Cardant User Manual 1.0.0-beta0001