Overview

Documentation of StrichRListe.

For Admins

Deployment and configuration are documented in deployment and config respectively.

For Developers

The development workflow and specifics are documented at development.

Deployment

Currently the only officially supported deployment method is through a container.

Docker/Podman

Releases of StrichRListe are available as a OCI image for linux/amd64 and linux/arm64.

Available registries:

Supported tags:

latest: latest tagged release
{major}: latest tagged minor release within this major version
{major}.{minor}: latest tagged patch release in this minor version
{major}.{minor}.{patch}: exact version

The config and database in the containers is located in /strichrliste/data.

Compose

Compose example:

services:
  strichrliste:
    image: fregrem/strichrliste:latest
    ports:
      - "3000:3000"
    restart: always
    volumes:
      - "./data:/strichrliste/data"

Podman Quadlet

Quadlet Example:

[Unit]
Description=Reimplementation of strichliste with some extras
After=network-online.target

[Container]
Image=docker.io/fregrem/strichrliste:latest
AutoUpdate=registry
PublishPort=3000:3000
Volume=%h/strichrliste:/strichrliste/data

[Service]
Restart=on-failure

[Install]
WantedBy=default.target

Config

Configuration is possible through both environment variables and a config file. Environment variables take precedence over the config file.

All available options are shown and described in the example config file.

Environment

Config variables start with STRICHRLISTE_. Nested options are separated with double underscores (__).

# Port to bind to.
STRICHRLISTE_PORT=3000

# Set the upper balance limit for accounts in cents.
STRICHRLISTE_BOUNDARIES__ACCOUNT_UPPER=20000

File

The config file is read from data/config.toml.

In the container it is located at /strichrliste/data/config.toml

Example

# Address to bind to.
url = "0.0.0.0"

# Port to bind to.
port = 3000

# Directory the frontend files are located in.
frontend_dir = "frontend"

# Set the timeout a transaction can be undone in seconds. If `false`, users are always allowed to
# undo. To disable undo, set to `0`.
undo_timeout = 600

# Set the duration a user will remain as active after their last interaction (transaction/edit).
# If `false`, users are always active.
user_timeout = 86400

# Set the used currency for the instance. Mainly used for frontend.
currency = "euro"


# Set boundaries for accounts, transactions and the inventory.
[boundaries]
# Set the upper balance limit for accounts in cents. `false` is equal to the upper i32 limit.
account_upper = 20000

# Set the lower balance limit for accounts in cents. `false` is equal to the lower i32 limit.
account_lower = -10000

# Set the (positive/negative) monetary transaction limit. `false` is equal to the i32 limit.
transaction = 10000

# Set the maximum allowed stock. `false` is equal to the upper i32 limit.
#
# If both this and 'inventory_lower' are `false`, all articles are reported as infinitely available
# through faking an override.
inventory_upper = 1000

# Set the minimum allowed stock. `false` is equal to the lower i32 limit.
#
# If both this and 'inventory_upper' are `false`, all articles are reported as infinitely available
# through faking an override.
inventory_lower = 0


# Set options for the backend storage.
[storage]
# Set used storage method.
# Possible values: sqlite
driver = "sqlite"

# If needed, set file location for the storage.
file = "data/database.db"


# Set which features are enabled for the instance.
[capabilities]
# Toggles the builtin frontend. Frontend related information will still be available through the
# api.
frontend = true

# Toggles the article system. Also disables `compensations` if disabled.
articles = true

# Allows to rebalance articles without money transfer.
# `articles` has to be enabled for the feature to work.
compensations = true

# Toggles the inventory system.
inventory = true

# Toggles the ability to optionally set per article inventory boundaries.
inventory_override = true

# Toggles the possibility to set a custom price when filling up articles.
custom_purchase_price = true

# Toggles the possibility for users to directly send money between them.
user_transactions = true


# Sets default options for the frontend.
# Frontend options are passed one to one to the frontend and aren't used by the backend.
[frontend]
# Should the article section on a users page be automatically opened.
auto_open_articles = true

