Samland Coin

This is the new official Samland Coin node. It is written in Node.js and TypeScript. This is a fork of Kirst.

Conventional Commits

Commit messages are written with Conventional Commits.

API Documentation

The documentation is generated with apiDoc. You can find a live copy of the API documentation here. Additional documentation for Samland Coin itself and libraries can be found here.

Docker Installation

The preferred method of installation is Docker. The Docker images are published on the GitHub Container Registry under ghcr.io/samland-Gov/samland-coin.

MySQL/MariaDB and Redis are required too. There are two options to connect to the databases. The easier way is to run MySQL and Redis on the host machine, and specify the DB_HOST=${DOCKER_GATEWAY} and REDIS_HOST=${DOCKER_GATEWAY} environment variables to Samland Coin. Alternatively, you can run MariaDB and Redis in Docker too (left as an exercise to the reader).

Example usage with Docker Compose:

version: "3.9"
services:
  krist:
    image: "ghcr.io/samland-gov/samland-coin:latest"
    environment:
      - DB_PASS=${DB_PASS}
      - PUBLIC_URL=krist.dev
      - PUBLIC_WS_URL=ws.krist.dev
      - DB_HOST=172.17.0.1
      - REDIS_HOST=172.17.0.1
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped

Manual Installation

Requirements

• Node.js v16
• MySQL or MariaDB
• Redis

Webserver Configuration

This Samland Coin node is supposed to be ran behind a serverside proxy. The file casket_example.casket includes a basic configuration for how to set up the proxy in Casket. The Node.js webserver is not designed to and should not be exposed to the public web. HTTPS is required.

Configuration

Basic configuration is now done via environment variables. You must supply the following environment variables:

Variable	Default	Description
DB_PASS	required	The password of the database user.
PUBLIC_URL	required	The FQDN of the Samland Coin server (e.g. krist.dev).

The following optional environment variables may also be specified:

Variable	Default	Description
DB_HOST	127.0.0.1	The hostname of the database.
DB_PORT	3306	The port of the database.
DB_NAME	krist	The name of the database.
DB_USER	krist	The username of the database user.
TEST_DB_NAME	test_krist	Required for testing. If NODE_ENV is test, the name of the database.
TEST_DB_USER	test_krist	Required for testing. If NODE_ENV is test, the username of the database user.
TEST_DB_PASS		Required for testing. If NODE_ENV is test, the password of the database user.
WEB_LISTEN	8080	The port that the webserver listens on.
PUBLIC_URL	localhost:8080	The public URL of the websocket gateway.
REDIS_HOST	127.0.0.1	The hostname of the redis server.
REDIS_PORT	6379	The port of the redis server.
REDIS_PREFIX	krist:	The prefix of the redis keys.
TEST_REDIS_PREFIX	test_krist:	Required for testing. If NODE_ENV is test (e.g. running Jest), the prefix of the redis keys.
NODE_ENV	development	Either development or production. If development, the Samland Coin server runs in debug mode.
FORCE_INSECURE	false	If true, force the websocket gateway to return ws:// URLs instead of wss://. Used for development only.
GITHUB_TOKEN		Any valid GitHub token (e.g. a PAT with no scopes) to obtain avatars for the homepage. Completely optional.
USE_PROMETHEUS	false	If true, enables Prometheus metrics on the /metrics endpoint.
PROMETHEUS_PASSWORD		If set, require HTTP basic authentication to access Prometheus metrics, with the username prometheus.

For convenience, you may specify environment variables in a .env file.

License

This project is released under GPL-3.0. More information can be found in the LICENSE file. Samland Coin is a fork of Kirst, which is also licensed under the GPL-3.0.