Frontend Workers

Frontend Workers enable you to deploy and host static frontend applications on the Taruvi cloud platform. Upload your built React, Next.js, Vue, or any static web application, and deploy to either a Taruvi-hosted subdomain or your own custom domain.

Overview

Frontend Workers provide:

Automated Hosting: Upload a zip or tar file and your application is automatically deployed
Flexible Domain Options: Choose between Taruvi-hosted subdomains (e.g., https://my-app.taruvi.app/) or your own custom domains (e.g., https://app.yourcompany.com/)
Version Control: Track all deployments with build history and easy rollback
HTTPS by Default: All deployments are automatically secured with HTTPS
Zero Infrastructure: No need to manage servers, domains, or SSL certificates

Domain Types

Frontend Workers support two domain types:

Internal Domains (Taruvi-hosted)

Default option - Automatically managed subdomains under *.taruvi.app
Automatic DNS - No DNS configuration required
Unique subdomains - Globally unique slugs (e.g., my-app, dashboard, portal)
Instant deployment - Just upload and your app is live

External Domains (Custom domains)

Your own domain - Use any domain you own (e.g., app.yourcompany.com or yourcompany.com)
Client DNS setup required - You must configure DNS records to point to the Taruvi platform
SSL/TLS - Handled at your CDN/proxy level (not managed by Taruvi)
Full control - Use your branding and domain infrastructure

Environment-Based Domain Prefixing

Frontend Workers automatically prefix subdomains based on the deployment environment to separate test, staging, and production deployments.

How It Works

The ENVIRONMENT configuration variable controls subdomain prefixing:

Production (ENVIRONMENT=production): No prefix applied
- Example: portal.taruvi.app
Staging (ENVIRONMENT=staging): Adds staging- prefix
- Example: staging-portal.taruvi.app
Development (ENVIRONMENT=dev): Adds dev- prefix
- Example: dev-portal.taruvi.app
Testing (ENVIRONMENT=test): Adds test- prefix
- Example: test-portal.taruvi.app

Benefits

Clear Separation: Easily distinguish between environments by URL
Collision Prevention: Test and production workers can have the same base slug without conflicts
Automatic: No manual configuration needed - prefix is applied automatically based on environment
Consistent: Works for both internal (Taruvi-hosted) and external (custom) domains

Examples

When you create a worker with slug dashboard:

Production Environment:

# ENVIRONMENT=production
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "name=Dashboard" \
  -F "slug=dashboard" \
  -F "file=@dashboard.zip"
# Result: dashboard.taruvi.app

Staging Environment:

# ENVIRONMENT=staging
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "name=Dashboard" \
  -F "slug=dashboard" \
  -F "file=@dashboard.zip"
# Result: staging-dashboard.taruvi.app

Custom Domain (Staging):

# ENVIRONMENT=staging
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "name=Portal" \
  -F "slug=portal" \
  -F "is_internal=false" \
  -F "domain=walmart.com" \
  -F "file=@portal.zip"
# Result: staging-portal.walmart.com

Note: You always provide the base slug (e.g., dashboard, portal). The system automatically applies the appropriate environment prefix.

Quick Start

1. Prepare Your Application

Build your frontend application for production:

# React/Next.js example
npm run build

# This typically creates a 'build' or 'dist' folder

2. Create an Archive

Package your built files into a supported format:

# Create a zip file
cd build && zip -r ../my-app.zip . && cd ..

# Or create a tar.gz file
tar -czf my-app.tar.gz -C build .

Supported formats: .zip, .tar, .tar.gz, .tgz

3. Deploy via API

curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "name=My React App" \
  -F "slug=my-app" \
  -F "file=@my-app.zip"

Your application is now live at https://my-app.taruvi.app/

4. Deploy with Custom Domain (Optional)

To deploy to your own custom domain instead:

curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "name=Client Portal" \
  -F "slug=portal" \
  -F "is_internal=false" \
  -F "domain=walmart.com" \
  -F "file=@my-app.zip"

How it works: The system combines your slug with the base domain to create the full domain:

slug=portal + domain=walmart.com = portal.walmart.com
slug=support + domain=example.com = support.example.com

Important:

Before deploying to a custom domain, ensure you've configured DNS records pointing to the Taruvi platform. See Custom Domain Setup for details.
The base domain (e.g., walmart.com) must be provided without any subdomain
Your application will be accessible at https://portal.walmart.com/

Custom Domain Setup

To use a custom external domain, you need to configure DNS records:

DNS Configuration

Point your domain to the Taruvi platform by creating one of these records:

Option 1: CNAME Record (recommended for subdomains)

Type: CNAME
Host: app (or your subdomain)
Value: <TARUVI_CDN_ENDPOINT>
TTL: 3600

Option 2: A Record (for apex domains)

Type: A
Host: @ (or your apex domain)
Value: <TARUVI_IP_ADDRESS>
TTL: 3600

Note: Contact your Taruvi administrator for the correct TARUVI_CDN_ENDPOINT or TARUVI_IP_ADDRESS values for your installation.

SSL/TLS Certificates

SSL certificates for custom domains must be managed at your CDN or proxy level. Taruvi does not provision SSL certificates for external domains.

Domain Restrictions

The following domains are reserved and cannot be used as external domains:

*.taruvi.app - Reserved for Taruvi-hosted subdomains
Any subdomain of your configured FRONTEND_WORKER_BASE_DOMAIN

Domain Validation

Domain format must follow standard DNS naming conventions:

Valid characters: letters, numbers, hyphens, dots
Must have a valid TLD (e.g., .com, .org, .io)
Examples: app.example.com, example.com, dashboard.mysite.io

API Reference

Base URL

Frontend Workers API is available at tenant-level:

https://your-tenant.taruvi.app/api/frontend_workers/

Authentication

All endpoints require JWT authentication. Include your access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

See API Overview for details on obtaining tokens.

Response Format

All API endpoints return responses in a standardized format:

Success Response Structure:

{
  "success": true,
  "message": "Operation successful",
  "status_code": 200,
  "data": { ... }  // Single object or array of objects
}

Paginated Response Structure:

{
  "success": true,
  "message": "Data retrieved successfully",
  "status_code": 200,
  "data": [ ... ],
  "total": 50,
  "page": 1,
  "page_size": 10,
  "total_pages": 5
}

Error Response Structure:

{
  "success": false,
  "message": "Error description",
  "status_code": 400,
  "data": { ... }  // Optional error details
}

Key Fields:

success: Boolean indicating if the request was successful
message: Human-readable message describing the result
status_code: HTTP status code (200, 201, 400, 404, etc.)
data: The actual response data (object, array, or null)
total: Total count of items (for list endpoints)
page: Current page number (for paginated endpoints)
page_size: Number of items per page
total_pages: Total number of pages available

List Frontend Workers

Retrieve all frontend workers for your site.

Endpoint

GET /api/frontend_workers/

Query Parameters

search (optional): Search workers by name
ordering (optional): Order by field (created_at, updated_at, -created_at, -updated_at)
app (optional): Filter by associated app ID

Response

{
  "success": true,
  "message": "Data retrieved successfully",
  "status_code": 200,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My React App",
      "subdomain": "my-react-app",
      "web_url": "https://my-react-app.taruvi.app/",
      "active_build_uuid": "660e8400-e29b-41d4-a716-446655440001",
      "app": "My App"
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 10,
  "total_pages": 1
}

Example

# List all workers
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/

# Search workers by name
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/?search=react

# Filter by app and order by creation date
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/?app=123&ordering=-created_at

Create Frontend Worker

Create a new frontend worker and optionally upload an initial build.

Endpoint

POST /api/frontend_workers/

Request Parameters

name (required): Name for your frontend worker
is_internal (optional): Boolean, defaults to true. Set to false to use custom external domain
domain (optional): Custom base domain (e.g., "walmart.com", "example.com"). Required when is_internal=false
slug (optional): Custom subdomain slug (auto-generated from name if not provided)
app (optional): ID of associated app
file (optional): Build archive file to deploy

Domain Requirements

For internal domains (is_internal=true):
- Uses FRONTEND_WORKER_BASE_DOMAIN (e.g., taruvi.app)
- domain parameter should NOT be provided (automatically uses base domain)
- slug: Combines with base domain to create full domain (e.g., portal.taruvi.app)
For external domains (is_internal=false):
- domain: Required, must be a valid base domain name
- Cannot use *.taruvi.app or any reserved Taruvi domains
- Must follow DNS naming conventions (letters, numbers, hyphens, dots, valid TLD)
- Examples: walmart.com, example.com, my-company.co.uk
- slug: Combines with your custom domain (e.g., slug=portal + domain=walmart.com = portal.walmart.com)
- Client must configure DNS records

Slug Requirements

Format: 3-100 characters, lowercase letters, numbers, and hyphens only
Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ (no leading/trailing hyphens)
Auto-generation: If not provided, automatically generated from the worker name
Uniqueness: The combination of (slug, domain) must be globally unique

Slug Collision Behavior

Explicit slug provided: If the slug is already in use for the specified domain, the request fails with a validation error. You must choose a different slug.
Auto-generated slug: If not provided, the slug is generated from the name. If a collision occurs, a numeric suffix is automatically added (e.g., portal, portal-1, portal-2).

Examples:

User provides slug=helpdesk, is_internal=true and helpdesk.taruvi.app exists → ❌ Error
User provides only name=Helpdesk, auto-generates slug=helpdesk → ✅ Auto-increments to helpdesk-1.taruvi.app if needed

File Requirements

Maximum size: 10MB
Supported formats: .zip, .tar, .tar.gz, .tgz

Response

{
  "success": true,
  "message": "Frontend worker created successfully",
  "status_code": 201,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My React App",
    "subdomain": "my-react-app",
    "web_url": "https://my-react-app.taruvi.app/",
    "active_build_uuid": "660e8400-e29b-41d4-a716-446655440001",
    "app": "My App",
    "latest_build": {
      "uuid": "660e8400-e29b-41d4-a716-446655440001",
      "status": "completed",
      "uploaded_at": "2025-11-10T12:00:00Z"
    },
    "active_build_info": {
      "uuid": "660e8400-e29b-41d4-a716-446655440001",
      "status": "completed",
      "uploaded_at": "2025-11-10T12:00:00Z"
    },
    "created_at": "2025-11-10T12:00:00Z",
    "updated_at": "2025-11-10T12:00:00Z"
  }
}