# Values that should be set in the deposit section on a users page.
deposit = [
    100,
    200,
    500,
    1000,
    2000,
]

# Values that should be set in the dispense section on a users page.
dispense = [
    100,
    200,
    500,
    1000,
    2000,
]

# Percentage of random sounds being used, from 0 to 1.
random_sounds = 0.02

# Info shown on cash payment site
cash_info = "register cash payments"

API

StrichRListe API (0.11.0)

^{AGPL-3.0-or-later}

StrichRListe API to access all functions of the server Base path of all api functionality is located at /api

Paths

`GET /`

Info

Response at the root level of the api

`GET /article`

Get all articles

Responses

200: Article (application/json)
500: string (text/plain)

`POST /article`

Create article

Responses

201: Article (application/json)
500: string (text/plain)

`GET /article/label/{label}`

Get articles by label

Responses

200: array of Article (application/json)
500: string (text/plain)

`GET /article/search/{term}`

Search article

Responses

200: array of Article (application/json)
500: string (text/plain)

`GET /article/{article}/compensation`

Get all compensations for a specific article

Responses

200: Compensation (application/json)
404: string (text/plain)
500: string (text/plain)

`POST /article/{article}/compensation`

Compensate Inventory

Responses

201: Compensation (application/json)
400: string (text/plain)
404: string (text/plain)
500: string (text/plain)

`GET /article/{id}`

Get single article

Responses

200: Article (application/json)
404: string (text/plain)
500: string (text/plain)

`POST /article/{id}`

Update article

Responses

200: Article (application/json)
404: string (text/plain)
500: string (text/plain)

`DELETE /article/{id}`

Deactivate article

Responses

200: Article (application/json)
404: string (text/plain)
500: string (text/plain)

`GET /article/{id}/transaction`

Get all article transactions

Responses

200: array of Transaction (application/json)
404: string (text/plain)
500: string (text/plain)

`GET /compensation`

Get all compensations

Responses

200: array of Compensation (application/json)
500: string (text/plain)

`GET /compensation/{id}`

Get compensation

Request a specific compensation by id.

Responses

200: Compensation (application/json)
404: string (text/plain)
500: string (text/plain)

`GET /settings`

Settings

Get all settings that can be used for the frontend.

`GET /transaction`

Get all transactions

Responses

200: array of Transaction (application/json)
500: string (text/plain)

`POST /transaction`

Create transaction

Responses

201: Transaction (application/json)
500: string (text/plain)

`GET /transaction/{id}`

Get single transaction

Responses

200: Transaction (application/json)
404: string (text/plain)
500: string (text/plain)

`DELETE /transaction/{id}`

Undo transaction

Responses

200: Transaction (application/json)
404: string (text/plain)
500: string (text/plain)

`GET /user`

Get all users

Responses

200: array of User (application/json)
500: string (text/plain)

`POST /user`

Create user

Responses

201: array of User (application/json)
500: string (text/plain)

`GET /user/search/{term}`

Search users

Responses

200: User (application/json)
500: string (text/plain)

`GET /user/{id}`

Get single user

Responses

200: User (application/json)
404: string (text/plain)
500: string (text/plain)

`POST /user/{id}`

Update user

Responses

200: User (application/json)
404: string (text/plain)
500: string (text/plain)

`DELETE /user/{id}`

Delete user

“Deletes” the user. User is set to deleted, but actual data is kept.

Responses

200: User (application/json)
404: string (text/plain)
500: string (text/plain)

`GET /user/{id}/transaction`

Get all user transactions

Responses

200: array of Transaction (application/json)
404: string (text/plain)
500: string (text/plain)

Components

Article

Everything about an article in storage and while working with it.

