86 lines
4.4 KiB
Markdown
86 lines
4.4 KiB
Markdown
# @lfk/document-server
|
|
|
|
The document generation server responsible for creating pdfs for sponsoring contracts, certificates and more.
|
|
This server doesn't interact with any database and can therefor be deployed on it's own.
|
|
The basic generation mechanism makes the templates and routes interchangeable (if you want to expand or modify it).
|
|
|
|
## Quickstart 🐳
|
|
> Use this to run the document server 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/docs to check if the server is running
|
|
|
|
## Dev Setup 🛠
|
|
> Local dev setup
|
|
|
|
1. Rename the .env.example file to .env (you can adjust app port and other settings, if needed)
|
|
2. Install Dependencies
|
|
```bash
|
|
yarn
|
|
```
|
|
3. Start the server
|
|
```bash
|
|
yarn dev
|
|
```
|
|
|
|
## ENV Vars
|
|
> You can provide them via .env file or docker env vars.
|
|
|
|
| Name | Type | Default | Description
|
|
| - | - | - | -
|
|
| APP_PORT | Number | 4010 | The port the backend server listens on. Is optional.
|
|
| NODE_ENV | String | dev | The apps env - influences debug info.
|
|
| EVENT_NAME | String | "Please set the event name" | The event's name - used to generate pdf text.
|
|
| CURRENCY_SYMBOL | String | "€" | The your currency's symbol - used to generate pdf text.
|
|
| SPONSORING_RECEIPT_MINIMUM_AMOUNT | String | "10" | The mimimum total donation amount a sponsor has to donate to be able to receive a donation receipt - used to generate pdf text.
|
|
| SPONOR_LOGOS | Array<String> | Empty png | The sponsor images you want to loop through. You can provide them via http url, local file or base64-encoded image.
|
|
| API_KEY | String(min length: 64) | Random generated string | The api key you want to use for auth (query-param `key`), has to be at least 64 chars long.
|
|
| DISCLAIMER_TEXT | String | N/A | A disclaimer that will get displayed on the bottom of each sponsoring contract. R/N You can only provide the disclaimer for one language.
|
|
| DONATIONS_FOOTER_TEXT | String | N/A | A text that will get displayed on the bottom of each runner certificate's second page. R/N You can only provide the text for one language.
|
|
| CONTRACTS_PER_RUNNER | Number | 1 | The amount of contracts that get created per runner (per request).
|
|
| CODEFORMAT | String | code39 | The barcode format for everything except.
|
|
| CODEFORMAT_CARDS | String | code39 | The barcode format for runnercards (overwrites CODEFORMAT).
|
|
| CARD_SUBTITLE | String | Empty | A subtitle that get's displayed on the cards under the eventname.
|
|
|
|
## Templates
|
|
> The document server uses html templates to generate various pdf documents.
|
|
> The templates are stored in src/templates by default.
|
|
|
|
We provide a set of default templates that we use for the ["Lauf für Kaya!" charity run](https://lauf-fuer-kaya.de).
|
|
We use handlebars for templateing utilizing i18next for translation - the i18n string format in the templates is : `{{__ "string"}}`
|
|
You can provide your own templates by replacing the ones we provided before compiling the project or by simply mounting your custom templates into the docker container.
|
|
|
|
The server currently needs the following templates to work:
|
|
* sponsoring_contract.html
|
|
|
|
### Sponsoring Contracts
|
|
|
|
| Template Data | Type | Optional | Description
|
|
| - | - | - | -
|
|
| runners | array(Runner) | ❌ | The runner objects. We generate a contract for each runner on a new DIN-A5 page.
|
|
|
|
|
|
## Recommended Editor
|
|
|
|
[Visual Studio Code](https://code.visualstudio.com/)
|
|
|
|
### Recommended Extensions
|
|
|
|
* will be automatically recommended via ./vscode/extensions.json
|
|
* we also provide a config for i18n-ally in the .vscode folder
|
|
|
|
## 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
|
|
* New releases get created as tags from this
|
|
* dev: Current dev branch for merging the different feature branches and bugfixes
|
|
* 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 - nameing scheme: `feature/issueid-title`
|
|
* bugfix/xyz: Branches for bugfixes - nameing scheme:`bugfix/issueid-title` |