Sites

Sites (also known as tenants) are isolated cloud environments within Taruvi Cloud. Each site represents a separate workspace with its own database schema, users, and data, providing complete data isolation.

Slug-Based URLs

All site endpoints now use slug-based URLs (e.g., /api/cloud/sites/production-site/) instead of UUID-based URLs. Slugs are human-readable identifiers automatically generated from the site name. UUIDs are still supported for backward compatibility.

Overview

A site is a fully isolated cloud environment that belongs to an organization. Sites enable:

Multi-tenancy: Each site has its own database schema
Data Isolation: Complete separation of data between sites
Custom Configuration: Site-specific settings and environments
Domain Management: Multiple domains can point to a single site

Key Features

Schema-Based Multi-Tenancy

Sites use django-tenants for schema-based isolation:

Each site gets its own PostgreSQL schema
Data is completely isolated at the database level
Sites can have different configurations and settings

Environment Types

Sites can be configured for different purposes using the environment field:

production: Live production environment
staging: Pre-production testing environment
development: Development and testing
testing: Automated testing environment

Automatic Environment Prefixing

Site names are automatically prefixed based on the deployment environment to ensure clear separation between test, staging, and production sites. This matches the behavior of frontend workers and enables proper ALB routing.

How It Works:

The system reads the ENVIRONMENT configuration variable and automatically prepends a prefix to site names during creation:

Environment	Prefix	Example Input	Actual Site Name	Schema Name
`production`	None	`customer-portal`	`customer-portal`	`customer_portal`
`dev`	`dev-`	`customer-portal`	`dev-customer-portal`	`dev_customer_portal`
`test`	`test-`	`customer-portal`	`test-customer-portal`	`test_customer_portal`
`staging`	`staging-`	`customer-portal`	`staging-customer-portal`	`staging_customer_portal`

Example:

When you create a site in a development environment:

POST /api/cloud/organizations/acme-corp/sites/
{
  "name": "customer-portal",
  "description": "Customer portal site"
}

Response:

{
  "name": "dev-customer-portal",
  "schema_name": "dev_customer_portal",
  "slug": "dev-customer-portal",
  ...
}

Benefits:

Clear Separation: Easily distinguish between environments by site name
ALB Routing: Sites with test- prefix automatically route to test-console
Prevents Confusion: Impossible to accidentally mix test and production sites
Automatic: No manual configuration needed - prefix is applied based on environment
Consistent: Matches frontend worker prefixing behavior

Important Notes:

Prefix is applied only during creation, not on updates
If you manually provide a prefixed name (e.g., dev-mysite), it won't be duplicated
Production environment has no prefix to keep production site names clean
Schema names follow the same pattern with underscores instead of hyphens

Site Settings

Each site can store custom configuration in the site_settings JSON field:

{
  "site_settings": {
    "feature_flags": {"analytics": true},
    "branding": {"primary_color": "#007bff"},
    "integrations": {"stripe_enabled": true}
  }
}

Flexible Configuration

Each site can have:

Custom settings stored in JSON format
Multiple domains pointing to it
Organization association
Active/inactive status for soft deletion

Using Sites

Creating a Site

Create a new site within an organization:

POST /api/cloud/organizations/{org_slug}/sites/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "name": "Production Site",
  "description": "Main production environment",
  "environment": "production",
  "site_settings": {
    "feature_flags": {
      "analytics": true,
      "notifications": true
    }
  }
}

Environment Prefix

The site name will be automatically prefixed based on your deployment environment (e.g., dev-, test-, staging-). Production environments have no prefix. See Automatic Environment Prefixing for details.

Example:

POST /api/organizations/acme-corp/sites/

Response:

{
  "uuid": "750e8400-e29b-41d4-a716-446655440000",
  "slug": "production-site",
  "name": "Production Site",
  "description": "Main production environment",
  "schema_name": "production_site",
  "environment": "production",
  "is_active": true,
  "site_settings": {
    "feature_flags": {
      "analytics": true,
      "notifications": true
    }
  },
  "created_at": "2024-01-15T10:30:00Z",
  "modified_at": "2024-01-15T10:30:00Z"
}

Listing Sites

Get all sites within an organization:

GET /api/cloud/organizations/{org_slug}/sites/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

GET /api/organizations/acme-corp/sites/

Query Parameters:

environment: Filter by environment type (production, staging, development, testing)
is_active: Filter by active status
- true or 1: Only active sites (default)
- false or 0: Only inactive sites
- all or *: All sites regardless of status
search: Search by name or schema_name
ordering: Sort results (e.g., name, -created_at, updated_at)

Retrieving Site Details

Get details of a specific site:

GET /api/cloud/sites/{slug}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

GET /api/cloud/sites/production-site/

Updating a Site

Update site configuration:

PUT /api/cloud/sites/{slug}/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "name": "Production Site - Updated",
  "description": "Updated production environment",
  "is_active": true,
  "site_settings": {
    "feature_flags": {
      "analytics": true,
      "notifications": true,
      "beta_features": false
    }
  }
}

Example:

PUT /api/cloud/sites/production-site/

Deleting a Site

Delete a site permanently (this will drop the database schema):

DELETE /api/cloud/sites/{slug}/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

DELETE /api/cloud/sites/production-site/

Warning: Deleting a site:

Permanently deletes the database schema and all data
Removes all associated domains
Removes all site permissions
Cannot be undone

Soft Delete (Deactivation)

Instead of hard deletion, you can deactivate a site:

