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

# 2. Installation

- 2.1. Overview
- 2.2. PostgreSQL
- 2.3. Maven Central
- 2.4. OCI Images
  - 2.4.1. Quay.io
  - 2.4.2. Health Checks
- 2.5. Running The Server
  - 2.5.1. Initialization
  - 2.5.2. Running
- 2.6. Running The Shell
- 2.7. Database
  - 2.7.1. Overview
  - 2.7.2. Roles
    - 2.7.2.1. Overview
    - 2.7.2.2. Owner
    - 2.7.2.3. Worker
    - 2.7.2.4. Reader
- 2.8. Mail

## 2.1. Overview

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

### 2.1.2. Sources

- Maven Central
- Quay.io

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

## 2.2. PostgreSQL

1
The idstore server requires a PostgreSQL server. The idstore 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. Maven Central

1
A distribution package can be found at Maven Central.
2
The idstore 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.3.4. Verify

    $ gpg --verify com.io7m.idstore.main-1.0.0-rc0006-distribution.zip.asc
    gpg: assuming signed data in 'com.io7m.idstore.main-1.0.0-rc0006-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 idstore command expects an environment variable named IDSTORE_HOME to be defined that points to the installation directory.

### 2.3.6. Extract

    $ unzip com.io7m.idstore.main-1.0.0-rc0006-distribution.zip
    $ export IDSTORE_HOME=$(realpath idstore)
    $ ./idstore/bin/idstore
    idstore: usage: idstore [command] [arguments ...]
    ...

## 2.4. OCI Images

## 2.4.1. Quay.io

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

### 2.4.1.2. Podman/Docker

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

## 2.4.2. Health Checks

1
The OCI image includes an idstore-healthcheck command that makes a request to a health endpoint on the Admin API server. The command expects the server to be accessible on localhost inside the container, and requires that the IDSTORE_HEALTHCHECK_PORT environment variable be set to the port used by the Admin API. By default, the container sets IDSTORE_HEALTHCHECK_PORT to 51000 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 Admin API or the User API.

### 2.4.2.3. Health Example

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

## 2.5. Running The Server

## 2.5.1. Initialization

1
Given an appropriate configuration file in server.conf, it's necessary to tell idstore to configure the database and create an initial administrator:

### 2.5.1.2. Initialize

    $ idstore initial-admin \
      --admin-id '92f83bce-3973-4db8-8aaf-d401443a9772' \
      --admin-email 'someone@example.com' \
      --admin-realname 'Someone Else' \
      --admin-username 'someone' \
      --admin-password 12345678 \
      --configuration server.conf

## 2.5.2. Running

1
The server can now be run with idstore server:

### 2.5.2.2. Run

    $ idstore server --configuration server.conf
    info: [localhost/<unresolved>:50000] User API server started
    info: [localhost/<unresolved>:50001] User view server started
    info: [localhost/<unresolved>:51000] Admin API server started

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

## 2.6. Running The Shell

1
Run idstore shell [1].

### 2.6.2. Shell

    $ idstore shell
    [idstore]# version
    com.io7m.idstore 0.0.15-SNAPSHOT 20af71248a7784b0e5247eab4b1ebd28de284739

## 2.7. Database

## 2.7.1. Overview

1
The idstore package uses PostgreSQL for all persistent data.

## 2.7.2. Roles

## 2.7.2.1. Overview

1
The idstore 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 idstore 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.7.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 idstore 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 idstore_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.7.2.2.3. Example

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

## 2.7.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 idstore, and adminstrators are required to set a password for this role.

## 2.7.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.

## 2.8. Mail

1
The idstore package requires a working SMTP MTA. The MTA is used to send email to users.

## 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 | Idstore User Manual 1.0.0-rc0006