Skip to content
komp.ac Docs

Server setup and API overview

The server is a single gRPC process that listens on [::1]:50051 by default. Everything — authentication, tables, search, accounting, backups — is one service exposing one API on one port.

Documented version: server v0.8.40.

Requirements

Section titled “Requirements”
  • Rust and Cargo;
  • PostgreSQL;
  • protoc (Protocol Buffers) and OpenSSL;
  • sqlx-cli for migrations;
  • the steel-decimal crate cloned as a sibling directory at ../steel-decimal.

With Nix, direnv allow (or nix develop) provides all dependencies.

Database setup

Section titled “Database setup”

Create the database user and database:

Terminal window
psql postgres -c "CREATE USER multi_psql_dev WITH PASSWORD '...';"
psql postgres -c "CREATE DATABASE multi_rust_dev OWNER multi_psql_dev;"
psql postgres -c "GRANT ALL PRIVILEGES ON DATABASE multi_rust_dev TO multi_psql_dev;"

Then configure the environment and run migrations:

Terminal window
cp .env_template .env
openssl rand -base64 32   # put the output into JWT_SECRET
sqlx migrate run

Environment variables

Section titled “Environment variables”
Variable Required Default Meaning
RUST_DB_USER yes — PostgreSQL user
RUST_DB_PASSWORD yes — PostgreSQL password
RUST_DB_HOST yes — PostgreSQL host
RUST_DB_PORT yes — PostgreSQL port
RUST_DB_NAME yes — PostgreSQL database name
JWT_SECRET yes — Secret used to sign access tokens
GRPC_LISTEN_ADDRESS no [::1]:50051 Address the gRPC server binds
PGBACKREST_BIN no pgbackrest pgBackRest binary path
PGBACKREST_CONFIG no — pgBackRest config path
PGBACKREST_STANZA no komp_ac pgBackRest stanza
DISABLE_ECB_IMPORTER no unset When set, the ECB importer does not start

Running the server

Section titled “Running the server”
Terminal window
cargo run --package server -- server

Other subcommands:

Command Purpose
server Run the gRPC server
sync-ecb Synchronize ECB reference rates up to the latest verifiable date
backfill-ecb Import the ECB reference-rate history

Boot sequence

Section titled “Boot sequence”

On startup the server:

  1. loads the JWT signing keys from JWT_SECRET;
  2. builds the authorization policy from the Rust base policy plus stored data grants;
  3. starts the search indexer task and the idempotency-record cleanup task;
  4. starts the web frontend and the ECB importer (unless disabled);
  5. serves every gRPC service, plus the reflection service, on the listen address.

The gRPC services

Section titled “The gRPC services”

All services except AuthService require an Authorization: Bearer token. AuthService stays open because registration and login are how a token is obtained; its administrative calls authenticate themselves.

Service Purpose
AuthService Registration, login, bootstrap claim, authorization snapshot, timezone, roles, grants, users
TableStructureService Read a table’s structure
TableDefinitionService Define tables, profiles, invoice templates, column aliases
TableValidationService Validation rules and sets
TablesDataService Row operations: insert, update, soft delete, read, count
TableScriptService Attach Steel scripts to tables
AccountingService Journals, accounts, periods, approval, transfers
BackupService pgBackRest operations and logical dumps
DocumentDataService Versioned rendered documents
EcbService ECB conversion previews and evidence
Searcher Full-text search
Search2 Live single-table filtering
AnalyticsService Permission-aware SQL analytics

The reflection service exposes the full service list to gRPC clients, which can discover the API without a static descriptor.

Continue

Section titled “Continue”