Chevereto V4 Docs

# Multitenancy

Multitenancy (opens new window) is supported as of version 4.4.0.

It allows hosting multiple isolated Chevereto instances (tenants) in a single installation. Each tenant has its own configuration, users, media, and settings, while sharing the same application codebase. This reduces maintenance and resource consumption.

# System overview

In a multi-tenant setup, Chevereto recognizes and serves multiple tenants. Each tenant:

  • Is identified by a unique tenant ID.
  • Is bound to a hostname.
  • Is resolved at runtime from the incoming request’s hostname.

Tenant metadata is stored in the tenants and tenants_plans database tables. The database is the source of truth for tenant limits and environment settings. The application caches this data in memory and provides a command line interface to manage it.

By design, this system requires encryption because data stored under env columns is encrypted at rest.

Resource sharing and isolation:

  • Database: table prefixing per tenant.
  • Cache: key prefixing per tenant.
  • Storage: no shared local storage. Tenants configure their own “Site storage” and “Upload storage” in application settings.
  • Sessions: only Redis is supported as backend.
  • Tenant ID: unique, up to 16 characters.
  • Tenant hostname: unique, up to 255 characters.

# Enabling multitenancy

Set the following environment variables:

CHEVERETO_ENABLE_TENANTS=1
CHEVERETO_ENCRYPTION_KEY=your_encryption_key

Then, initialize the multi-tenant database system:

app/bin/tenants -C init

# Managing tenant plans

Tenant plans define default limits and environment variables, similar to a template. When a tenant is assigned to a plan, it inherits the plan’s limits and environment, which the tenant can still override.

  • Use limits to define resource constraints.
  • Use env to set environment variables (values are stored encrypted).

# Adding a tenant plan

Use plan:add. Pass the plan ID and name; limits and env are optional (JSON format).

app/bin/tenants -C plan:add \
    --id 1 \
    --name "Basic Plan" \
    --limits '{"CHEVERETO_MAX_TAGS":"10000"}' \
    --env '{"CHEVERETO_CACHE_TIME_MICRO":"120"}'

This creates plan 1 named “Basic Plan” with a maximum of 10000 tags and a cache time of 120 seconds.

# Listing tenant plans

Use plan:list:

app/bin/tenants -C plan:list

# Deleting a tenant plan

Use plan:delete by plan ID. Affected tenants will lose the inherited plan settings; the system re-caches them automatically.

app/bin/tenants -C plan:delete --id 1

# Managing tenants

A tenant represents an individual Chevereto instance within the multi-tenant setup. Each tenant has a unique hostname and can override its plan’s limits and environment.

  • Use limits for resource constraints.
  • Use env for environment variables (encrypted). Tenant env overrides plan env.

# Adding a tenant

Use add. Provide tenant ID, hostname, and enabled status. plan_id, limits, and env are optional (JSON format).

app/bin/tenants -C add \
    --id 1 \
    --hostname tenant1.example.com \
    --is_enabled 1 \
    --plan_id 1 \
    --env '{"CHEVERETO_CACHE_TIME_MICRO":"90"}'

This creates tenant 1 at tenant1.example.com, enabled, associated with plan 1, and overriding the plan’s cache time to 90 seconds.

# Editing a tenant

Use edit to change hostname, enabled status, plan, limits, or environment.

app/bin/tenants -C edit \
    --id 1 \
    --is_enabled 0

# Deleting a tenant

Use delete by tenant ID:

app/bin/tenants -C delete --id 1

# Caching tenant data

Use cache to regenerate the entire tenant data cache:

app/bin/tenants -C cache

# Application CLI

When running Chevereto in multi-tenant mode, pass the target tenant via the CHEVERETO_ID environment variable.

CHEVERETO_ID=abc app/bin/cli -C <command> <options>

← Operating system →