Single or multi-tenant
One fepli installation can serve one organisation or many. Each organisation is a tenant, with its own domains, admins, settings and data. This page explains the two setups and how to create the first tenant and the first admin, which can only be done on the command line.
Tenants
A tenant is one organisation that uses fepli, such as a municipality with its holiday programme, a club or a library. It has:
- a slug, its machine name, e.g.
elmsbrueck, - a name, e.g. "Ferienpass Elmsbrück", which also appears as the sender of its e-mails,
- its domains,
- its own admins, hosts, families, offers, settings and CMS pages.
All tenants of an installation share one database, and fepli keeps their data apart. A family registered with Elmsbrück doesn't exist for Beispielhausen, and an admin of one tenant can't see the other. In the CMS, which all tenants share, a tenant's super admins edit their own website only: see Give the tenant its website.
There is no separate single-tenant version: every image is the same. Whether an installation is single- or multi-tenant only depends on how many tenants you create, and on whether you switch on the platform console.
| Single-tenant | Multi-tenant | |
|---|---|---|
| Tenants | one | as many as you need |
| Admin | at /admin on the organisation's domain | at /admin on each tenant's domain, plus the platform console |
| Tenants are created | once, on the command line | by global admins in the platform console, or on the command line |
FEPLI_PLATFORM_HOST | not set | the console's domain |
Start with a single tenant if you are unsure. You can add a platform console and more tenants at any time, without moving data.
Domains
Every tenant claims the domains it is reached on. A domain serves one of two things:
- A public host serves the tenant's website, and its admin under
/admin. This is the usual case:https://example.fepli.euandhttps://example.fepli.eu/admin. - An admin host serves only the admin, at the root of the domain, without
/admin. Once a tenant has an admin host, its public hosts stop serving the admin.
Two more domains serve no request at all, so they don't go into TRUSTED_HOSTS: the domain a tenant's e-mails are sent from (the purpose E-Mail-Versand), and the domain replies to its messages arrive at. A tenant enters the latter as a setting of the app Antworten per E-Mail, not as a domain with a purpose: see E-mail replies.
A domain is unique per purpose: the key is the domain together with its purpose. A domain belongs to one tenant, for every purpose, and a tenant names it once per purpose. It answers requests for one purpose only. The one exception is E-Mail-Versand, which may share a domain with another purpose, so a tenant can send from the domain its website is on. Such a domain has two rows, and a request to it reaches the row that is served over HTTP, never the one for sending mail.
A request for a domain no tenant claims is answered with 404, before anything else happens. fepli never falls back to a default tenant. So when you add a domain, add it in two places: to the tenant, and to TRUSTED_HOSTS.
Links in e-mails lead to the domains of the tenant that the account or record they are about belongs to. That holds for sign-in links, invitations, the link to set a new password that an admin sends, the link that confirms a new sign-in address, and every link in an e-mail the worker writes, wherever the e-mail was sent from: the platform console, an API domain or another tenant's domain included. A link into the admin goes to the tenant's admin host where it has one, otherwise to /admin on its public host. A link to the website, such as a family's sign-in link, goes to the public host. APP_BASE_URL is only the fallback, for a link without a tenant or a tenant without a domain for it.
In notification texts, {{ baseUrl }} is the address of the host the e-mail was sent from when that is one of the tenant's public or admin hosts. Sent from any other host, it is the tenant's public host, or its admin host if it has no public host.
Giving a tenant its first admin host moves its admin: from then on, /admin on its public hosts answers 404. Invitations and sign-in links sent before point there and stop working. Send open invitations and sign-in links again once the admin host is in place.
Tenants that embed their offers
A tenant can show its offers on somebody else's website, with the embeds, and have no website of its own in the CMS. Families still come to fepli to apply: the embeds' apply button leads to the offer's page, and from there to sign-in, the family's applications and the payment. Those pages are served on a public host, so a tenant that embeds needs one. Two layouts work:
- One domain. The public host serves the pages families apply on, and the admin under
/admin. Without a website in the CMS there is no home page, so/redirects to the admin's sign-in. - Two domains. A public host for families, and an admin host with the admin at its root.
An admin host alone can't serve families: everything on it is the admin. The embeds would list the offers, but their apply button would lead nowhere. The domain preview on the tenant's page says so.
The embeds are off until the tenant switches them on, with the app Website einbinden under Einstellungen → App-Store. Off, /embed.js answers 404 on every host of the tenant. They also stop answering in maintenance mode, and they don't answer on the platform console.
The platform console
On a multi-tenant installation, the platform console is the place to manage the installation itself. It has a domain of its own, e.g. platform.example.fepli.eu, set with FEPLI_PLATFORM_HOST. It belongs to no tenant and serves only the admin, at the root of the domain.
Only global admins can sign in there. They see:
- Installation → Mandanten: the list of tenants, with Mandant anlegen to create one, and the switch to take a tenant offline. See Creating a tenant.
- Wechseln: stepping into a tenant, to work in its admin.
- CMS in the top bar: the CMS of the tenant they switched into, on its public host, without signing in again. There they administer the whole CMS. The tenant's log under Betroffenenrechte records CMS dieses Mandanten geöffnet, and Admin-Panel in the CMS leads back to the console.
- Installation → Systemwerte: the values all tenants share, such as the installation's sender address (Absenderadresse der Installation) and the maintenance mode, which puts every tenant's website behind a maintenance page. The admin stays reachable, and so do the files it offers for download.
On a new installation without tenants, the console shows nothing but the tenant list, until the first tenant exists.
Run commands in the container
The first admin is created with a console command inside the web container. With Docker Compose, prefix every command on this page with docker compose exec web:
Run a console command
docker compose exec web php bin/console ferienpass:tenant:list
Other platforms have their own way to open a shell in a running container (kubectl exec, the terminal of Dokploy or Coolify, …). Run the commands from /app, which is where the container starts.
On a multi-tenant installation, a command works across all tenants unless you name one: with --tenant=<slug>, which every command accepts, or with the environment variable FEPLI_TENANT for a whole shell session.
Set up a single tenant
Create the tenant with its public hosts, then its first admin:
Create the tenant
php bin/console ferienpass:tenant:create elmsbrueck "Ferienpass Elmsbrück" \
--host=example.fepli.eu \
--host=www.example.fepli.eu
Create the first admin
php bin/console ferienpass:user:create anna.schmidt@example.fepli.eu \
--tenant=elmsbrueck --firstname=Anna --lastname=Schmidt
The second command asks for the password twice. The admin is a super admin of Elmsbrück: they may do everything in its admin, including payments, participants and the CMS, and invite everyone else from there. They sign in at https://example.fepli.eu/admin.
Then give the tenant its website.
Set up several tenants
-
Set
FEPLI_PLATFORM_HOSTto the console's domain, add that domain toTRUSTED_HOSTS, and restart the containers. -
Create a global admin. It belongs to no tenant, so it needs no
--tenant:Create a global admin
php bin/console ferienpass:user:create you@example.org --global-admin -
Sign in at
https://platform.example.fepli.euand create the tenants under Installation → Mandanten → Mandant anlegen, with their domains. Or create them on the command line withferienpass:tenant:create, as for a single tenant. -
Give each tenant its first admin: switch into the tenant and create its admins there, or use
ferienpass:user:createwith--tenant.
Creating a tenant
Mandant anlegen asks for the name, the Kürzel, which can't be changed later, and what the tenant's main address is for:
| Choice | The main address serves |
|---|---|
| Mit Website | the website for families, and the admin under /admin |
| Ohne Website, Bausteine aktivieren on | the pages families apply on, and the admin under /admin; / redirects to the admin's sign-in |
| Ohne Website, Bausteine aktivieren off | the admin, at its root |
Bausteine aktivieren switches the tenant's embeds on from the start. It is suggested for a tenant without a website, which is the one that shows its offers elsewhere, and stays as you set it once you switch it yourself. The embeds read from the API, so API aktivieren is on while they are.
Vorschau Domains below the address shows what each address will answer with, the embeds' script included. For a tenant without a website that embeds, the main address reads Anmeldung für Familien (kein Direktzugang): families reach it through an offer's link, and / leads to the admin's sign-in. Further addresses, such as an admin host or a domain for e-mail, are added in the same form. Offline anlegen keeps the tenant unreachable until you release it.
Global admins have the rights of a super admin in every tenant they switch into. The personal data of the tenant's families stays masked for them by default. Keep their number small.
The commands
- Name
ferienpass:tenant:create- Type
- slug name
- Description
Creates a tenant. The slug is kebab case (
elmsbrueck,bad-musterbach) and can't be changed later.--hostadds a public host,--admin-hostan admin host. Both can be repeated.
- Name
ferienpass:tenant:list- Description
Lists the tenants: slug, name, public and admin hosts, and whether they are online.
- Name
ferienpass:user:create- Type
- Description
Creates a super admin.
--tenant=<slug>names the tenant it belongs to,--global-adminmakes it an admin of the installation instead.--firstnameand--lastnameare optional.
Passwords:
- Run interactively,
ferienpass:user:createasks for the password. - Run without a terminal, e.g. from a script or with
docker compose exec -T, it generates a password and prints it once. Change it after signing in. --password=…works too, but leaves the password in your shell history and the process list. Prefer the prompt.
An e-mail address is unique per tenant, not per installation, so the same person can be an admin of two tenants with two accounts.
Give the tenant its website
The public website of a tenant is a page tree in the CMS, which the admin opens under CMS in its top bar. Each tenant's tree starts at exactly one root page, and the root page says which tenant it belongs to. Until the tenant has a published root page, its domain has no website, though its admin works: / redirects to the admin's sign-in, and the pages families apply on are served in a plain layout that fepli brings along. That is also how a tenant that embeds its offers runs for good. A tenant with only an admin host has no website and needs no root page.
The CMS has no Template Studio: fepli's templates come with the image.
One tenant
On an installation with one tenant, its super admins administer the whole CMS. They create the root page themselves:
- Sign in to the tenant's admin and open CMS in the top bar.
- Go to Seiten and create a page of the type Startpunkt einer Webseite.
- Set its Domainname to the tenant's public host, e.g.
example.fepli.eu, its Sprache tode, and choose the tenant under Mandant. - Publish it, and build the pages below it.
Several tenants
Once an installation has a second tenant, disabled tenants included, the CMS keeps the tenants apart. A tenant's super admins then edit:
- the pages and articles of their own website, the root page included, but not the tenant it belongs to,
- the files in the tenant's own folder,
files/<slug>, e.g.files/elmsbrueck, - the tenant's forms and FAQ categories, with their fields and questions. They can create and delete both, but can't let a form store what it receives in a database table.
A form or FAQ category belongs to one tenant, or to the installation. A new one belongs to the tenant it is created for: the tenant of the super admin who creates it, or, when a global admin creates it, the tenant whose public host the CMS runs on. Global admins hand it to another tenant, or to the installation, under Mandant, a field only they see.
Themes, layouts and front end modules belong to the whole installation, and only global admins change them. A tenant's super admins can't use the content elements Ungefiltertes HTML, Inhaltselement, Artikel and Artikelteaser; elements of these types already on their pages stay, but they can't change them.
A tenant's super admins can't add root pages either. So the first time one of them opens CMS from the tenant's admin, fepli prepares the website:
- An existing root page that names no tenant and carries one of the tenant's public hosts becomes the tenant's.
- Otherwise fepli creates a root page for the tenant: named after it, on its first public host, with the Sprache
deand the first layout of the installation, and not published. - fepli creates the folder
files/<slug>.
The super admin then publishes the root page and builds the pages below it.
Each time one of them opens CMS from the tenant's admin, forms and FAQ categories of the installation become the tenant's where they clearly belong to its website: a FAQ category whose reader page is part of it, and a form that only articles of its website show. Anything less clear stays with the installation, such as a form that another website or a front end module shows: a global admin assigns it, or copies a shared form for each tenant. Forms and FAQ categories from versions before they had a tenant belong to the installation at first, and find their tenant the same way.
A tenant's super admins get these rights on their next request in the CMS after the second tenant was created. Files uploaded before stay in use on their pages, but the file manager shows them only what lies in files/<slug>.