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]"

Database

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:

DEBUG=False
DATA_DIR=/var/ephios/data
DATABASE_URL=psql://dbuser:dbpass@localhost:5432/ephios
ALLOWED_HOSTS="your.domain.org"
SITE_URL=https://your.domain.org
EMAIL_URL=smtp+ssl://emailuser:emailpass@smtp.domain.org:465
DEFAULT_FROM_EMAIL=ephios@domain.org
SERVER_EMAIL=ephios@domain.org
ADMINS=Org Admin <admin@domain.org>
CACHE_URL="redis://127.0.0.1:6379/1"

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:

[Unit]
Description=ephios gunicorn daemon
After=network.target

[Service]
Type=notify
User=ephios
Group=ephios
WorkingDirectory=/home/ephios
Environment="ENV_PATH=/home/ephios/ephios.env"
ExecStart=/home/ephios/venv/bin/gunicorn ephios.wsgi --name ephios \
            --workers 5 --max-requests 1000  --max-requests-jitter 100 --bind=127.0.0.1:8327
Restart=on-failure

[Install]
WantedBy=multi-user.target

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;
    server_name your.domain.org
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ipv6only=on ssl;
    server_name your.domain.org;

    http2 on;
    ssl_certificate     /etc/letsencrypt/certificates/your.domain.org.crt;
    ssl_certificate_key /etc/letsencrypt/certificates/your.domain.org.key;

    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>
    ServerName your.domain.org
    Redirect permanent / https://your.domain.org/
</VirtualHost>

<VirtualHost *:443>
    ServerName your.domain.org
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/certificates/your.domain.org.crt
    SSLCertificateKeyFile /etc/letsencrypt/certificates/your.domain.org.key

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

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

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 https://your.domain.org. 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