BorrowList3000

Simple application to keep track of who borrowed what stuff

A public instance is available at borrowlist.dreitausend.eu

Deployment

This application can be deployed using three different methods which are described in the following sections.

In all cases, the application will not immediately start without errors because it needs to bec configured first. This is done via environment variables. See Configuration for the list of available options.

On Docker

A docker image is built automatically that follows the master branch of the repository. It is available as ghcr.io/ftsell/borrowlist3000:dev-latest. Tagged images for each release are also available as ghcr.io/ftsell/borrowlist3000:<release>.

The container will automatically generate and print required configuration secrets if they are not defined. Take note of them and set them as environment variables.

On Kubernetes

A kubernetes configuration is included in this repository as kustomization.

# just render the config
kustomize build https://github.com/ftsell/BorrowList3000.git

# directly apply it to your existing cluster
kustomize build https://github.com/ftsell/BorrowList3000.git | kubectl apply -f -

The container will automatically generate and print required configuration secrets if they are not defined. Take note of them and set them as environment variables via the generated configmap.

On Baremetal from source

Although this deployment works, it is not recommended. If you need to use a deployment without containers, you should serve this application via uwsgi, gunicorn or the like.

To build the application from source, follow the following steps:

# get the code
git clone https://github.com/ftsell/BorrowList3000.git
cd BorrowList3000

# install python dependencies
pipenv install --ignore-pipfile

# build the frontend
cd src/borrowlist3000_frontend/borrowlist_vue
yarn run build

To start it:

cd src
./manage.py migrate
./manage.py

Configuration

The application is configured at runtime via the following environment variables:

Name	Default	Description	Notes
BL_DB_PATH	required	Path to the database file.	In container based deployments this preconfigured to point to `/app/data/db.sqlite`
BL_TOKEN_SECRET	required	Secret that is used to sign short lived tokens.	It can be generated by calling `manage.py gen_token_secret`. In container based deployments this is done automatically.
BL_SECRET_KEY	required	Django secret key.	It can be generated by calling `manage.py gen_secret_key`. In container based deployments this is done automatically.
BL_ALLOWED_HOSTS	required	List of hostnames which may be used when accessing the application.
BL_SERVED_OVER_HTTPS	`false`	Whether the application is served over HTTPS. If enabled, automatic redirects and additional security measures are activated.
BL_HSTS_SECONDS	`63072000`	If larger than 0 and `BL_SERVED_OVER_HTTPS` is true, HSTS is enabled with this configured value.
BL_TRUST_REVERSE_PROXY	`false`	If true, headers set by a reverse proxy (i.e. `X-Forwarded-Proto`) are trusted.	Defaults to `true` for Kubernetes deployments.

BL_EMAIL_FROM	undefined	From email address to use when sending mails.
BL_EMAIL_HOST	undefined	Host address of an email server.
BL_EMAIL_PORT	`25`	Port address on the email host.
BL_HOST_USER	undefined	Username used to authenticate on the email server.
BL_HOST_PASSWORD	undefined	Password used to authenticate on the email server.
BL_EMAIL_USE_TLS	`false`	Whether TLS (including STARTTLS) should be used on the email connection.
BL_EMAIL_USE_SSL	`false`	Whether SSL should be used on the email connection.

Note: If none of the BL_EMAIL_* options are defined, all email related features are completely disabled.

Software Architecture

The software ist composed of a backend which serves a GraphQL API which is then consumed by a frontend. The backend is written as a Django application while the frontend is using Vue.js.

Backend

The backend package is located directly in the src folder. It is in itself a rather simple django project composed of the five apps:

borrowlist3000 for general things like Django's asgi handler and settings.
borrowlist3000_db for low level database interactions. It pretty much consists of only models.
borrowlist3000_bll for specific business logic (BLL = business logic layer) like token generation or email sending.
borrowlist3000_api for the GraphQL Api that is consumed by the vue frontend. This app directly depends on the …_bll and …_db apps.
borrowlist3000_frontend which contains the vue code and ties it into the Django project. For its own structure see the Frontend Section.

Frontend

The frontend Vue.js code is located at src/borrowlist3000_frontend/borrowlist_vue. The package contains its own README that explains the directory structure and how to interact with it.

ftsell / BorrowList3000