property	type	description	default
active	boolean	Is the article active.	-
barcodes	string[]	Optional barcode mainly to be used in barmode in the frontend.	-
created	integer	Timestamp of the article creation	-
id	integer	Unique id, gets allocated by the storage backend.	-
inventory	integer	Stock of the article	-
inventory_override	Inventory	Inventory boundary override for this article.	-
labels	string[]	Optional labels for sorting in the frontend.	-
name	string	Article name, only one article with the same name can be active at the same time.	-
prices	Price[]	Versioned price information for the article	-
usage_count	integer	How often has the article been bought.	-

Boundaries

Describes all configured limits for actions and objects.

property	type	description	default
account_lower	integer	Set the lower balance limit for accounts in cents. No value equals i32::MIN.	-10000
account_upper	integer	Set the upper balance limit for accounts in cents. No value equals i32::MAX.	20000
inventory	Inventory	Sets the type of override for inventory boundaries	-
transaction	integer	Set the (positive/negative) monetary transaction limit. None equals i32::MAX/i32::MIN.	10000

Capabilities

Describes all toggleable features for the instance.

property	type	description	default
articles	boolean	Toggles the article system. Also disables `compensations` if disabled.	true
compensations	boolean	Allows to rebalance articles without money transfer. `articles` has to be enabled for the feature to work.	true
custom_purchase_price	boolean	Toggles the possibility to set a custom price when filling up articles.	true
frontend	boolean	Toggles the builtin frontend. Frontend related information will still be available through the api.	true
inventory	boolean	Toggles the inventory system.	true
inventory_override	boolean	Toggles the ability to optionally set per article inventory boundaries.	true
user_transactions	boolean	Toggles the possibility for users to directly send money between them.	true

Compensation

External representation of a compensation. Compensations are used to allow changing the inventory of an Article without affecting a user.

property	type	description	default
amount	integer	Amount of articles that are compensated	-
article	integer	Article the compensation applies to	-
created	integer	Timestamp of the compensations creation	-
id	integer	Unique id	-
reason	CompensationReason	Reason the compensation has to be done	-

CompensationReason

Reason the compensation has to be done

bar: Bar transaction used to pay article

shrinkage: Compensate for missing articles noticed during inventory taking

enlargement: An article is bought without a user taking credit

buy: An article is bought without a user taking credit (e.g. cash payments)

error: Compensation for error in prior compensation

string “bar”|“shrinkage”|“enlargement”|“buy”|“error”

CreateArticle

Representing needed values to crate/update a new Article. When updating, all values have to be filled out with their new values, even when not changing them.

property	type	description	default
active	boolean		-
barcodes	string[]	Optional barcode mainly to be used in barmode in the frontend.	-
cost	integer	Cost of the article in cents.	-
inventory_override	Inventory	Inventory boundary override for this article.	-
labels	string[]	Optional labels to tag an article	-
name	string	Article name, only one article with the same name can be active at the same time.	-
purchase_price	integer	The amount of money a user receives when filling up the article. If unset, defaults to cost. Can be overridden by the user if `custom_purchase_price` in Capabilities is `true`.	-

CreateCompensation

Representing values needed to create a new Compensation.

property	type	description	default
amount	integer	Amount of articles that are compensated	-
reason	CompensationReason	Reason the compensation has to be done	-

CreateTransaction

Representing the possible information for creating a new Transaction.

property	type	description	default
amount	integer	If `article` given functions as article amount, if not as cents. Negative article amount means filling up the article.	-
article	string	Optional article, if given changes how the `amount` works.	-
comment	string	Optional comment to the transaction. Can be shown in frontend.	-
purchase_override	PurchaseOverride	User override for `purchase_price` of an Article. Only allowed if `custom_purchase_price` in Capabilities is `true` in the Settings.	-
recipient	string	Set if users send money between them.	-
user	string	Main user affected by the transaction.	-

CreateUser

Struct representing the needed possible values for a Users creation. All other values are calculated/generated. When updating all values have to be filled out.

property	type	description	default
email	string	Optional email of the user.	-
name	string	Username	-

Currency

Available currencies, used for the frontend.

