The cardant server package is available from the following sources:
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.
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.
The
cardant server delegates all user and password management to
idstore and therefore requires
a running
idstore server in order to work.
The cardant command requires that a Java 21+ compatible JVM be accessible
via /usr/bin/env java.
Verify the integrity of the distribution zip file:
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.
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.
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.
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:
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.
The server can now be run with cardant server:
The server does not fork into the background and is designed to be run under process
supervision.
Run
cardant shell
to start the
shell:
The
cardant package uses
PostgreSQL for all persistent data.
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.
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.
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.
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:
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.
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.