Hosting fepli
This section is for integrators: whoever runs fepli for one or more municipalities on their own infrastructure. It explains what an instance is made of, how to configure it and how to create the first admin. You don't need to know PHP, but you should be at home with Docker, DNS and environment variables.
What you get
fepli comes as a Docker image, not as source code. The image holds the whole application: the public website of the holiday programme, the admin at /admin, the CMS at /cms and the REST API at /api.
The image
ghcr.io/ferienpass/app:general-latest
You run it next to MariaDB and Redis, optionally with Varnish in front, and configure everything with environment variables. You don't build anything, and there is nothing to install inside the container.
Hosting fepli yourself is an enterprise feature. The image is private: fepli gives you a user name and a token to pull it. Write to support@fepli.de to get them.
What an instance is made of
An instance is the fepli image running three times, with a different job each time, plus two services and an optional cache:
| Part | What it does | What runs it |
|---|---|---|
| Web | Serves the website, the admin, the CMS and the API | the fepli image, as it starts by default |
| Worker | Sends e-mails, builds exports and receipts, assigns places by lot, and runs the other jobs that take longer than a page request | the fepli image with IS_WORKER=1 |
| Cron | Runs scheduled jobs: reminders, deadlines, deleting data that has reached its retention period | the fepli image, running php bin/console contao:cron every minute |
| MariaDB | Holds all data: offers, families, applications, payments, the CMS pages | MariaDB 11.2 or newer. fepli runs 12.3. |
| Redis | Holds the queue of background jobs, the sessions, the locks and the settings cache | Redis 8, with persistence switched on |
| Varnish (optional) | Caches pages in front of the web container. fepli tags every page with what it shows and purges exactly those pages when the data changes. | fepli's Varnish image, ghcr.io/ferienpass/varnish |
A request travels like this:
Request path
browser ──HTTPS──▶ your TLS proxy ──HTTP──▶ Varnish ──▶ web ──▶ MariaDB, Redis
browser ──HTTPS──▶ your TLS proxy ──HTTP──────────────▶ web ──▶ MariaDB, Redis
The web container doesn't speak HTTPS, and neither does Varnish, so a proxy of yours terminates TLS in front of them: Caddy, Traefik, nginx or a load balancer.
With or without Varnish
fepli works the same with and without Varnish. What changes is how often the web container has to build a page:
- With Varnish, most page views are answered from the cache, including the admin's lists and the offer pages of the public website. This is how fepli runs its own installations, and what you want when many families use the site at the same time, for example on the day applications open.
- Without Varnish, every page view reaches the web container. That is simpler to run and fine for a small municipality, a staging instance or your own machine.
You choose with one variable: an empty VARNISH_HOST means there is no Varnish, and fepli then sends no purge requests. You can add Varnish later: start it, point your proxy at it and set VARNISH_HOST.
Only fepli's Varnish caches fepli's pages. fepli tells it how long in a
header of its own, and marks those pages private for everybody else, so a
CDN or proxy in front of fepli keeps nothing of them. That also means another
cache can't take Varnish's place.
Requirements
- A container runtime. Docker with Compose v2 is enough for a single server. Kubernetes, Nomad, Dokploy or Coolify work just as well: they run the same image with the same variables.
- An x86 host. The image is built for
linux/amd64. On an Apple Silicon Mac, Docker runs it through emulation, which is fine for trying it out. - A domain per municipality, with DNS you control, and TLS certificates for it. Your proxy usually gets those from Let's Encrypt.
- An SMTP server that may send mail for the sender address you configure. fepli sends login links, confirmations and decision letters by e-mail, so without one nobody can sign in.
- Backups of the database and the uploaded files. See Production.
Two ways to set it up
Decide first whether one installation serves one municipality or several: Single or multi-tenant. Both use the same configuration. Then:
- Local setup: the image on your own machine, with Docker Compose. To try fepli, to train colleagues or to rehearse an update. It takes about fifteen minutes.
- Production: the same image on a server, behind TLS, with persistent volumes, backups and a routine for updates.
Who does what
| fepli | You |
|---|---|
| builds and publishes the image, including security updates of everything inside it | run the containers and the three services |
| publishes the Varnish image with its configuration, if you use it | provide TLS, DNS and outgoing mail |
| documents what changes in a release in the changelog | back up and pull new images; the image migrates the database on start |
| answers questions at support@fepli.de | monitor the instance and keep the services patched |