string “euro”

Frontend

Config usable for a frontend

property	type	description	default
auto_open_articles	boolean	Should the article section on a users page be automatically opened.	true
cash_info	string	Info shown on cash payment site	register cash payments
deposit	integer[]	Values that should be set in the deposit section on a users page.	[100, 200, 500, 1000, 2000]
dispense	integer[]	Values that should be set in the dispense section on a users page.	[100, 200, 500, 1000, 2000]
random_sounds	number	Percentage of the random sounds being used, from 0 to 1.	0.019999999552965164

Inventory

Sets the type of override for inventory boundaries

One of:

string “infinite” or:

property	type	description	default
bound	InventoryBound	Custom override. If a value isn’t set, it counts as i32::MAX/i32::MIN.	-

InventoryBound

Upper and lower bounds for bound in Inventory.

property	type	description	default
lower	integer	Lower inventory limit, unset equals to i32::MIN.	-
upper	integer	Upper inventory limit, unset equals to i32::MAX.	-

Price

Versioned price information for Articles

property	type	description	default
cost	integer	Cost of the article	-
created	integer	Timestamp of the creation of this price version	-
purchase_price	integer	The amount of money a user receives when filling up the article. If unset, defaults to cost. Can be overridden by the user if `custom_purchase_price` in the Capabilities is `true`.	-
version	integer	Version of the Price information	-

PurchaseOverride

Struct used for overriding the set purchase price of an article when filling.

property	type	description	default
unit	integer	Unit of the override, as in amount of the product costing `value`.	-
value	integer	Value of the override	-

Settings

Representing the backend config with the necessary info for a frontend or user

property	type	description	default
boundaries	Boundaries	Boundaries for accounts, transactions and the inventory.	-
capabilities	Capabilities	Which features are enabled for the instance.	-
currency	Currency	Used Currency for the instance. Mainly used for frontend.	euro
frontend	Frontend	Default options for the frontend. Frontend options are passed one to one to the frontend and are otherwise ignored by the backend.	-
undo_timeout	integer	Set the timeout a transaction can be undone in seconds. If no value is set users are always allowed to undo. If set to `0`, undo is disabled.	600
user_timeout	integer	Time a user will be set as active after their last interaction (transaction/edit).	86000

Transaction

Struct representing everything about a single transaction.

property	type	description	default
amount	integer	If `article` given functions as article amount, if not as cents. Negative article amount means filling up the article.	-
article	integer	Optional article, if given changes how the `amount` works. Requires `price_version` to be set	-
comment	string	Optional comment to the transaction. Can be shown in frontend.	-
created	integer	Timestamp of the transactions creation	-
deleted	boolean	Has the transaction been undone.	-
id	integer	Unique id, gets allocated by the storage backend.	-
isdeletable	boolean	Shows if the transaction can be undone by a user.	-
price_version	integer	Version of the article price, has to be set if article is set.	-
purchase_override	PurchaseOverride	User override for `purchase_price` of an Article. Only allowed if `custom_purchase_price` in Capabilities is `true` in the Settings.	-
recipient	integer	Set if users send money between them.	-
user	integer	Main user affected by the transaction.	-

User

Everything about an user in storage and while working with it.

property	type	description	default
active	boolean	Has the user been active over a certain time, set in the Settings with `user_timeout`.	-
balance	integer	Current balance of the user in cent	-
created	integer	Timestamp of the users creation	-
deleted	boolean	Has the user been deleted? Deletion is only reversible with direct database access.	-
email	string	Optional email of the user.	-
id	integer	Unique id, gets allocated by the storage backend.	-
modified	integer	Timestamp of the last modification to the user (transaction/edit)	-
name	string	Username	-

Development

General Workflow

The project is built and developed with make.

To build and start the server in debug mode run make dev. This builds everything necessessary and runs the backend binary. By default the server runs on 0.0.0.0:3000.
For frontend javascript development make js can be used while the server is running.