Examples

# Create internal domain worker with initial deployment (default)
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=Dashboard App" \
  -F "slug=dashboard" \
  -F "file=@dashboard-build.zip"
# Result: https://dashboard.taruvi.app/

# Create internal domain worker without initial deployment
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Portal",
    "slug": "analytics"
  }'
# Result: https://analytics.taruvi.app/

# Create external domain worker with custom domain
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=Client Portal" \
  -F "is_internal=false" \
  -F "domain=portal.clientcompany.com" \
  -F "file=@client-portal.zip"
# Result: https://portal.clientcompany.com/
# Note: Ensure DNS is configured before deployment

# Create external domain worker without initial deployment
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client App",
    "is_internal": false,
    "slug": "app",
    "domain": "walmart.com"
  }'
# Result: https://app.walmart.com/

Error Responses

Slug Collision Error (when providing explicit slug that already exists):

{
  "success": false,
  "status_code": 400,
  "message": "Validation error",
  "data": {
    "slug": ["Slug 'portal' is already in use for domain 'taruvi.app'. Please choose a different slug."]
  }
}

Invalid Domain Format Error:

{
  "success": false,
  "status_code": 400,
  "message": "Validation error",
  "data": {
    "domain": ["Invalid domain format. Domain must follow DNS naming conventions (e.g., 'walmart.com', 'my-company.co.uk')"]
  }
}

