The project is developed in Python using the Django framework. There are 3 sections below, focussing on developers, running the project using Docker and hints for running the project in production.
You need the following libraries and/or programs:
- Python 3.11
- Python Virtualenv and Pip
- PostgreSQL 11 or above
- Node.js
- npm
Developers can follow the following steps to set up the project on their local development machine.
Navigate to the location where you want to place your project.
Get the code:
$ git clone [email protected]:maykinmedia/open-klant.git $ cd open-klant
Install all required (backend) libraries:
$ virtualenv env $ source env/bin/activate $ pip install -r requirements/dev.txt
Install all required (frontend) libraries and build static files.
$ npm install $ npm run build
Activate your virtual environment and create the statics and database:
$ source env/bin/activate $ python src/manage.py collectstatic --link $ python src/manage.py migrate
Create a superuser to access the management interface:
$ python src/manage.py createsuperuser
You can now run your installation and point your browser to the address given by this command:
$ python src/manage.py runserver
Create a .env file with database settings. See dotenv.example for an example.
$ cp dotenv.example .env
Note: If you are making local, machine specific, changes, add them to
src/openklant/conf/local.py
. You can base this file on the
example file included in the same directory.
When updating an existing installation:
Activate the virtual environment:
$ cd open-klant $ source env/bin/activate
Update the code and libraries:
$ git pull $ pip install -r requirements/dev.txt $ npm install $ npm run build
Update the statics and database:
$ python src/manage.py collectstatic --link $ python src/manage.py migrate
To run the test suite:
$ python src/manage.py test openklant
A number of common settings/configurations can be modified by setting
environment variables. You can persist these in your local.py
settings
file or as part of the (post)activate
of your virtualenv.
SECRET_KEY
: the secret key to use. A default is set indev.py
DB_NAME
: name of the database for the project. Defaults toopenklant
.DB_USER
: username to connect to the database with. Defaults toopenklant
.DB_PASSWORD
: password to use to connect to the database. Defaults toopenklant
.DB_HOST
: database host. Defaults tolocalhost
DB_PORT
: database port. Defaults to5432
.SENTRY_DSN
: the DSN of the project in Sentry. If set, enabled Sentry SDK as logger and will send errors/logging to Sentry. If unset, Sentry SDK will be disabled.
The easiest way to get the project started is by using Docker Compose.
Clone or download the code from Github in a folder like
openklant
:$ git clone [email protected]:maykinmedia/open-klant.git Cloning into 'openklant'... ... $ cd open-klant
Start the database and web services:
$ docker-compose up -d Starting openklant_db_1 ... done Starting openklant_web_1 ... done
It can take a while before everything is done. Even after starting the web container, the database might still be migrating. You can always check the status with:
$ docker logs -f openklant_web_1
Create an admin user and load initial data. If different container names are shown above, use the container name ending with
_web_1
:$ docker exec -it openklant_web_1 /app/src/manage.py createsuperuser Username: admin ... Superuser created successfully. $ docker exec -it openklant_web_1 /app/src/manage.py loaddata admin_index groups Installed 5 object(s) from 2 fixture(s)
Point your browser to
http://localhost:8000/
to access the project's management interface with the credentials used in step 3.If you are using
Docker Machine
, you need to point your browser to the Docker VM IP address. You can get the IP address by doingdocker-machine ls
and point your browser tohttp://<ip>:8000/
instead (where the<ip>
is shown below the URL column):$ docker-machine ls NAME ACTIVE DRIVER STATE URL default * virtualbox Running tcp://<ip>:<port>
To shutdown the services, use
docker-compose down
and to clean up your system you can rundocker system prune
.
If you just want to run the project as a Docker container and connect to an
external database, you can build and run the Dockerfile
and pass several
environment variables. See src/openklant/conf/docker.py
for
all settings.
$ docker build -t openklant
$ docker run \
-p 8000:8000 \
-e DATABASE_USERNAME=... \
-e DATABASE_PASSWORD=... \
-e DATABASE_HOST=... \
--name openklant \
openklant
$ docker exec -it openklant /app/src/manage.py createsuperuser
Using bin/release-docker-image
, you can easily build and tag the image.
The script is based on git branches and tags - if you're on the master
branch and the current HEAD
is tagged, the tag will be used as
RELEASE_TAG
and the image will be pushed. If you want to push the image
without a git tag, you can use the RELEASE_TAG
envvar.
The image will only be pushed if the JOB_NAME
envvar is set. The image
will always be built, even if no envvar is set. The default release tag is
latest
.
Example usage:
JOB_NAME=publish RELEASE_TAG=dev ./bin/release-docker-image.sh
Ansible is used to deploy test, staging and production servers. It is assumed the target machine has a clean Debian installation.
Make sure you have Ansible installed (globally or in the virtual environment):
$ pip install ansible
Navigate to the project directory, and install the Maykin deployment submodule if you haven't already:
$ git submodule update --init
Run the Ansible playbook to provision a clean Debian machine:
$ cd deployment $ ansible-playbook <test/staging/production>.yml
For more information, see the README
file in the deployment directory.
All settings for the project can be found in
src/openklant/conf
.
The file local.py
overwrites settings from the base configuration.
Commands can be executed using:
$ python src/manage.py <command>
There are no specific commands for the project. See
Django framework commands for all default commands, or type
python src/manage.py --help
.