Simple application to keep track of who borrowed what stuff
A public instance is available at borrowlist.dreitausend.eu
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.
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.
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.
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
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.
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.
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.
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.