Reserved Domain Error (trying to use *.taruvi.app for external worker):

{
  "success": false,
  "status_code": 400,
  "message": "Validation error",
  "data": {
    "domain": ["Cannot use 'taruvi.app' or its subdomains for external workers. Use is_internal=true for workers on taruvi.app."]
  }
}

Missing Domain Error (when is_internal=false but no domain provided):

{
  "success": false,
  "status_code": 400,
  "message": "Validation error",
  "data": {
    "domain": ["Domain is required when is_internal=false (external workers must specify a custom domain)."]
  }
}

Get Frontend Worker Details

Retrieve detailed information about a specific frontend worker.

Endpoint

GET /api/frontend_workers/{uuid}/

Response

{
  "success": true,
  "message": "Frontend worker retrieved successfully",
  "status_code": 200,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My React App",
    "subdomain": "my-react-app",
    "web_url": "https://my-react-app.taruvi.app/",
    "active_build_uuid": "660e8400-e29b-41d4-a716-446655440001",
    "app": "My App",
    "created_by": "user@example.com",
    "modified_by": "user@example.com",
    "latest_build": {
      "uuid": "660e8400-e29b-41d4-a716-446655440001",
      "status": "completed",
      "uploaded_at": "2025-11-10T12:00:00Z"
    },
    "active_build_info": {
      "uuid": "660e8400-e29b-41d4-a716-446655440001",
      "status": "completed",
      "uploaded_at": "2025-11-10T12:00:00Z"
    },
    "created_at": "2025-11-10T12:00:00Z",
    "updated_at": "2025-11-10T12:00:00Z"
  }
}

