Enabling multi-tenant mode on self-hosted VeloCMS
Switch from single-blog mode to multi-tenant mode — run multiple independent blogs from one installation, each with their own database and media storage.
Self-hosted VeloCMS ships in single-instance mode by default — one blog, one database, all features. If you want to run multiple independent blogs from one installation (as a small SaaS, an agency hosting client sites, or a family of related blogs), you can switch to multi-tenant mode by changing a single environment variable.
What multi-tenant mode does
In multi-tenant mode, VeloCMS creates a separate PocketBase database for each blog (tenant). Tenant A's posts, members, and settings are completely isolated from Tenant B's. The Master database handles authentication, billing, and the tenant registry. Tenants access their blog at subdomain.yourdomain.com and cannot see each other's data.
Switching from single-instance to multi-tenant mode is a one-way migration. There is no automated rollback. Perform this on a fresh installation or take a full backup before switching.
Prerequisites
- A wildcard DNS record: *.yourdomain.com pointing to your server's IP.
- A wildcard SSL certificate for *.yourdomain.com (Let's Encrypt with Certbot's DNS challenge, or a Cloudflare proxied wildcard).
- Docker Compose installation of VeloCMS with access to the .env file.
Enabling multi-tenant mode
Open your .env file and change VELOCMS_MODE=single to VELOCMS_MODE=multi. Also set NEXT_PUBLIC_PLATFORM_DOMAIN=yourdomain.com (the apex domain — tenants will be served at *.yourdomain.com). Restart the containers: docker compose down && docker compose up -d. The first boot in multi-tenant mode runs the Master database migration automatically.
# .env changes required for multi-tenant
VELOCMS_MODE=multi
NEXT_PUBLIC_PLATFORM_DOMAIN=yourdomain.com
NEXT_PUBLIC_SITE_URL=https://yourdomain.comCreating the first tenant
With multi-tenant mode active, new tenant accounts are created via the signup flow at yourdomain.com/signup, exactly as with the hosted version. The tenant receives a subdomain at their-blog.yourdomain.com. You (as the server operator) can see all tenants from the Master PocketBase admin at :8090/admin — look for the tenants collection.
Tenant isolation guarantees
Each tenant's database is a separate PocketBase instance in its own directory. One tenant's compromised admin account cannot read another tenant's data. API rules on every collection enforce tenant ownership at the database layer — even if application code has a bug, the database rules provide a second line of defence.