Workspaces, instances and hosting
Archestack is usually rolled out by an implementation partner: a company that builds an app on Archestack and delivers it to its clients. This page follows one example throughout: a software company that has built an app for testing laboratories, the companies that analyse food, water and materials for other businesses. The app follows every sample from intake to certificate, and the software company rolls it out to one laboratory after another. Each laboratory is a client, and each has business customers of its own: the food producers, water companies and manufacturers that send in samples.
Three words carry the rest of this page:
- Client: a company the partner delivers the app to. In this example, each laboratory.
- Workspace: the isolated environment a client works in, with its own app, its own data and its own members. Its technical name is tenant.
- Instance: one running copy of Archestack. It runs one workspace or many.
In short: a client works in a workspace, and a workspace runs on an instance. The sections below cover what a workspace is and what keeps it apart, the two ways to host your clients' workspaces, how a laboratory lets its own customers in, how Archestack itself is hosted, and how a new version of your app reaches every client.
What a workspace is
A workspace is the isolated environment one client works in. It holds the whole app, the data that app works on and the people allowed in, and it is closed off from every other workspace. Every laboratory gets one.
Tenant is the technical name for the same thing. The screens say workspace; the API and the code say tenant, the word behind single-tenant and multi-tenant hosting. Workspace and tenant are not two layers, and neither contains the other: one laboratory has one workspace, and the API calls that workspace a tenant. This page says workspace throughout.
Archestack instance What is inside a workspace
A workspace holds three things:
- Core, a PostgreSQL database that holds the app itself: business entities, pages, business events, script modules, scheduled events, PDF templates, packages, releases, test suites, Data API endpoints and API keys, MCP tokens, branding, app layouts, translations, settings, mail accounts and the outbox, and the preferences and notifications of its users. Passwords and other secrets stored here are encrypted, and API keys and MCP tokens are kept only as a hash.
- Runtime, a PostgreSQL database that holds the business data: the tables and the rows in them, in this example the samples, analyses, results, certificates of analysis and invoices. The Schema Designer shows its structure exactly as it is in the database.
- Members: the people allowed in, each with a role in this workspace. Invitations are sent per workspace.
Because the app lives in Core, two laboratories running the same app each have a copy of their
own. A change made in one workspace stays there until you ship it to the others, which is what
packages are for. A workspace can also have an address of its own, such
as peeters.labapp.example.com. On Archestack's hosting it can be served on a domain
of the company's own as well, such as app.peeters.be: an administrator adds it on
the builder's Domains page and proves it with one DNS record, and the certificate
follows by itself.
What keeps workspaces apart
The API and the background jobs serve every workspace on the instance, but each request and each scheduled job works for exactly one workspace:
- Separate databases. One workspace's pages, business entities and queries cannot reach another workspace's tables.
- One token, one workspace. Every signed-in request carries a signed token that names exactly one workspace, and only that workspace's databases are opened.
- No fallback. A token naming a workspace that does not exist or is suspended is refused, never redirected to another workspace.
- Keys that name their workspace. API keys and MCP tokens carry the name of the workspace they belong to and work only there.
- Jobs that stay in their workspace. Scheduled jobs run inside the workspace that owns them.
- Backups per workspace. Backups, restores and exports cover one workspace's Core and Runtime, so one client's data can be restored or exported without touching another's.
One account, a role per workspace
Accounts belong to the instance, memberships belong to the workspace. A person has one account on an instance, with one email address and one password, and can be a member of several workspaces with a different role in each. The partner's consultants can be admin in the workspace of every laboratory they look after, while a laboratory's staff are members of their own workspace only.
Someone who belongs to several workspaces switches between them from the avatar menu. The switch issues a new token, which opens the other workspace and only that one. Removing someone from one workspace leaves their other memberships alone.
The main workspace and new ones
Every instance creates a main workspace the first time it starts. A company that needs a single environment just works in it. A partner with many clients keeps the main workspace for its own team and creates one workspace per client. A new workspace is created in about a second and starts empty.
Dividing a workspace
Two features divide one workspace further. Neither creates a new environment: both work inside the workspace, on its own Core and Runtime.
- Business units divide it by team, so each team sees the pages and business entities that concern it. They do not hide data rows, so they are not a separation.
- Customer organisations divide it by customer. They are not workspaces of their own. They live inside the laboratory's workspace, not next to it, with no databases of their own: the laboratory's customers use the laboratory's app, what they enter lands in the laboratory's Runtime, and each customer sees only its own rows. More on this below.
Two ways to host your clients
Every workspace runs on an instance: one running copy of Archestack, with its API, its background jobs and a PostgreSQL server that holds the databases of its workspaces. The workspaces on one instance share the instance around them, not each other's databases:
| Each workspace has its own | Shared by the workspaces on one instance | |
|---|---|---|
| The app | Core: pages, business entities, script modules, settings and the rest | The platform version. An upgrade reaches every workspace at once. |
| The data | Runtime: its tables and rows | The PostgreSQL server that holds the databases |
| People | Members, roles and invitations | The accounts: one email address and one password per person |
| Background work | Its scheduled jobs, which run inside the workspace | The background jobs and the job scheduler |
| Modules | The packages it has installed | The Module Store catalogue |
The workspaces on one instance also share its capacity: processor, memory and database connections. For every client, the partner decides whether its workspace gets an instance of its own or shares one with the workspaces of other clients. In both models every client has a workspace of its own with its own Core and Runtime. What differs is how many workspaces share an instance, and so what they share with each other.
One workspace per instance (single-tenant)
Archestack Archestack Archestack Each laboratory gets an instance of its own, with its own API and background jobs, and a workspace with its own Core and Runtime databases. It suits large clients, clients that decide where their data lives and clients that choose when to upgrade. The partner can run these instances, or install one in the laboratory's own cloud account or data centre.
Advantages
- The strongest separation there is. Nothing is shared with other clients, not even the platform.
- Capacity of its own. A busy laboratory never slows down another, and its instance is sized for it alone.
- Upgrades on the client's schedule. Each instance moves to a new platform version when it suits that client.
- The data lives where the client wants it: a region, a cloud account or their own servers.
- A clean ending. Hand the instance over, or shut it down.
Disadvantages
- Every instance has to be run: servers, certificates, backups, monitoring and upgrades, once per client.
- A new version of your app has to be imported into every instance separately.
- Your own staff need an account on every instance they work on.
- The smallest client still needs a full instance.
Several workspaces per instance (multi-tenant)
Archestack
One instance serves many laboratories. Each laboratory is still a workspace of its own, with its
own Core and Runtime databases and, if you like, its own address such as
peeters.labapp.example.com. The instance's administrators create a new workspace in
about a second.
Advantages
- Each client still has its own databases, its own backups and its own version of the app, adapted to how they work.
- Adding a client takes about a second, and a quiet client costs almost nothing: a workspace nobody uses holds no database connections.
- One instance to run, secure and upgrade.
- Your consultants use one account and switch between clients from the avatar menu.
Disadvantages
- Every client moves to a new platform version at the same moment.
- Clients share the instance's capacity, so size it for all of them together. An instance with more than a few dozen workspaces in use at the same time also needs PostgreSQL's connection limit raised above its default of 100.
- A new version of your app is still installed workspace by workspace, from the instance's Module Store or a ZIP.
Side by side
| One workspace per instance | Several workspaces per instance | |
|---|---|---|
| Own databases | Yes, on their own server | Yes, on a shared server |
| Capacity | Per client | Shared |
| Platform version | Per client | Shared |
| Where the data can live | Anywhere, including the client's own cloud | Wherever the partner runs the instance |
| Shipping a new app version | A ZIP imported into each client's workspace | Installed into each client's workspace, from the instance's Module Store or a ZIP |
| Adding a client | A new instance | About a second |
| Cost per client | Higher | Low |
Mixing is normal: small laboratories share an instance, a large laboratory group gets one of its own, and the same packages ship to both. Development, test, acceptance and production are each a workspace of their own. Put development, test and acceptance on one instance and production on an instance of its own, so a platform upgrade reaches acceptance before it reaches production.
Customers inside a client's app
A laboratory has customers of its own: food producers, water companies and manufacturers that send in samples. They want to register the samples they send in and follow each one while the laboratory works on it. One food producer must never see another producer's samples; the laboratory sees them all. The laboratory can let these customers into the app the partner built for it, as customer organisations.
The partner builds the app and chooses the hosting, with either of the two models above. The laboratory does not notice which one, and neither do its customers. The laboratory then invites its customers, or lets them sign themselves up.
A customer organisation is not a workspace and has no databases of its own. It lives inside the laboratory's workspace: the app belongs to that workspace, each customer has members of its own, and everything they enter lands in the laboratory's Runtime database, stamped with the company that wrote it. Each customer sees only its own rows, the laboratory sees all of them, and a customer can have sub-units of its own: a food group, for example, with a sub-unit for each of its factories and one for each production line in a factory. Each unit sees its own rows and those of the units below it. Customers use the app as the laboratory publishes it and do not change it, and each customer's own administrator invites and removes colleagues.
Hosting infrastructure
Archestack ships as one container image that runs both the API and the background jobs: scheduled events, outgoing mail, test suite runs, syncs with other systems and the nightly backups. It scales horizontally: run more copies of the same image behind a load balancer as the number of users grows. The copies coordinate through PostgreSQL, so the scheduled work is shared between them and every job runs once.
Archestack image Archestack image Running more than one copy asks a few things of the infrastructure around it:
- No sticky sessions, but WebSockets must get through. Any copy can answer any request. Live updates (grids that refresh, who else is on a page, notifications) travel over WebSockets only, so a load balancer or network that blocks them leaves the app working without live updates.
- Shared volumes for backups and files. The backups folder and the folder
that holds every workspace's files (uploads, logos, files scripts write) have to be storage
every copy mounts (in Kubernetes, a
ReadWriteManyvolume), or each copy only sees the backups and files it wrote itself. - A startup probe. Copies that start together take turns preparing the databases, and with many workspaces to migrate that takes a while. Give the containers a startup probe rather than a short liveness probe.
- Rate limits are per copy. Three copies allow three times as many requests per caller as one.
- Behind PgBouncer in transaction mode, point
ConnectionStrings__Clusterstraight at PostgreSQL: the copies talk to each other over a PostgreSQL connection that has to stay open.
Next to the containers, an instance needs PostgreSQL 16 and a proxy that handles TLS. It runs
wherever containers run: a single server, a cloud account or a Kubernetes cluster. The partner
can host it, Archestack can host it, or it can run in the client's own infrastructure.
For Kubernetes there is a Helm chart, and an instance can also live under a path of a hostname
another application owns, such as apps.example.com/archestack/.
A new instance has no users. The first person to open it creates the first administrator, so set it up before it can be reached from the internet.
Capacity and sizing has the measured figures: how many people and workspaces an instance serves, and the servers it needs for them. Hosting on AKS installs an instance on Azure Kubernetes Service and keeps it on the newest release by itself; Hosting with Docker does the same on one server.
Getting your app to every client
When every client has its own workspace, each new version of the app has to travel. A package is how it travels:
- Put the tables, business entities, pages, business events, script modules, PDF templates, scheduled events, test suites and app layouts of your app in a package, and export it as a ZIP.
- Import it into the client's workspace. The import shows a plan first, then applies the table changes to the workspace's Runtime database.
- Run the package's test suites there. Tests run in a separate sandbox database and never touch the client's data.
- Publish a release. That is the moment the new pages reach the client's users. A workspace that has never published a release shows its pages as soon as the import finishes.
Some things are set up in each workspace rather than shipped: Data API endpoints and keys, translations, users, roles, business units, branding, mail accounts and connections to other systems. Anything marked public arrives private, so installing a package can never put a client's data on the internet by itself.
On one instance, a module published to the Module Store as public is visible to, and can be installed by, every workspace on it, which saves the export and import. A private listing is visible only to the workspace that published it. Between instances, packages travel as ZIP files.
When the app lives in a git repository, Deployment strategy describes how a pipeline tests it and deploys it to each environment without downtime.
Gotchas
- A platform upgrade reaches every workspace on the instance at once. A client that has to stay on a version needs an instance of its own.
- A new workspace starts empty. Install your packages into it and invite its people; memberships do not carry over from other workspaces.
Where this goes next
Packages covers building and exporting the package you ship to each workspace. The Data API guide shows how a service connects to one workspace with an API key, and Database Backups covers the per-workspace backups.