Example

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/550e8400-e29b-41d4-a716-446655440000/

Update Frontend Worker

Update a frontend worker's configuration or deploy a new build.

Endpoint

PATCH /api/frontend_workers/{uuid}/

Request Parameters

name (optional): Update worker name
slug (optional): Change subdomain (triggers automatic file migration)
app (optional): Change associated app
file (optional): Upload new build

Important Notes

Slug changes: Migrates all existing files to the new subdomain path in S3
Slug collision: If you provide a slug that's already in use for the same domain, the request will fail with a validation error
File uploads: Creates a new build but doesn't activate it automatically
Activating builds: Use the Set Active Build endpoint to activate a specific build

Response

{
  "success": true,
  "message": "Frontend worker updated successfully",
  "status_code": 200,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated App Name",
    "subdomain": "new-subdomain",
    "web_url": "https://new-subdomain.taruvi.app/",
    "active_build_uuid": "660e8400-e29b-41d4-a716-446655440001",
    "app": "My App",
    "created_at": "2025-11-10T12:00:00Z",
    "updated_at": "2025-11-10T14:30:00Z"
  }
}

Example

# Update worker name
curl -X PATCH https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../  \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Dashboard"}'

# Change subdomain
curl -X PATCH https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "new-dashboard"}'

# Upload new build
curl -X PATCH https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@new-version.zip"

Delete Frontend Worker

Delete a frontend worker and all associated resources.

Endpoint

DELETE /api/frontend_workers/{uuid}/

What Gets Deleted

The frontend worker record
All associated builds
All deployment files from storage
Domain mapping (subdomain becomes available for reuse)

Response

{
  "success": true,
  "message": "Frontend worker \"My React App\" and all related data deleted successfully",
  "status_code": 204
}

Example

curl -X DELETE https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../ \
  -H "Authorization: Bearer YOUR_TOKEN"

Set Active Build

Deploy a specific build as the active version of your frontend worker.

Endpoint

PATCH /api/frontend_workers/{uuid}/set-active-build/

Request

{
  "build_uuid": "660e8400-e29b-41d4-a716-446655440001"
}

Validation

Build must exist and belong to this worker
Build status must be "completed"
Build must have an archive file

Process

Downloads the build archive from storage
Clears existing deployment files
Extracts and deploys the archive contents
Updates the active build reference

Response

{
  "success": true,
  "message": "Successfully redeployed and set build 660e8400-e29b-41d4-a716-446655440001 as active build",
  "status_code": 200,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My React App",
    "subdomain": "my-react-app",
    "web_url": "https://my-react-app.taruvi.app/",
    "active_build_uuid": "660e8400-e29b-41d4-a716-446655440001",
    "app": "My App",
    "created_at": "2025-11-10T12:00:00Z",
    "updated_at": "2025-11-10T15:00:00Z"
  },
  "deployment_url": "https://my-react-app.taruvi.app/"
}

Example

curl -X PATCH https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../set-active-build/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"build_uuid": "660e8400-e29b-41d4-a716-446655440001"}'

List Builds

Retrieve all builds for a specific frontend worker.

Endpoint