PATCH /api/cloud/sites/{slug}/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "is_active": false
}

Example:

PATCH /api/cloud/sites/production-site/
{
  "is_active": false
}

Schema Management

Auto-Generated Schema Names

When creating a site, a schema name is automatically generated from the site name:

Converts to lowercase
Replaces spaces and special characters with underscores
Ensures uniqueness by appending numbers if needed
Must start with a letter or underscore

Examples:

"Acme Production" → acme_production
"Test Site" → test_site
"Test Site" (duplicate) → test_site_1

Manual Schema Names

You can also provide a custom schema name:

POST /api/cloud/organizations/{org_slug}/sites/
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "name": "Custom Site",
  "schema_name": "my_custom_schema"
}

Example:

POST /api/organizations/acme-corp/sites/
{
  "name": "Custom Site",
  "schema_name": "my_custom_schema"
}

Requirements:

Must start with a letter or underscore
Can only contain lowercase letters, numbers, and underscores
Must be unique across all sites

Auto-Generated Features

When creating a site, the following are automatically generated if not provided:

Schema Name: Auto-generated from site name (converted to lowercase with underscores)
Default Domain: If no domains are specified, creates {site-slug}.taruvi.cloud as primary domain
Tenant Seeding: Runs default data seeders to initialize admin users, groups, tags, and permissions

# Example: Create site with minimal fields
POST /api/cloud/organizations/acme-corp/sites/
{
  "name": "My New Site"
}

# Auto-generates:
# - schema_name: "my_new_site"
# - domain: "my-new-site.taruvi.cloud" (primary)
# - Seeds default data in the new schema

Site Configuration

Site Settings

The site_settings field accepts any JSON data for custom configuration:

{
  "site_settings": {
    "feature_flags": {
      "analytics": true,
      "notifications": false
    },
    "branding": {
      "primary_color": "#007bff",
      "logo_url": "https://example.com/logo.png"
    },
    "integrations": {
      "stripe_key": "sk_test_...",
      "sendgrid_api_key": "SG..."
    }
  }
}

Accessing Site Configuration

Retrieve current site configuration:

GET /api/cloud/sites/config/
Authorization: Bearer YOUR_ACCESS_TOKEN

This endpoint returns the configuration for the current tenant based on the domain you're accessing.

Checking Your Permissions

Get your effective permissions on a specific site:

GET /api/cloud/sites/{slug}/privileges/
Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

GET /api/cloud/sites/production-site/privileges/

Response:

{
  "permissions": [
    "access_site",
    "view_site",
    "change_site",
    "manage_site"
  ]
}

This endpoint returns all permissions you have on the specified site, including permissions inherited from organization membership and groups.

Permissions

Sites support the following permissions:

Permission	Description
`view_site`	View site details
`change_site`	Update site settings
`delete_site`	Delete the site
`access_site`	Access the site environment
`manage_site`	Full site management access
`manage_site_users`	Manage users within the site
`admin_site`	Site administrator with full control

Best Practices

Environment Separation: Use different sites for production, staging, and development
- The system automatically prefixes site names based on environment
- Test sites (with test- prefix) automatically route to test-console
- Production sites have no prefix for clean naming
Schema Naming: Use descriptive schema names that indicate purpose
- Schema names are auto-generated from site names
- Environment prefixes are included in schema names (with underscores)
Soft Deletes: Deactivate sites instead of deleting when possible
Settings Management: Store all configuration in site_settings for centralized management
Regular Backups: Implement backup strategies for production sites
Access Control: Assign minimal required permissions to users
Naming Convention: Use clear, descriptive names without manually adding environment prefixes
- ✅ Good: customer-portal (system adds dev- automatically)
- ❌ Avoid: dev-customer-portal (prefix will not be duplicated, but unnecessary)

Use Cases

Multi-Environment Development

Create separate sites for production, staging, and development environments with identical configurations.

White-Label SaaS

Each customer gets their own site with custom branding, settings, and isolated data.

Geographic Isolation

Create separate sites for different regions or countries with region-specific data and compliance.

Feature Testing

Use separate sites to test new features without affecting production environments.

Organizations - Manage sites within organizations
Domains - Configure domains for site access
User Management - Manage site users and access
Permissions - Control site-level access

Overview​

Key Features​

Schema-Based Multi-Tenancy​

Environment Types​

Automatic Environment Prefixing​

Site Settings​

Flexible Configuration​

Using Sites​

Creating a Site​

Listing Sites​

Retrieving Site Details​

Updating a Site​

Deleting a Site​

Soft Delete (Deactivation)​

Schema Management​

Auto-Generated Schema Names​

Manual Schema Names​

Auto-Generated Features​

Site Configuration​

Site Settings​

Accessing Site Configuration​

Checking Your Permissions​

Permissions​

Best Practices​

Use Cases​

Multi-Environment Development​

White-Label SaaS​

Geographic Isolation​

Feature Testing​

Related Features​

Overview

Key Features

Schema-Based Multi-Tenancy

Environment Types

Automatic Environment Prefixing

Site Settings

Flexible Configuration

Using Sites

Creating a Site

Listing Sites

Retrieving Site Details

Updating a Site

Deleting a Site

Soft Delete (Deactivation)

Schema Management

Auto-Generated Schema Names

Manual Schema Names

Auto-Generated Features

Site Configuration

Site Settings

Accessing Site Configuration

Checking Your Permissions

Permissions

Best Practices

Use Cases

Multi-Environment Development

White-Label SaaS

Geographic Isolation

Feature Testing

Related Features