Tenant Lifecycle

This guide explains what happens when tenants are created, attached, or restored, and what steps you need to take in each scenario.

Creating a New Tenant

Creating a new tenant is the most common operation. It sets up a fresh, fully configured environment.

What Happens Automatically

1. Asset Repository creates a new MongoDB database and registers the tenant
2. A PosCreateTenant event is published to the distribution event hub
3. All services receive the event and run their tenant setup:
   • Import their Construction Kit models
   • Run data migrations
   • Create MongoDB indexes
4. Identity Service creates:
   • 10 default roles (TenantManagement, UserManagement, etc.)
   • TenantOwners group with all default roles
   • API scopes (octo_api, octo_api.read_only)
   • API resource (octoAPI) and identity resources
   • Default identity providers (Google, Microsoft — disabled; system tenant only). Child tenants receive an OctoTenant provider pointing to the parent tenant instead.

Steps

# 1. Ensure you are in the system tenant context
octo-cli -c Config -tid "octosystem" -isu "https://localhost:5003/" -asu "https://localhost:5001/"
octo-cli -c LogIn -i

# 2. Create the tenant
octo-cli -c Create -tid "my-project" -db "my_project_db"

# 3. Grant yourself access to the new tenant (from system tenant)
octo-cli -c ProvisionCurrentUser -ttid "my-project"

# 4. Switch to the new tenant context
octo-cli -c Config -tid "my-project"
octo-cli -c LogIn -i

# 5. Configure identity providers (optional)
octo-cli -c AddAzureEntryIdIdentityProvider \
  -n "Corporate Azure AD" \
  -t "<azure-tenant-id>" \
  -cid "<client-id>" \
  -cs "<client-secret>" \
  -e true

# 6. Create groups and assign roles (optional)
octo-cli -c CreateGroup -n "Operators" -rids "DashboardViewer,ReportingViewer"

# 7. Import your Construction Kit model
octo-cli -c ImportCk -f "./my-model.yaml" -w

info

Step 3 (ProvisionCurrentUser) is critical. Without it, you cannot access the new tenant because you have no allowed_tenants claim for it.

Attaching an Existing Database

Attach registers an existing MongoDB database as a tenant. This is used when:

• A database was previously detached
• A database was created outside of OctoMesh
• Moving a database from one OctoMesh instance to another

What Happens Automatically

1. Asset Repository registers the existing database as a tenant
2. Unlike create, attach does not trigger full initialization — the database is assumed to be already set up

Steps

# 1. From the system tenant context
octo-cli -c Config -tid "octosystem"
octo-cli -c LogIn -i

# 2. Attach the database
octo-cli -c Attach -tid "restored-tenant" -db "existing_database_name"

# 3. Clear the tenant cache (forces all services to re-initialize)
octo-cli -c ClearCache -tid "restored-tenant"

# 4. Grant yourself access (if not already present)
octo-cli -c ProvisionCurrentUser -ttid "restored-tenant"

warning

If you attach a database from a different OctoMesh installation, you may need to update the system CK model:

octo-cli -c UpdateSystemCkModel -tid "restored-tenant"

Restoring from a Backup

Restoring recovers a tenant's data from a backup file. The backup includes all MongoDB data (CK models, runtime entities, identity data).

Important Considerations

• The restore operation overwrites the target database
• You must create or attach the tenant first
• After restore, you need to clear the cache so services pick up the restored data
• If the backup came from a different OctoMesh version, CK model migrations may run on first access
• Identity data (users, roles, groups, providers) is included in the backup

Steps

# 1. From the system tenant context
octo-cli -c Config -tid "octosystem"
octo-cli -c LogIn -i

# 2. Create the tenant first (sets up infrastructure)
octo-cli -c Create -tid "restored-tenant" -db "restored_tenant_db"

# 3. Grant yourself access before restore (identity data will be overwritten)
octo-cli -c ProvisionCurrentUser -ttid "restored-tenant"

# 4. Restore from backup (overwrites the database created in step 2)
octo-cli -c Restore \
  -tid "restored-tenant" \
  -db "restored_tenant_db" \
  -f "./backup.tar.gz" \
  -w

# 5. Clear tenant cache (critical — services must reload the restored data)
octo-cli -c ClearCache -tid "restored-tenant"

# 6. Re-provision yourself (restore may have overwritten your mapping)
octo-cli -c ProvisionCurrentUser -ttid "restored-tenant"

caution

If the backup's original database name differs from the target, specify the old name:

octo-cli -c Restore \
  -tid "restored-tenant" \
  -db "new_database_name" \
  -f "./backup.tar.gz" \
  -oldDb "original_database_name" \
  -w

Restore from a Different OctoMesh Instance

When restoring from a backup taken on a different OctoMesh installation:

# After the standard restore steps above:

# Update system CK model to current version
octo-cli -c UpdateSystemCkModel -tid "restored-tenant"

# Clear cache again
octo-cli -c ClearCache -tid "restored-tenant"

# Verify identity providers are correct (may need reconfiguration)
octo-cli -c Config -tid "restored-tenant"
octo-cli -c LogIn -i
octo-cli -c GetIdentityProviders

Creating a Backup

# From the system tenant context with Bot Services configured
octo-cli -c Config -tid "octosystem" -bsu "https://localhost:5009/"
octo-cli -c LogIn -i

# Dump the tenant
octo-cli -c Dump -tid "my-project" -f "./my-project-backup.tar.gz"

The backup is created as a background job. The CLI waits for completion and downloads the file.

Deleting a Tenant

danger

Deleting a tenant permanently removes the MongoDB database and all its data. This action cannot be undone.

octo-cli -c Delete -tid "my-project"

Cleaning a Tenant

Cleaning resets a tenant to factory defaults by removing all CK models (except system) and all runtime entities, while keeping the database:

octo-cli -c Clean -tid "my-project"

Summary of Operations

Operation	Creates DB	Initializes Config	Preserves Data	Use When
Create	Yes	Yes	N/A	Setting up a fresh tenant
Attach	No	No	Yes	Re-registering an existing database
Restore	No (needs Create first)	Overwritten	Backup data	Recovering from a backup
Clean	No	Partial reset	No	Resetting to factory defaults
Delete	Drops DB	N/A	No	Permanently removing a tenant