Private
Public Access
Add hardening and deployment: admin dashboard, security headers, install docs
Adds an admin-only dashboard (apps/core) surfacing feeds that are failing to fetch, with error messages, subscriber counts, and a one-click retry that resets backoff and re-queues the fetch. Hardens config/settings/prod.py with the remaining standard Django security settings (HSTS preload, nosniff, referrer-policy, frame-options, SameSite cookies) plus a Content-Security-Policy header via django-csp, as a second layer behind nh3's HTML sanitization of feed content. Adds docs/install.md (pip + gunicorn + systemd + nginx, SQLite and Postgres both covered) plus the systemd units and nginx snippet it references, LICENSE (AGPL-3.0-or-later, matching pyproject.toml), and an updated README. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
7577110238
commit
3f6474ce94
16 files changed
+1226
-6
No files matched your search
@@ -0,0 +1,22 @@
|
||||
[Unit]
|
||||
Description=Evection (Celery beat scheduler)
|
||||
After=network.target redis-server.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=evection
|
||||
Group=evection
|
||||
WorkingDirectory=/opt/evection/app
|
||||
EnvironmentFile=/opt/evection/app/.env
|
||||
Environment=DJANGO_SETTINGS_MODULE=config.settings.prod
|
||||
ExecStart=/opt/evection/venv/bin/celery -A config beat --loglevel=info \
|
||||
--schedule=/opt/evection/app/celerybeat-schedule
|
||||
Restart=on-failure
|
||||
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
ProtectSystem=strict
|
||||
ReadWritePaths=/opt/evection/app
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,23 @@
|
||||
[Unit]
|
||||
Description=Evection (Celery worker)
|
||||
After=network.target redis-server.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=evection
|
||||
Group=evection
|
||||
WorkingDirectory=/opt/evection/app
|
||||
EnvironmentFile=/opt/evection/app/.env
|
||||
Environment=DJANGO_SETTINGS_MODULE=config.settings.prod
|
||||
# Combine worker + beat on a single small host by adding "-B" here instead
|
||||
# of also running evection-celery-beat.service — see docs/install.md.
|
||||
ExecStart=/opt/evection/venv/bin/celery -A config worker --loglevel=info
|
||||
Restart=on-failure
|
||||
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
ProtectSystem=strict
|
||||
ReadWritePaths=/opt/evection/app
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,26 @@
|
||||
[Unit]
|
||||
Description=Evection (gunicorn)
|
||||
After=network.target redis-server.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=evection
|
||||
Group=evection
|
||||
WorkingDirectory=/opt/evection/app
|
||||
EnvironmentFile=/opt/evection/app/.env
|
||||
Environment=DJANGO_SETTINGS_MODULE=config.settings.prod
|
||||
RuntimeDirectory=evection
|
||||
ExecStart=/opt/evection/venv/bin/gunicorn \
|
||||
--workers 3 \
|
||||
--bind unix:/run/evection/gunicorn.sock \
|
||||
config.wsgi:application
|
||||
ExecReload=/bin/kill -s HUP $MAINPID
|
||||
Restart=on-failure
|
||||
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
ProtectSystem=strict
|
||||
ReadWritePaths=/opt/evection/app
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,45 @@
|
||||
# Reverse proxy for Evection. Copy to /etc/nginx/sites-available/evection,
|
||||
# adjust server_name and the certificate paths (certbot will fill those in
|
||||
# for you if you use `certbot --nginx`), then symlink into sites-enabled.
|
||||
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
server_name your-domain.example;
|
||||
|
||||
# certbot --nginx adds the HTTPS server block and redirects here
|
||||
# automatically; until then this serves plain HTTP.
|
||||
location / {
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl;
|
||||
listen [::]:443 ssl;
|
||||
server_name your-domain.example;
|
||||
|
||||
ssl_certificate /etc/letsencrypt/live/your-domain.example/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/your-domain.example/privkey.pem;
|
||||
|
||||
client_max_body_size 10M; # OPML uploads are small, but leave headroom
|
||||
|
||||
location /static/ {
|
||||
alias /opt/evection/app/staticfiles/;
|
||||
expires 30d;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
|
||||
# The service worker must be served from the domain root with the right
|
||||
# scope header for its Service-Worker-Allowed: / to take effect — it's
|
||||
# already a normal Django view (see apps.pwa), proxied like everything
|
||||
# else below, so no special-casing is needed here.
|
||||
|
||||
location / {
|
||||
proxy_pass http://unix:/run/evection/gunicorn.sock;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
+206
@@ -0,0 +1,206 @@
|
||||
# Installing Evection
|
||||
|
||||
Evection is a traditional Python/Django application: `pip install`, a WSGI server
|
||||
(gunicorn), a Celery worker + beat scheduler for background feed polling, and an
|
||||
nginx reverse proxy in front of it. There's no Docker image for v1 — everything
|
||||
below runs directly on the host.
|
||||
|
||||
Both SQLite and PostgreSQL are fully supported. Steps that differ are marked
|
||||
**SQLite** / **Postgres**; everything else applies to both.
|
||||
|
||||
## 1. Prerequisites
|
||||
|
||||
- Python 3.11 or 3.12
|
||||
- Redis (Celery's broker)
|
||||
- **Postgres only**: a PostgreSQL server (12+) and its client headers if you're not
|
||||
using the bundled `psycopg[binary]` wheel (most platforms are covered by the wheel,
|
||||
so this is rarely needed)
|
||||
- nginx (or another reverse proxy)
|
||||
- A domain name pointed at the host, if you want this reachable outside your LAN
|
||||
|
||||
Debian/Ubuntu example for the non-Python pieces:
|
||||
|
||||
```bash
|
||||
sudo apt install redis-server nginx
|
||||
# Postgres only:
|
||||
sudo apt install postgresql
|
||||
```
|
||||
|
||||
## 2. Create a dedicated system user
|
||||
|
||||
Evection should run as its own unprivileged user, not root and not your personal
|
||||
account:
|
||||
|
||||
```bash
|
||||
sudo adduser --system --group --home /opt/evection evection
|
||||
sudo -u evection -H git clone https://github.com/<you>/evection.git /opt/evection/app
|
||||
```
|
||||
|
||||
(Swap the `git clone` for however you're distributing releases — a tagged
|
||||
checkout or an extracted release tarball both work the same way.)
|
||||
|
||||
## 3. Python environment
|
||||
|
||||
```bash
|
||||
cd /opt/evection/app
|
||||
sudo -u evection -H python3 -m venv /opt/evection/venv
|
||||
sudo -u evection -H /opt/evection/venv/bin/pip install .
|
||||
```
|
||||
|
||||
## 4. Configure
|
||||
|
||||
Copy the example environment file and edit it:
|
||||
|
||||
```bash
|
||||
sudo -u evection -H cp .env.example /opt/evection/app/.env
|
||||
sudo -u evection -H "$EDITOR" /opt/evection/app/.env
|
||||
```
|
||||
|
||||
Every `manage.py` command below needs `DJANGO_SETTINGS_MODULE=config.settings.prod`
|
||||
in its environment — `manage.py` itself defaults to the dev settings (`DEBUG=True`)
|
||||
for local convenience, so production commands must override that explicitly (the
|
||||
`env DJANGO_SETTINGS_MODULE=...` prefix you'll see in the commands below). The
|
||||
systemd units in step 6 set the same thing for gunicorn and Celery.
|
||||
|
||||
At minimum, set the following in `.env`:
|
||||
|
||||
- `SECRET_KEY` — generate one with
|
||||
`python -c "import secrets; print(secrets.token_urlsafe(50))"` and keep it out of
|
||||
version control
|
||||
- `DEBUG=False`
|
||||
- `ALLOWED_HOSTS` — your domain(s), comma-separated
|
||||
- `DATABASE_URL`:
|
||||
- **SQLite**: `sqlite:////opt/evection/app/db.sqlite3` (note the four slashes for
|
||||
an absolute path)
|
||||
- **Postgres**: `postgres://evection:<password>@localhost:5432/evection` — create
|
||||
the role and database first:
|
||||
```bash
|
||||
sudo -u postgres createuser evection -P
|
||||
sudo -u postgres createdb evection -O evection
|
||||
```
|
||||
- `REDIS_URL` — `redis://localhost:6379/0` is fine for a single-host install
|
||||
|
||||
Evection reads `config.settings.prod` when run via the commands below (see each
|
||||
systemd unit's `DJANGO_SETTINGS_MODULE`). That module turns on HTTPS-only cookies,
|
||||
HSTS, and a Content-Security-Policy header on top of the base settings — see
|
||||
`config/settings/prod.py` if you need to adjust it for your proxy setup.
|
||||
|
||||
## 5. Initialize the database and static files
|
||||
|
||||
```bash
|
||||
cd /opt/evection/app
|
||||
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
|
||||
/opt/evection/venv/bin/python manage.py migrate
|
||||
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
|
||||
/opt/evection/venv/bin/python manage.py collectstatic --noinput
|
||||
```
|
||||
|
||||
**SQLite only**: the search index lives in a SQLite FTS5 table that `migrate`
|
||||
already created above. If you ever bulk-load articles outside the normal fetch
|
||||
pipeline (e.g. restoring a dump), rebuild it with:
|
||||
|
||||
```bash
|
||||
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
|
||||
/opt/evection/venv/bin/python manage.py reindex_search
|
||||
```
|
||||
|
||||
**Postgres** needs no equivalent step — its full-text search is computed at query
|
||||
time, not stored in an index.
|
||||
|
||||
You don't need to create an admin account by hand: the first time anyone loads the
|
||||
site, Evection's setup wizard creates the first account for you and makes it an
|
||||
instance admin.
|
||||
|
||||
## 6. systemd units
|
||||
|
||||
Copy the three unit files from `docs/deploy/` into place and adjust paths if you
|
||||
installed somewhere other than `/opt/evection`:
|
||||
|
||||
```bash
|
||||
sudo cp docs/deploy/evection-gunicorn.service \
|
||||
docs/deploy/evection-celery-worker.service \
|
||||
docs/deploy/evection-celery-beat.service \
|
||||
/etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now evection-gunicorn evection-celery-worker evection-celery-beat
|
||||
```
|
||||
|
||||
This runs the Celery worker and beat scheduler as two separate processes, which is
|
||||
the safer default once you might want to scale the worker independently. On a
|
||||
single small host you can combine them into one process instead and skip the
|
||||
`evection-celery-beat` unit — edit `evection-celery-worker.service`'s `ExecStart` to
|
||||
add `-B`:
|
||||
|
||||
```
|
||||
ExecStart=/opt/evection/venv/bin/celery -A config worker -B --loglevel=info
|
||||
```
|
||||
|
||||
Check they came up cleanly:
|
||||
|
||||
```bash
|
||||
sudo systemctl status evection-gunicorn evection-celery-worker evection-celery-beat
|
||||
sudo journalctl -u evection-gunicorn -f
|
||||
```
|
||||
|
||||
## 7. nginx
|
||||
|
||||
Copy `docs/deploy/nginx.conf.example` to `/etc/nginx/sites-available/evection`,
|
||||
adjust `server_name` and the certificate paths, then enable it:
|
||||
|
||||
```bash
|
||||
sudo cp docs/deploy/nginx.conf.example /etc/nginx/sites-available/evection
|
||||
sudo ln -s /etc/nginx/sites-available/evection /etc/nginx/sites-enabled/
|
||||
sudo nginx -t && sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
Get a TLS certificate (Let's Encrypt via certbot is the easiest path):
|
||||
|
||||
```bash
|
||||
sudo apt install certbot python3-certbot-nginx
|
||||
sudo certbot --nginx -d your-domain.example
|
||||
```
|
||||
|
||||
Evection's `prod` settings enable `SECURE_SSL_REDIRECT` and HSTS by default, so
|
||||
plan to have TLS working before your first real visit — see
|
||||
`config/settings/prod.py` to disable the redirect temporarily if you need to debug
|
||||
over plain HTTP first.
|
||||
|
||||
## 8. Visit the site
|
||||
|
||||
Open `https://your-domain.example/`. The setup wizard appears automatically since
|
||||
no account exists yet — create your admin account there. Once any account exists,
|
||||
`/setup/` stops being reachable, and you manage further accounts from the
|
||||
"Manage Users" page (visible to admins) or Django's own `/admin/`.
|
||||
|
||||
Once logged in, check the "Dashboard" link in the top nav (admins only) — it
|
||||
surfaces any feeds that are failing to fetch, which is the fastest way to catch a
|
||||
misconfigured feed or an outage at the source.
|
||||
|
||||
## Backups
|
||||
|
||||
- **SQLite**: stop the services (or at least gunicorn and the Celery worker) and
|
||||
copy the `db.sqlite3` file, or use `sqlite3 db.sqlite3 ".backup backup.sqlite3"`
|
||||
for a consistent copy without stopping anything.
|
||||
- **Postgres**: `pg_dump evection > evection-backup.sql` on whatever schedule suits
|
||||
you; no downtime needed.
|
||||
|
||||
Either way, also back up your `.env` file — it's the only copy of `SECRET_KEY`,
|
||||
and losing it invalidates every existing session and signed cookie.
|
||||
|
||||
## Upgrading
|
||||
|
||||
```bash
|
||||
cd /opt/evection/app
|
||||
sudo -u evection -H git pull # or: extract the new release over this directory
|
||||
sudo -u evection -H /opt/evection/venv/bin/pip install .
|
||||
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
|
||||
/opt/evection/venv/bin/python manage.py migrate
|
||||
sudo -u evection -H env DJANGO_SETTINGS_MODULE=config.settings.prod \
|
||||
/opt/evection/venv/bin/python manage.py collectstatic --noinput
|
||||
sudo systemctl restart evection-gunicorn evection-celery-worker evection-celery-beat
|
||||
```
|
||||
|
||||
Bump `EVECTION_PWA_CACHE_VERSION` in `.env` whenever a release changes cached
|
||||
static assets (CSS/JS/icons) — it's baked into the service worker's cache name, so
|
||||
changing it forces every installed PWA to drop its old cache instead of serving
|
||||
stale assets after the upgrade.
|
||||
Reference in new issue
Block a user