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.

Creating a workspace also gives its first administrator a Subscriber account on the platform site, used for billing, and records it as the workspace owner. An existing account with the same email is reused unchanged. Owners manage their workspaces and sites from their account page at /account.

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.

A hostname only routes while it is active. Hostnames an operator adds on a website page are active straight away. A domain a website connects itself is served only after it is verified; see Custom domains.

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. Suspension starts its retention clock. Reactivate brings the sites back and stops the clock.
• 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. The cleanup also removes the workspace's plugin tables, queued jobs, uploads, and domains, and retries any step that fails. Plugins can hold it back with the workspace.beforePurge gate and hear workspace.purged afterwards. Shop keeps orders, payments, and cancelled subscriptions.

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

Limits and features#

Platform operators cap sites per workspace, and users, content, media, private files, and total storage per website, and can turn admin features off per website. Platform → Defaults sets what new workspaces and websites start with. See Limits and storage.

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 is installed on the main site, which turns on Allow on other sites for each plugin it shares. Another site can then activate or deactivate it, and always runs the version the main site installed. Activating it on the main site creates its tables in every site database. Another site cannot install, update, or remove plugins.

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. These operations, and setting limits with ctx.quotas.set, run only on the installation's root site and are refused whenever an AI agent, API key, or connected app is behind the call. ctx.tenancy.siblingSites() lists the active sites of the current workspace from any of them, without seeing other workspaces.

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. tenancy.workspaceCreated runs with workspace.created and adds the first administrator's email; only plugins with platform:tenancy may listen. See Hooks.