GET /api/frontend_workers/{worker_uuid}/builds/

Query Parameters

search (optional): Search builds by name
ordering (optional): Order by field (uploaded_at, created_at, -uploaded_at, -created_at)

Response

{
  "success": true,
  "message": "Frontend worker builds retrieved successfully",
  "status_code": 200,
  "data": [
    {
      "uuid": "660e8400-e29b-41d4-a716-446655440001",
      "frontend_worker_name": "My React App",
      "status": "completed",
      "uploaded_at": "2025-11-10T12:00:00Z",
      "created_by_username": "john.doe",
      "created_at": "2025-11-10T12:00:00Z"
    },
    {
      "uuid": "770e8400-e29b-41d4-a716-446655440002",
      "frontend_worker_name": "My React App",
      "status": "completed",
      "uploaded_at": "2025-11-09T10:30:00Z",
      "created_by_username": "john.doe",
      "created_at": "2025-11-09T10:30:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "page_size": 10,
  "total_pages": 1
}

Build Status Values

pending: Upload in progress
completed: Successfully deployed and archived
failed: Deployment failed

Example

# List all builds for a worker
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../builds/

# List builds ordered by upload date
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../builds/?ordering=-uploaded_at

Get Build Details

Retrieve detailed information about a specific build.

Endpoint

GET /api/frontend_workers/{worker_uuid}/builds/{build_uuid}/

Response

{
  "success": true,
  "message": "Build retrieved successfully",
  "status_code": 200,
  "data": {
    "uuid": "660e8400-e29b-41d4-a716-446655440001",
    "frontend_worker_name": "My React App",
    "status": "completed",
    "uploaded_at": "2025-11-10T12:00:00Z",
    "created_by_username": "john.doe",
    "created_at": "2025-11-10T12:00:00Z",
    "updated_at": "2025-11-10T12:00:30Z"
  }
}

Example

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../builds/660e8400.../

Download Build Archive

Download the original archived zip file for a specific build. This is useful for:

Creating backups of your deployments
Reviewing the exact files that were deployed
Deploying the same build to another environment

Endpoint

GET /api/frontend_workers/{worker_uuid}/builds/{build_uuid}/download/

Requirements

Build status must be completed
Build must have an archive file in storage

Response

Content-Type: application/zip
Content-Disposition: attachment; filename="build-{uuid}.zip"
Body: Binary zip file content

Example

# Download build archive
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../builds/660e8400.../download/ \
  -o build-backup.zip

# Verify download
unzip -l build-backup.zip

Error Responses

400 Bad Request - Build not completed:

{
  "success": false,
  "message": "Cannot download build with status \"pending\". Only completed builds can be downloaded.",
  "status_code": 400
}

404 Not Found - Archive doesn't exist:

{
  "success": false,
  "message": "This build does not have an archived file",
  "status_code": 404
}

Delete Build

Delete a specific build and its archived file from storage. This is useful for:

Cleaning up old builds to save storage space
Removing failed or test builds

Endpoint

DELETE /api/frontend_workers/{worker_uuid}/builds/{build_uuid}/

Important Restrictions

⚠️ Cannot delete the active build - You must set a different build as active first
This prevents accidental deletion of the currently deployed version
Protects your ability to redeploy and change subdomains

What Gets Deleted

The build record from the database
The archived zip file from S3 storage

Response

{
  "success": true,
  "message": "Build 660e8400-e29b-41d4-a716-446655440001 and its archive deleted successfully",
  "status_code": 204
}

Example

# Delete an old build (not active)
curl -X DELETE https://your-tenant.taruvi.app/api/frontend_workers/550e8400.../builds/660e8400.../ \
  -H "Authorization: Bearer YOUR_TOKEN"

Error Responses

400 Bad Request - Trying to delete active build:

{
  "success": false,
  "message": "Cannot delete the active build. Please set a different build as active first.",
  "status_code": 400
}

404 Not Found - Build doesn't exist or belongs to different worker:

{
  "success": false,
  "message": "Not found.",
  "status_code": 404
}

Safe Deletion Workflow

If you need to delete the active build:

# 1. List all builds to find another one
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/{worker_uuid}/builds/

# 2. Set a different build as active
curl -X PATCH https://your-tenant.taruvi.app/api/frontend_workers/{worker_uuid}/set-active-build/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"build_uuid": "new-active-build-uuid"}'

# 3. Now you can delete the old build
curl -X DELETE https://your-tenant.taruvi.app/api/frontend_workers/{worker_uuid}/builds/{old-build-uuid}/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Common Use Cases

Deploy Multiple Environments

Create separate workers for development, staging, and production:

# Development
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=App Dev" \
  -F "slug=app-dev" \
  -F "file=@dev-build.zip"

# Staging
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=App Staging" \
  -F "slug=app-staging" \
  -F "file=@staging-build.zip"

# Production
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=App Production" \
  -F "slug=app" \
  -F "file=@prod-build.zip"

Your environments are now available at:

Dev: https://app-dev.taruvi.app/
Staging: https://app-staging.taruvi.app/
Production: https://app.taruvi.app/

Quick Rollback

If you discover issues with your latest deployment:

# 1. List all builds to find the previous version
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/{worker_uuid}/builds/

# 2. Activate the previous build
curl -X PATCH https://your-tenant.taruvi.app/api/frontend_workers/{worker_uuid}/set-active-build/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"build_uuid": "previous-build-uuid"}'

Your application instantly reverts to the previous version.

Continuous Deployment

Integrate with your CI/CD pipeline:

#!/bin/bash
# deploy.sh

# Build the application
npm run build

# Create archive
cd build && zip -r ../release.zip . && cd ..

# Upload new build
curl -X PATCH https://your-tenant.taruvi.app/api/frontend_workers/${WORKER_UUID}/ \
  -H "Authorization: Bearer ${TARUVI_TOKEN}" \
  -F "file=@release.zip"

# Get the new build UUID (from response)
NEW_BUILD_UUID="..." # Extract from response

# Activate the new build
curl -X PATCH https://your-tenant.taruvi.app/api/frontend_workers/${WORKER_UUID}/set-active-build/ \
  -H "Authorization: Bearer ${TARUVI_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"build_uuid\": \"${NEW_BUILD_UUID}\"}"

Change Subdomain

Update your worker's subdomain while preserving all files:

curl -X PATCH https://your-tenant.taruvi.app/api/frontend_workers/{worker_uuid}/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "new-subdomain-name"}'

All files are automatically migrated to the new subdomain path, and your application is immediately available at the new URL.

Build Management and Cleanup

Manage your build history to optimize storage:

# 1. List all builds to see storage usage
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/{worker_uuid}/builds/

# 2. Download important builds for backup before cleanup
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-tenant.taruvi.app/api/frontend_workers/{worker_uuid}/builds/{build_uuid}/download/ \
  -o production-backup-v1.2.3.zip

# 3. Delete old builds (keeping recent ones and backups)
# Note: Cannot delete the active build
curl -X DELETE https://your-tenant.taruvi.app/api/frontend_workers/{worker_uuid}/builds/{old_build_uuid}/ \
  -H "Authorization: Bearer YOUR_TOKEN"

This keeps your storage clean while maintaining backups of critical versions.

White-Labeled Multi-Tenant Deployments

Deploy the same application to multiple client domains with their own branding:

Use Case: As a SaaS agency, you want to deploy a "Customer Portal" application to multiple clients (Walmart, Target, Best Buy), where each client sees their own domain.

# Deploy to Walmart's domain
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=Walmart Customer Portal" \
  -F "slug=portal" \
  -F "is_internal=false" \
  -F "domain=walmart.com" \
  -F "file=@customer-portal.zip"
# Live at: https://portal.walmart.com/

# Deploy same app to Target's domain
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=Target Customer Portal" \
  -F "slug=portal" \
  -F "is_internal=false" \
  -F "domain=target.com" \
  -F "file=@customer-portal.zip"
# Live at: https://portal.target.com/

# Deploy same app to Best Buy's domain
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "name=Best Buy Support" \
  -F "slug=support" \
  -F "is_internal=false" \
  -F "domain=bestbuy.com" \
  -F "file=@customer-portal.zip"
# Live at: https://support.bestbuy.com/

Key Benefits:

Same codebase: Deploy identical applications across multiple client domains
No slug conflicts: The same slug (e.g., "portal") can be used on different domains
Client branding: Each client sees their own domain, not your company's
Isolated deployments: Each deployment is independent - you can update Walmart without affecting Target
Centralized management: Manage all client deployments from a single tenant

Architecture:

Each worker has its own builds and deployment history
Workers can share the same name (e.g., "Customer Portal") but have unique (slug, domain) combinations
Configure your backend to serve tenant-specific data based on the domain
DNS must be configured by each client to point their domain to your Taruvi instance

Configuration

DNS Requirements

For frontend workers to be accessible, your Taruvi instance administrator must configure:

Base Domain: Set via environment variable FRONTEND_WORKER_BASE_DOMAIN (e.g., taruvi.app)
Wildcard DNS Entry: Create a wildcard DNS record pointing to your Taruvi instance:
```
*.taruvi.app  A      <IP_ADDRESS>
*.taruvi.app  CNAME  <CLOUDFRONT_OR_S3_ENDPOINT>
```

This allows any subdomain (e.g., my-app.taruvi.app, dashboard.taruvi.app) to route correctly.

Storage

Frontend workers use cloud storage (S3-compatible) for:

Deployment files: Live application files served to users
Build archives: Compressed archives for version history and quick rollback

All storage is managed automatically by the platform.

Best Practices

Build Preparation

Optimize for Production: Always use production builds (npm run build, yarn build)
Test Locally: Test your build locally before deploying (use serve or similar)
Check File Paths: Ensure all assets use relative paths, not absolute paths
Environment Variables: Bake environment-specific values into your build

Archive Structure

Your archive should contain your build files at the root or in a single root folder:

✅ Good structure:
my-app.zip
├── index.html
├── static/
│   ├── css/
│   └── js/
└── assets/

✅ Also acceptable (automatically handled):
my-app.zip
└── build/
    ├── index.html
    ├── static/
    └── assets/

❌ Avoid nested structures:
my-app.zip
└── project/
    └── build/
        └── index.html

Version Management

Keep History: Don't delete old builds immediately - they enable quick rollback
Test Before Activation: Upload new builds and test before setting them active
Gradual Rollout: Use separate workers for staged rollouts (dev → staging → prod)

Security

Don't Commit Secrets: Never include API keys or secrets in your frontend build
Use Environment Variables: Configure backend URLs and public keys via build-time variables
Regular Updates: Keep your dependencies updated and rebuild regularly

Troubleshooting

Build Status is "Failed"

Possible Causes:

Archive is corrupted or invalid format
Archive exceeds maximum size (10MB)
Unsupported file format

Solution:

Verify your archive can be extracted locally
Check archive format is one of: .zip, .tar, .tar.gz, .tgz
Reduce build size by optimizing assets

Application Not Loading

Possible Causes:

Index.html not at the root of the archive
Assets using absolute paths instead of relative
CORS issues with backend API

Solution:

Ensure index.html is at the archive root (or single root folder)
Configure your build tool to use relative paths
Configure your backend API to allow requests from your frontend worker domain

Slug Already Taken

Error: "Slug 'portal' is already in use for domain 'taruvi.app'. Please choose a different slug."

Cause: You explicitly provided a slug that is already in use for the same domain.

Solution:

Choose a different slug: The (slug, domain) combination must be unique
Let the system auto-generate: If you don't provide a slug, it will be auto-generated from the name and a numeric suffix will be added if needed (e.g., portal-1, portal-2)
Use a different domain: For external workers, you can use the same slug on different domains (e.g., portal.walmart.com and portal.target.com can coexist)

Example:

# This fails if portal.taruvi.app already exists
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Portal", "slug": "portal"}'

# This succeeds - uses different slug
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Portal", "slug": "my-portal"}'

# This succeeds - auto-generates slug with suffix if needed
curl -X POST https://your-tenant.taruvi.app/api/frontend_workers/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Portal"}'
# Auto-generates slug=portal, or portal-1 if portal exists

Cannot Set Active Build

Error: "Build must have status 'completed'"

Solution:

Wait for the build upload to complete
If build is marked as "failed", upload a new build
Verify the build UUID is correct and belongs to this worker

Cannot Delete Build

Error: "Cannot delete the active build. Please set a different build as active first."

Reason: The active build's archive is needed for:

Redeploying when changing subdomains (slug changes)
Quick rollback via the set-active-build endpoint
Disaster recovery if deployment files are corrupted

Solution:

Set a different build as active first using the Set Active Build endpoint
Then delete the old build
See the Safe Deletion Workflow for step-by-step instructions

Limits and Quotas

Resource	Limit
Maximum archive size	10MB
Subdomain length	3-100 characters
Supported formats	`.zip`, `.tar`, `.tar.gz`, `.tgz`
Builds per worker	Unlimited
Workers per site	Unlimited

API Response Codes

All responses include a standardized format with success, message, and status_code fields.

Code	Description	Success Field
200	OK - Request successful	`true`
201	Created - Worker created successfully	`true`
204	No Content - Deletion successful	`true`
400	Bad Request - Invalid data or file	`false`
401	Unauthorized - Authentication required	`false`
403	Forbidden - Permission denied	`false`
404	Not Found - Worker or build not found	`false`
409	Conflict - Subdomain already exists	`false`
413	Payload Too Large - File exceeds 10MB	`false`
500	Internal Server Error - Server error occurred	`false`

Example Error Response:

{
  "success": false,
  "message": "Failed to update frontend worker",
  "status_code": 500,
  "data": {
    "details": "Database connection timeout"
  }
}

Next Steps

Explore the API Overview for authentication details
Check out User Management for managing access
Learn about Organizations and Sites for multi-tenancy

Need help? Check the interactive API documentation at /api/docs/ or contact support.

Overview​

Domain Types​

Internal Domains (Taruvi-hosted)​

External Domains (Custom domains)​

Environment-Based Domain Prefixing​

How It Works​

Benefits​

Examples​

Quick Start​

1. Prepare Your Application​

2. Create an Archive​

3. Deploy via API​

4. Deploy with Custom Domain (Optional)​

Custom Domain Setup​

DNS Configuration​

SSL/TLS Certificates​

Domain Restrictions​

Domain Validation​

API Reference​

Base URL​

Authentication​

Response Format​

List Frontend Workers​

Create Frontend Worker​

Get Frontend Worker Details​

Update Frontend Worker​

Delete Frontend Worker​

Set Active Build​

List Builds​

Get Build Details​

Download Build Archive​

Delete Build​

Common Use Cases​

Deploy Multiple Environments​

Quick Rollback​

Continuous Deployment​

Change Subdomain​

Build Management and Cleanup​

White-Labeled Multi-Tenant Deployments​

Configuration​

DNS Requirements​

Storage​

Best Practices​

Build Preparation​

Archive Structure​

Version Management​

Security​

Troubleshooting​

Build Status is "Failed"​

Application Not Loading​

Slug Already Taken​

Cannot Set Active Build​

Cannot Delete Build​

Limits and Quotas​

API Response Codes​

Next Steps​

Overview

Domain Types

Internal Domains (Taruvi-hosted)

External Domains (Custom domains)

Environment-Based Domain Prefixing

How It Works

Benefits

Examples

Quick Start

1. Prepare Your Application

2. Create an Archive

3. Deploy via API

4. Deploy with Custom Domain (Optional)

Custom Domain Setup

DNS Configuration

SSL/TLS Certificates

Domain Restrictions

Domain Validation

API Reference

Base URL

Authentication

Response Format

List Frontend Workers

Create Frontend Worker

Get Frontend Worker Details

Update Frontend Worker

Delete Frontend Worker

Set Active Build

List Builds

Get Build Details

Download Build Archive

Delete Build

Common Use Cases

Deploy Multiple Environments

Quick Rollback

Continuous Deployment

Change Subdomain

Build Management and Cleanup

White-Labeled Multi-Tenant Deployments

Configuration

DNS Requirements

Storage

Best Practices

Build Preparation

Archive Structure

Version Management

Security

Troubleshooting

Build Status is "Failed"

Application Not Loading

Slug Already Taken

Cannot Set Active Build

Cannot Delete Build

Limits and Quotas

API Response Codes

Next Steps