io7m | single-page | multi-page | epub | Stonesignal 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. Maven Central
- 2.4. OCI Images
  - 2.4.1. Quay.io
- 2.5. Database
  - 2.5.1. Overview
  - 2.5.2. Database Configuration
  - 2.5.3. Roles
    - 2.5.3.1. Overview
    - 2.5.3.2. Owner
    - 2.5.3.3. Worker
    - 2.5.3.4. Reader
    - 2.5.3.5. Device
- 2.6. Running The Server
  - 2.6.1. Running

## 2.1. Overview

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

### 2.1.2. Sources

- Maven Central
- Quay.io

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

## 2.2. PostgreSQL

1
The stonesignal server requires a PostgreSQL server. The stonesignal 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 stonesignal 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 stonesignal-distribution.zip.asc
    gpg: assuming signed data in 'stonesignal-distribution.zip.asc'
    gpg: Signature made Tue 28 Jun 2022 15:01:56 GMT
    gpg:                using RSA key 12BC 7CF4 BB72 BD17 F7F5  01EB 3A1B 34F8 9D7A D0FC
    gpg:                issuer "contact@io7m.com"
    gpg: using pgp trust model
    gpg: Good signature from "io7m.com (2025 github-ci-maven-rsa-key) <contact@io7m.com>" [unknown]

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

### 2.3.6. Extract

    $ unzip com.io7m.stonesignal.main-1.0.0-beta0001-distribution.zip
    $ export STONESIGNAL_HOME=$(realpath stonesignal)
    $ ./stonesignal/bin/stonesignal
    stonesignal: usage: stonesignal [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/stonesignal:1.0.0-beta0001
    $ podman run quay.io/io7mcom/stonesignal:1.0.0-beta0001
    stonesignal: usage: stonesignal [command] [arguments ...]
    ...

## 2.5. Database

## 2.5.1. Overview

1
The stonesignal package uses PostgreSQL for all persistent data.

## 2.5.2. Database Configuration

1
Create an owner role in PostgreSQL that will own the database objects:

### 2.5.2.2. Owner Role Creation

    postgres=# create role stonesignal_owner with login password 'a very strong password';

3
Create a new database owned by the owner role:

### 2.5.2.4. Database Creation

    postgres=# create database stonesignal with owner stonesignal_owner;

## 2.5.3. Roles

## 2.5.3.1. Overview

1
The stonesignal 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 stonesignal 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.5.3.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 stonesignal 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 stonesignal_owner to make it clear as to the purpose of the role. The stonesignal package will create the other roles it uses for normal operation automatically, and will manage their passwords based on the server configuration.
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.5.3.2.3. Example

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

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

## 2.5.3.4. Reader

1
The reader role is a role that is permitted read-only access to some of the database. Specifically, the role does not have access to columns containing secrets such as device keys. The role is therefore safe for use by external systems that want to connect to the database directly to do data analysis. The role is always named stonesignal_reader, and adminstrators are required to set a password for this role.

## 2.5.3.5. Device

1
The device role is a role that is permitted update access to some of the database. The role is always named stonesignal_device, and adminstrators are required to set a password for this role.

## 2.6. Running The Server

## 2.6.1. Running

1
The server can now be run with stonesignal server:

### 2.6.1.2. Run

    $ stonesignal server --configuration server.conf
    stonesignal: INFO: com.io7m.stonesignal.server.device_api_v1.StDeviceAPI: [localhost/<unresolved>:10000] Device API server started
    stonesignal: INFO: com.io7m.stonesignal.server.admin_api_v1.StAdminAPI: [localhost/<unresolved>:10001] Admin API server started
    stonesignal: INFO: com.io7m.stonesignal.server.data_api_v1.StDataAPI: [localhost/<unresolved>:10002] Data API server started

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

## Footnotes

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

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