Manual installation

To run ephios on a debian-based system, make sure you have prepared the prerequisites. What follows is a rough guide to install ephios and configure the supporting services. Feel free to adapt it to your needs and style. The guide assumes you are logged in as root (# is a root prompt, $ the ephios user prompt).

Unix user

Create a unix user that will run the ephios. You should avoid running ephios with root privileges.

# adduser --disabled-password --home /home/ephios ephios

Package dependencies

Install the system packages that ephios depends on.

# apt-get install gettext

python environment and ephios package

Create a virtualenv for ephios and install the ephios package. Replace pgsql with mysql if you want to use mysql.

# sudo -u ephios python3.11 -m venv /home/ephios/venv
# sudo -u ephios /home/ephios/venv/bin/pip install gunicorn "ephios[redis,pgsql]"


Create a database user and a database for ephios. For postgres this could look like this:

# sudo -u postgres createuser ephios
# sudo -u postgres createdb -O ephios ephios

Make sure the encoding of the database is UTF-8.

Data directory

ephios stores some data in the file system. Create the folders and make sure the ephios user can write to them. The reverse proxy needs to be able to read the static files stored in /var/ephios/data/public/static.

# mkdir -p /var/ephios/data/
# chown -R ephios:ephios /var/ephios

Config file

ephios can be configured using environment variables. They can also be read from a file. Create a file /home/ephios/ephios.env (owned by the ephios user) with the following content, replacing the values with your own:

ADMINS=Org Admin <>

For details on the configuration options and syntax, see configuration options.

To test your configuration, run:

# sudo -u ephios -i
$ export ENV_PATH="/home/ephios/ephios.env"
$ source /home/ephios/venv/bin/activate
$ python -m ephios check --deploy
$ python -m ephios sendtestemail --admin

Build ephios files

Now that the configuration is in place, we can build the static files and the translation files.

# sudo -u ephios -i
$ export ENV_PATH="/home/ephios/ephios.env"
$ source /home/ephios/venv/bin/activate
$ python -m ephios migrate
$ python -m ephios build

Setup cron

ephios needs to have the run_periodic management command run periodically (at least every five minutes). This command sends notifications and performs other tasks that need to be done regularly. Run crontab -e -u ephios and add the following line:

*/5 * * * * ENV_PATH=/home/ephios/ephios.env /home/ephios/venv/bin/python -m ephios run_periodic

Setup gunicorn systemd service

To run ephios with gunicorn, create a systemd service file /etc/systemd/system/ephios-gunicorn.service with the following content:

Description=ephios gunicorn daemon

ExecStart=/home/ephios/venv/bin/gunicorn ephios.wsgi --name ephios \
            --workers 5 --max-requests 1000  --max-requests-jitter 100 --bind=


To start the service run:

# systemctl daemon-reload
# systemctl enable ephios-gunicorn
# systemctl start ephios-gunicorn

Configure reverse proxy

Configure your reverse proxy to forward requests to ephios. For nginx, you can start with this:

server {
    listen 80 default_server;
    listen [::]:80 ipv6only=on default_server;
    location / {
        return 301 https://$host$request_uri;

server {
    listen 443 ssl;
    listen [::]:443 ipv6only=on ssl;

    http2 on;
    ssl_certificate     /etc/letsencrypt/certificates/;
    ssl_certificate_key /etc/letsencrypt/certificates/;

    location / {
        proxy_pass http://localhost:8327;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header Host $http_host;
        proxy_redirect off;

    location /static/ {
        alias /var/ephios/data/public/static/;
        access_log off;
        expires 1d;
        add_header Cache-Control "public";

For apache you can build on this:

<VirtualHost *:80>
    Redirect permanent /

<VirtualHost *:443>
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/certificates/
    SSLCertificateKeyFile /etc/letsencrypt/certificates/

    ProxyPass /static/ !
    Alias /static/ /var/ephios/data/public/static/
    <Directory /var/ephios/data/public/static/>
        Require all granted

    RequestHeader set X-Forwarded-Proto "https"
    ProxyPreserveHost On
    ProxyPass / http://localhost:8327/
    ProxyPassReverse / http://localhost:8327/

Remember to replace all the domain names and certificate paths with your own. Make sure to use secure SSL settings. To obtain SSL certificates, you can use certbot with Let’s Encrypt.

Next steps

After restarting your reverse proxy you should be able to access ephios at You can now create your first user account by running:

# sudo -u ephios -i
$ export ENV_PATH="/home/ephios/ephios.env"
$ source /home/ephios/venv/bin/activate
$ python -m ephios createsuperuser

You should now secure your installation. Try starting with the tips below.

To install a plugin install them via pip:

# sudo -u ephios -i
$ export ENV_PATH="/home/ephios/ephios.env"
$ source /home/ephios/venv/bin/activate
$ pip install "ephios-<plugin>"
$ python -m ephios migrate
$ python -m ephios build

To update ephios create a backup of your database and files and run:

# sudo -u ephios -i
$ export ENV_PATH="/home/ephios/ephios.env"
$ source /home/ephios/venv/bin/activate
$ pip install -U "ephios[redis,pgsql]"
$ python -m ephios migrate
$ python -m ephios build

After installing plugins or updating, restart the gunicorn service:

# systemctl restart ephios-gunicorn