@lfk/backend

Backend Server

Prerequisites

This project uses Bun as the runtime and package manager. Install Bun first:

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1 | iex"

Or visit bun.sh for other installation methods.

Quickstart 🐳

Use this to run the backend with a PostgreSQL db in Docker

1. Clone the repo or copy the docker-compose
2. Run in the folder that contains the docker-compose file: docker-compose up -d
3. Visit http://127.0.0.1:4010/api/docs to check if the server is running
4. You can now use the default admin user (demo:demo)

Dev Setup 🛠

Local dev setup utilizing SQLite3 as the database and NATS for caching.

1. Rename the .env.example file to .env (you can adjust app port and other settings if needed)
2. Start NATS (required for KV cache):

docker-compose up -d nats

3. Install dependencies:

bun install

4. Start the server:

bun run dev

Note: Bun cannot run TypeScript source files directly due to circular TypeORM dependencies. The dev script automatically builds and runs the compiled output. For hot-reload during development, you may need to rebuild manually after code changes.

Run Tests

# Run tests once (server has to be running)
bun test

# Run test in watch mode (reruns on change)
bun run test:watch

# Run test in CI mode (automatically starts the dev server)
bun run test:ci

Run Benchmarks

# Start the server first
bun run dev

# In another terminal:
bun run benchmark

Generate Docs

bun run docs

Other Commands

# Build for production
bun run build

# Start production server
bun start

# Seed database with test data
bun run seed

# Export OpenAPI spec
bun run openapi:export

# Generate license report
bun run licenses:export

# Generate changelog
bun run changelog:export

ENV Vars

You can provide them via .env file or docker env vars. You can use the test:ci:generate_env package script to generate an example env (uses placeholder data for test server and ignores the errors).

Name	Type	Default	Description
APP_PORT	Number	4010	The port the backend server listens on. Is optional.
DB_TYPE	String	N/A	The type of the db you want to use. Supported by TypeORM. Possible: sqlite, mysql, postgresql
DB_HOST	String	N/A	The db's host IP address/FQDN or file path for sqlite
DB_PORT	String	N/A	The db's port
DB_USER	String	N/A	The user for accessing the db
DB_PASSWORD	String	N/A	The user's password for accessing the db
DB_NAME	String	N/A	The db's name
NODE_ENV	String	dev	The app's env - influences debug info. When set to "test", mailing errors get ignored.
POSTALCODE_COUNTRYCODE	String/CountryCode	N/A	The country code used to validate address postal codes
PHONE_COUNTRYCODE	String/CountryCode	null (international)	The country code used to validate phone numbers
SEED_TEST_DATA	Boolean	false	If you want the app to seed example data, set this to true
STATION_TOKEN_SECRET	String	N/A	Secret key for HMAC-SHA256 station token generation (min 32 chars). Required.
NATS_URL	String(URL)	nats://localhost:4222	NATS server connection URL for KV cache
NATS_PREWARM	Boolean	false	Preload all runner state into NATS cache at startup (eliminates DB reads on first scan)
MAILER_URL	String(URL)	N/A	The mailer's base URL (no trailing slash)
MAILER_KEY	String	N/A	The mailer's API key
SELFSERVICE_URL	String(URL)	N/A	The link to selfservice (no trailing slash)
IMPRINT_URL	String(URL)	/imprint	The link to an imprint page for the system (defaults to the frontend's imprint)
PRIVACY_URL	String(URL)	/privacy	The link to a privacy page for the system (defaults to the frontend's privacy page)

Recommended Editor

Visual Studio Code

Recommended Extensions

• will be automatically recommended via ./vscode/extensions.json

Staging

Branches & Tags

• vX.Y.Z: Release tags created from the main branch
  • The version numbers follow the semver standard
  • A new release tag automaticly triggers the release ci pipeline
• main: Protected "release" branch
  • The latest tag of the docker image get's build from this
• dev: Current dev branch for merging the different feature branches and bugfixes
  • New releases get created as tags from this
  • The dev tag of the docker image get's build from this
  • Only push minor changes to this branch!
  • To merge a feature branch into this please create a pull request
• feature/xyz: Feature branches - naming scheme: feature/issueid-title
• bugfix/xyz: Branches for bugfixes - naming scheme:bugfix/issueid-title