The document generation server responsible for creating pdfs for sponsoring contracts, certificates and more.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
Nicolai Ort 11efdebacf Merge pull request 'Release 0.5.1' (#43) from dev into main 2 months ago
.vscode Added first parts of template 4 months ago
src Merge branch 'dev' of git.odit.services:lfk/document-server into dev 2 months ago
.drone.yml Pipeline mtu fix 2 months ago
.gitignore Now with workin i18n-ally config🥳 4 months ago
CHANGELOG.md 🧾New changelog file version [CI SKIP] [skip ci] 2 months ago
Dockerfile Emoji+Chinese fixes🌍 2 months ago
LICENSE Initial commit 4 months ago
README.md Added new config options to reamde 2 months ago
docker-compose.yml Updated docker-compose example🐳 2 months ago
licenses.md 📖New license file version [CI SKIP] [skip ci] 2 months ago
package.json 🚀Bumped version to v0.5.1 2 months ago
sort_translations.js Added translation sorting secript 4 months ago
tsconfig.json Added tsconfig 4 months ago

README.md

@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
    yarn
    
  3. Start the server
    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 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. 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.

Visual Studio Code

  • 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