Private
Public Access
Make the reverse proxy a required, pluggable part of every deployment
gunicorn previously only ever bound to a Unix socket, which assumes the reverse proxy is nginx running on this same host — it can't be reached by a proxy on a different machine at all (e.g. Nginx Proxy Manager on its own box), which is this project's actual deployment target. Switch gunicorn to listening on a plain TCP address instead, controlled by a new EVECTION_GUNICORN_BIND setting in .env. install.sh now asks whether the proxy is local or remote and picks a sensible bind default either way (127.0.0.1:8000 vs 0.0.0.0:8000, with a reminder to firewall the port in the remote case), and no longer tries to automate nginx/certbot itself — docs/install.md's new "Reverse proxy" section covers both shapes instead, since which proxy and where it runs is the operator's choice, not something this script should assume or set up. upgrade.sh's health check now curls the TCP bind instead of the old socket path. Also add WhiteNoise so gunicorn serves /static/ itself: the old approach (nginx aliasing the staticfiles directory on disk) silently breaks the moment the proxy isn't on this host and can't see this filesystem. nginx.conf.example's own /static/ alias becomes an optional same-host perf optimization rather than a requirement. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
62702e13e3
commit
21c33e8188
7 files changed
+157
-91
No files matched your search
+61
-26
@@ -1,9 +1,16 @@
|
||||
# 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.
|
||||
(gunicorn), and a Celery worker + beat scheduler for background feed polling.
|
||||
There's no Docker image for v1 — everything below runs directly on the host.
|
||||
|
||||
**A reverse proxy in front of gunicorn is required, always** — Evection has no
|
||||
TLS support of its own and assumes one is terminating HTTPS for it (see "Reverse
|
||||
proxy" below). It can be nginx/Caddy/Traefik running on the same host, or
|
||||
something like Nginx Proxy Manager running on an entirely different host/VM —
|
||||
`scripts/install.sh` doesn't set one up for you, since which one and where it
|
||||
runs is up to you; it just leaves gunicorn listening on a TCP address for that
|
||||
proxy to reach.
|
||||
|
||||
Both SQLite and PostgreSQL are fully supported. Steps that differ are marked
|
||||
**SQLite** / **Postgres**; everything else applies to both.
|
||||
@@ -32,9 +39,11 @@ run at all until a tag exists.
|
||||
## Quick install
|
||||
|
||||
Once the prerequisites below are in place, `scripts/install.sh` automates
|
||||
everything from "create a system user" through "systemd units are running" —
|
||||
and optionally nginx + a Let's Encrypt certificate too. It's interactive
|
||||
(asks for your domain and database choice) and safe to re-run.
|
||||
everything from "create a system user" through "systemd units are running",
|
||||
including asking where your reverse proxy will run so it can set up gunicorn's
|
||||
listen address accordingly. It's interactive (asks for your domain, database
|
||||
choice, and proxy location) and safe to re-run. It does **not** set up the
|
||||
proxy itself — see "Reverse proxy" below for that, once this finishes.
|
||||
|
||||
```bash
|
||||
sudo mkdir -p /opt/evection
|
||||
@@ -61,14 +70,16 @@ and 4 below first — prerequisites and what `.env` controls.
|
||||
- **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
|
||||
- A reverse proxy, already running or that you're about to set up — on this
|
||||
host or a different one (see "Reverse proxy" below)
|
||||
- A domain name pointed at wherever that proxy terminates TLS, if you want
|
||||
this reachable outside your LAN
|
||||
|
||||
Debian/Ubuntu example for the non-Python pieces (swap `python3.13-venv` for
|
||||
whatever `python3 --version` reports on your system):
|
||||
|
||||
```bash
|
||||
sudo apt install redis-server nginx python3.13-venv
|
||||
sudo apt install redis-server python3.13-venv
|
||||
# Postgres only:
|
||||
sudo apt install postgresql
|
||||
```
|
||||
@@ -129,11 +140,15 @@ At minimum, set the following in `.env`:
|
||||
sudo -u postgres createdb evection -O evection
|
||||
```
|
||||
- `REDIS_URL` — `redis://localhost:6379/0` is fine for a single-host install
|
||||
- `EVECTION_GUNICORN_BIND` — the `address:port` gunicorn listens on; see
|
||||
"Reverse proxy" below for how to pick this
|
||||
|
||||
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.
|
||||
HSTS, and a Content-Security-Policy header on top of the base settings, and
|
||||
serves static files itself via WhiteNoise rather than relying on the proxy to
|
||||
have filesystem access to this host — see `config/settings/prod.py` if you need
|
||||
to adjust any of that.
|
||||
|
||||
## 5. Initialize the database and static files
|
||||
|
||||
@@ -192,28 +207,47 @@ sudo systemctl status evection-gunicorn evection-celery-worker evection-celery-b
|
||||
sudo journalctl -u evection-gunicorn -f
|
||||
```
|
||||
|
||||
## 7. nginx
|
||||
## 7. Reverse proxy
|
||||
|
||||
Copy `docs/deploy/nginx.conf.example` to `/etc/nginx/sites-available/evection`,
|
||||
adjust `server_name` and the certificate paths, then enable it:
|
||||
gunicorn only ever listens on plain HTTP, on the `EVECTION_GUNICORN_BIND`
|
||||
address you set in step 4 — it never terminates TLS itself. A reverse proxy
|
||||
in front of it is not optional: it's what the setup wizard, login, and every
|
||||
other page actually get reached through. Two shapes this takes:
|
||||
|
||||
**Proxy on the same host as Evection.** Set `EVECTION_GUNICORN_BIND=127.0.0.1:8000`
|
||||
(install.sh's default when you say the proxy is local) so gunicorn isn't
|
||||
reachable from outside this machine at all — only the proxy, listening on
|
||||
80/443, is. `docs/deploy/nginx.conf.example` is a working nginx config for
|
||||
this case; copy it into place and get a certificate the usual way:
|
||||
|
||||
```bash
|
||||
sudo cp docs/deploy/nginx.conf.example /etc/nginx/sites-available/evection
|
||||
# edit it: server_name, and the proxy_pass port if you didn't use 8000
|
||||
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.
|
||||
**Proxy on a different host or VM** (Nginx Proxy Manager, a Caddy box, a
|
||||
container host, etc.). Set `EVECTION_GUNICORN_BIND=0.0.0.0:8000` (or to this
|
||||
host's specific IP) so the proxy can actually reach gunicorn over the
|
||||
network, then **firewall that port to only accept connections from the
|
||||
proxy's host** — gunicorn itself has no auth in front of it, so it must
|
||||
never be reachable from the open internet directly. Point the proxy's
|
||||
upstream/forward target at `this-host:8000`, and make sure it forwards
|
||||
`X-Forwarded-Proto` (whatever sets up TLS passthrough/termination normally
|
||||
handles this, but double-check — see the next paragraph for why it matters).
|
||||
Whichever proxy you use, `docs/deploy/nginx.conf.example`'s `location /`
|
||||
block shows the three headers that need forwarding either way.
|
||||
|
||||
Either way, the proxy must set `X-Forwarded-Proto: https` on requests it
|
||||
forwards once it's terminating TLS — Evection's `prod` settings
|
||||
(`SECURE_PROXY_SSL_HEADER` in `config/settings/prod.py`) trust that header to
|
||||
know the original request was HTTPS, which is what keeps `SECURE_SSL_REDIRECT`
|
||||
from causing a redirect loop. Plan to have TLS working end-to-end 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
|
||||
|
||||
@@ -257,9 +291,10 @@ Equivalent by hand:
|
||||
|
||||
```bash
|
||||
cd /opt/evection/app
|
||||
sudo -u evection -H git fetch --tags --force
|
||||
LATEST_TAG="$(sudo -u evection -H git tag --sort=-creatordate | head -n1)"
|
||||
sudo -u evection -H git checkout --detach "$LATEST_TAG"
|
||||
git fetch --tags --force
|
||||
LATEST_TAG="$(git tag --sort=-creatordate | head -n1)"
|
||||
git checkout --detach "$LATEST_TAG"
|
||||
chown -R evection:evection /opt/evection/app
|
||||
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
|
||||
|
||||
Reference in new issue
Block a user