Multisite and workspaces

One Justflows installation can serve many sites. A workspace (tenant) owns one or more sites, and each site is reached by its own hostname. An unknown host is refused. It is never served as another workspace's site. Manage workspaces under Admin → Platform.

Database choice#

A site can stay on the workspace database, use the current database, or get its own separate database. Shared users cannot split across databases: either every site in the workspace uses the same database, or the workspace uses isolated users. The connection uses the same driver as the installation (PostgreSQL, MySQL, or MariaDB) and is encrypted with the installation secret. Revealing it on Platform writes an audit row and is limited to platform operators.

Users#

• Isolated users. Each site has its own accounts. The same email can exist on another site and is a different person.
• Shared users. One account in the workspace, with a role on each site. Signing in on a site uses that site's role. The session cookie is for that host only, so opening another site does not reuse it.

The first administrator created by the installer is a platform operator. Platform operators manage workspaces, suspension, and database placement. A person who signs up for a site is only an administrator of that site.

The platform site and customer sites#

The installation's first site is the platform site. Updates, diagnostics, Platform, the server cache, the CDN connection, and installation-wide settings (static export and responsive-image sizes, which are written to .env) live there. A site created later does not show those pages, and its API calls for them are refused. Every site keeps its own content, media, themes, plugins, users, admin URL, and site settings.

• A customer site can still run its own static export, regenerate its images, and purge its own pages at the CDN.
• An MCP key or OAuth sign-in for one site is refused on another. The MCP address shown in the admin is that site's own /api/mcp.
• An administrator of a customer site can delete it under Settings → Delete website by typing its hostname. The platform site cannot be deleted this way.

Hosts, DNS, and TLS#

Store the hostname without a scheme or path (www.example.com, my-site.example.com). Point DNS at this installation and terminate TLS at the reverse proxy or host. Justflows does not issue certificates.

While the installation has exactly one site, localhost still opens that site so an existing install keeps working. After a second site exists, each host must be registered. Add site-a.localhost and site-b.localhost to your hosts file to try two sites locally.

Public signup#

Admin → Platform → Public signup turns on Let visitors create their own workspace and sets the Signup domain. Each signup gets slug.<signup domain> with isolated users, and the visitor becomes that site's administrator. Visitors never enter a database connection. The same screen chooses whether every new signup goes into the current database or into one separate database, whose password is encrypted and not shown again.

POST /api/signup
Content-Type: application/json

{ "email": "ada@example.com", "password": "at-least-12-chars", "displayName": "Ada", "siteName": "Ada's notes", "slug": "ada" }

201 { "ok": true, "hostname": "ada.example.com", "url": "https://ada.example.com", "adminUrl": "https://ada.example.com/admin" }

Operations#

• Suspend a workspace to take its sites offline without affecting any other workspace. Reactivate brings them back.
• Migrations on a separate database run from Admin → Platform or POST /api/platform/databases/:id/migrate. The installation database is migrated on boot as before.
• Deleting a workspace marks it deleted. Dropping its database is a separate confirmation and does not touch other databases. If the drop fails, the error is stored on that connection and other workspaces stay up.
• Deleted websites on Platform removes a suspended or deleted website completely: pages, users, and files. A shared database is not dropped. The same cleanup runs on its own after the number of days set there. 0 keeps deleted websites until you remove them by hand. The platform workspace cannot be removed.

Back up the installation database (for routing) and every separate database on its own. Restore with psql or the mysql client into that same database, then run migrations.

pg_dump --host HOST --username USER --dbname DATABASE > workspace.sql
mysqldump --host HOST --user USER DATABASE > workspace.sql

Files per site#

/uploads only serves a site's own folder on its own host. A static export run from a site crawls that site's hostname and publishes under it, and auto-rebuild queues each site separately. Shared by every site: bundled themes and plugins, Marketplace packages under packages-installed/, and .env.

Adopting this on an existing install#

Migration 0037_tenancy creates a Primary workspace on the current database, attaches the existing site, registers the host from the site URL, and makes the earliest administrator a platform operator. Users stay isolated, which matches accounts that already belong to one site. Add another site from Admin → Platform when you are ready.

Plugins and the API#

A plugin reads the workspace for the current request with ctx.tenancy.current(): the workspace id, site id, hostname, user mode, and database mode. It never includes a database password. Listing, creating, suspending, reactivating, and deleting workspaces needs the platform:tenancy manifest permission. The same operations are on the Management API at /api/manage/v1/tenants for an API key whose user is a platform operator.

const here = await ctx.tenancy.current();
// { tenantId, siteId, hostname, userMode: "isolated" | "shared", databaseMode: "current" | "separate" }

ctx.hooks.gate("workspace.beforeCreate", (event) => {
  if (event.hostname.endsWith(".internal")) event.cancel("That domain is reserved.");
});

Gates workspace.beforeCreate, site.beforeCreate, workspace.beforeSuspend, workspace.beforeReactivate, and workspace.beforeDelete run before the change. Actions workspace.created, site.created, workspace.suspended, workspace.reactivated, and workspace.deleted run after it succeeds. See Hooks.