Self-Hosting the Web Interface

Onesimus Web is a Django/HTMX application served by Daphne (ASGI) behind nginx. The setup takes about 15 minutes on a fresh Debian/Ubuntu server.

Requirements: Debian 12+ / Ubuntu 22.04+, Python 3.11+, nginx ≥ 1.18, a domain name with DNS pointing to your server.

1. System Dependencies

sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip nginx git

2. Create the Service User and Directory

sudo useradd -r -s /usr/sbin/nologin www-data   # already exists on most systems
sudo mkdir -p /srv/onesimus-web
sudo chown www-data:www-data /srv/onesimus-web

3. Clone and Install

cd /srv/onesimus-web
sudo -u www-data git clone https://github.com/Beerlesklopfer/onesimus-web.git .

# Create virtualenv and install dependencies
sudo -u www-data python3 -m venv .venv
sudo -u www-data .venv/bin/pip install -r requirements-prod.txt

4. Environment Configuration

Environment variables are stored in /etc/onesimus/onesimus.env. The install-system make target creates this file from a template automatically. To create it manually:

sudo mkdir -p /etc/onesimus
sudo tee /etc/onesimus/onesimus.env <<EOF
DJANGO_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")
DJANGO_DEBUG=false
DJANGO_ALLOWED_HOSTS=onesimus.example.com
CSRF_TRUSTED_ORIGINS=https://onesimus.example.com
DJANGO_LOG_LEVEL=INFO
EOF
sudo chmod 640 /etc/onesimus/onesimus.env
sudo chown root:www-data /etc/onesimus/onesimus.env

Replace onesimus.example.com with your actual domain. The file is loaded by systemd via EnvironmentFile=/etc/onesimus/onesimus.env.

5. Database and Static Files

sudo -u www-data .venv/bin/python manage.py migrate
sudo -u www-data .venv/bin/python manage.py collectstatic --noinput

# Create the first admin user
sudo -u www-data .venv/bin/python manage.py createsuperuser

6. Log Directory

sudo mkdir -p /var/log/onesimus
sudo chown www-data:www-data /var/log/onesimus

7. systemd Service

Copy the unit file from the repository:

sudo cp contrib/onesimus.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable onesimus
sudo systemctl start onesimus
sudo systemctl status onesimus

Verify Daphne is listening on port 8888:

ss -tlnp | grep 8888

8. nginx Configuration

sudo cp contrib/onesimus-web.nginx.conf /etc/nginx/sites-available/onesimus

Edit the file and replace onesimus.example.com with your domain:

sudo nano /etc/nginx/sites-available/onesimus

Enable the site:

sudo ln -s /etc/nginx/sites-available/onesimus /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

9. TLS Certificate (Let’s Encrypt)

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d onesimus.example.com

Certbot will automatically update the nginx config. Reload nginx afterwards:

sudo systemctl reload nginx

10. Verify

Open https://onesimus.example.com in your browser. You should see the login page.

Log in with the superuser credentials you created in step 5. The app connects to Bareos via the Director protocol — configure your connection under File → Connect.

Updating

cd /srv/onesimus-web
sudo -u www-data git pull
sudo -u www-data .venv/bin/pip install -r requirements-prod.txt
sudo -u www-data .venv/bin/python manage.py migrate
sudo -u www-data .venv/bin/python manage.py collectstatic --noinput
sudo chown -R www-data:www-data /srv/onesimus-web /var/log/onesimus
sudo systemctl restart onesimus
sudo nginx -t && sudo systemctl reload nginx

Or simply use the Makefile:

sudo make update

Troubleshooting

Symptom	Likely Cause	Fix
502 Bad Gateway	Daphne not running	`systemctl status onesimus`
403 CSRF error	Missing `CSRF_TRUSTED_ORIGINS`	Update `.env`, restart service
Static files 404	`collectstatic` not run	`manage.py collectstatic --noinput`
Login redirect loop	`DJANGO_ALLOWED_HOSTS` wrong	Check `.env`, restart
Logs missing	Wrong directory ownership	`chown www-data:www-data /var/log/onesimus`

Logs are written to /var/log/onesimus/onesimus.log and rotated automatically.

Using the Makefile

The repository ships with a Makefile that automates the entire deployment lifecycle. Clone the repo on your server and run:

Command	What it does
`sudo make sysdeps`	Install system packages (apt)
`sudo make install-system`	Create `/etc/onesimus/onesimus.env` template, install systemd unit and nginx config
`sudo make update`	Sync code, install dependencies, migrate, collectstatic, fix ownership, restart service, reload nginx
`make superuser`	Create the initial admin user interactively
`sudo make mockdata`	Populate the database with mock data for testing

Recommended first-time setup:

git clone https://github.com/Beerlesklopfer/onesimus-web.git
cd onesimus-web
sudo make sysdeps
sudo make install-system   # then edit /etc/onesimus/onesimus.env
sudo make update
make superuser

After editing /etc/onesimus/onesimus.env, every future update is a single command:

sudo make update