Hermine provides a Docker Compose configuration with the following services:
a PostgreSQL database
a gunicorn server for the Python backend
Two profiles are available :
httpsprofile where Caddy is configured with automatic HTTPS. It can easily be deployed on a VPS.
localhostprofile to use Hermine on a local machine or behind a reverse proxy (not suited for development)
Configuration is made through a
.env file which should be
placed at the root of the project.
By default, a superadmin user is created with
admin / admin credential.
You can update these credentials from
In case you need to access the
django-admin tool from outside Docker, you should use :
docker exec -it hermine_django_1 /opt/hermine/manage.py
You just need to set
HERMINE_HOST environment variables before
you can start the containers. The easiest way to do so is to
write it in a .env file.
# configure secret key echo "HERMINE_SECRET=RANDOMSTRINGFORSECURITY" > .env # optional : configure HOST if you use something else than localhost:80 echo "HERMINE_HOST=example.com" >> .env # start the services in background docker-compose --profile https up -d
Hermine should be accessible at
https://example.com. Caddy automatically sets up
and renew HTTPS certificates.
To update your instance :
cd hermine/ git switch main && git pull docker-compose --profile https up -d --build
You must set
PORT insted of
# configure secret key echo "HERMINE_SECRET=RANDOMSTRINGFORSECURITY" > .env # configure port echo "PORT=9000" >> .env # start the services in background docker-compose --profile localhost up -d
Downloading the source code
git clone https://gitlab.com/hermine-project/hermine.git
You can also use git to clone a specific version :
git clone --branch v0.0.1 https://gitlab.com/hermine-project/hermine.git
Major versions changes mean breaking changes, either in the installation configuration or in the API. You can find more information in CHANGELOG.md.
For minor or patch versions, it should be safe to update your instance by pulling the latest tag from the repository or downloading from the release page.
Install python dependencies
You should run Hermine in a Python virtual environnement. Using poetry, you can create the virtual environment and install the dependencies with:
cd hermine/ poetry install
Install and build front modules
npm install npm run build
Configure your instance
Before the first run, you have to create a
config.py file in the
cp hermine/hermine/config.default.py hermine/hermine/config.py
hermine/hermine/config.py according to your configuration.
Ex: For development purposes, you can set
Update the database structure and create a superuser :
# activate poetry shell poetry shell # create database structure python hermine/manage.py migrate # create a superuser python hermine/manage.py createsuperuser
Run the server
How you want to serve Hermine is up to you. You should be familiar with WSGI servers and reverse proxies. You can find more information in Django documentation.
A typical installation is :
Gunicorn or another WSGI server (running Hermine’s
NGinx to serve static files and proxy other requests to Gunicorn
Hermine is not different from any other Django application. You can find more information in Django documentation.
For development purpose, you can simply run :
# run the server python hermine/manage.py runserver
Static files should be served by your web server. After
install, you must run
collectstatic to copy static files to the
directory (or any other configured in
python hermine/manage.py collectstatic
You can find more information in Django documentation.
You can use an OAuth2 server as authentication backend by uncommenting and
OAUTH_CLIENT entry in your
config.py file. When using Docker,
these elements have to be set in your
.env file. Further information
can be found in Python Social Auth’s documentation
on which Hermine relies.
Users will be created on the fly at authentication by the OAuth server.
Hermine provides two test endpoints which you can use in your monitoring system.
/ping/ always send a 200 response, and can be used to check server availability.
/ready/ does the same but also tries to connect to Hermine database. It sends a 200 response if it succeeds.