141 lines
7.0 KiB
Markdown
141 lines
7.0 KiB
Markdown
# @lfk/backend
|
|
|
|
Backend Server
|
|
|
|
## Prerequisites
|
|
|
|
This project uses **Bun** as the runtime and package manager. Install Bun first:
|
|
|
|
```bash
|
|
# macOS/Linux
|
|
curl -fsSL https://bun.sh/install | bash
|
|
|
|
# Windows
|
|
powershell -c "irm bun.sh/install.ps1 | iex"
|
|
```
|
|
|
|
Or visit [bun.sh](https://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):
|
|
```bash
|
|
docker-compose up -d nats
|
|
```
|
|
3. Install dependencies:
|
|
```bash
|
|
bun install
|
|
```
|
|
4. Start the server:
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Start the server first
|
|
bun run dev
|
|
|
|
# In another terminal:
|
|
bun run benchmark
|
|
```
|
|
|
|
### Generate Docs
|
|
```bash
|
|
bun run docs
|
|
```
|
|
|
|
### Other Commands
|
|
```bash
|
|
# 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](https://code.visualstudio.com/)
|
|
|
|
### 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` |