Clone Environment

Feature ID: ENV-004 Category: Environments Required Permission: project.environments.create or project.environments.update API Endpoint: POST /api/v1/environments/{env_id}/clone

Overview

Clone an existing Odoo environment to create a duplicate with optional data sanitization. Cloning creates a complete copy of the database, filestore, and custom modules - perfect for creating staging environments from production or testing new features safely.

Use this feature to:

Create staging environment from production for testing
Duplicate development environment for parallel feature work
Promote staging to production (replace mode)
Create isolated testing environment with anonymized data
Migrate environment to different server

What happens during cloning:

Source environment backed up (database + filestore)
Target environment created or prepared
Data restored to target environment
Sanitization applied (emails, API keys, passwords anonymized)
Target environment verified and ready

Typical Duration: 2-45 minutes depending on database size and filestore

Prerequisites

Required Access

Permission: project.environments.create (for new environment) or project.environments.update (for replace mode)
Organization Membership: Active member of the organization
Source Environment: Must be RUNNING or STOPPED (not deploying)

Infrastructure Requirements

Target Server: Must be RUNNING and have sufficient capacity
Disk Space: Target server needs space for database + filestore
Quota Available: Organization must have quota for new environment (if creating)

Source Environment Status

Source environment must be accessible
Database must be in healthy state
Cannot clone from DEPLOYING, CREATING, or DESTROYING states

Clone Modes

Mode 1: Create New Environment (Same Server)

Creates a brand new environment on the same server as the source.

Use when:

Creating staging from production on same infrastructure
Duplicating development environment for parallel work
Creating test environment with anonymized data

Requirements:

Environment name (must be unique)
Environment type (development, staging, production)
Optional: Custom domain

Result: New environment with cloned data on same server

Mode 2: Replace Existing Environment

Overwrites an existing environment with clone data from source.

Use when:

Promoting staging changes to production
Refreshing development environment with latest production data
Resetting environment to known good state

Requirements:

Target environment ID (must exist in same project)
Confirmation (destructive operation)

Warning: This permanently destroys all data in the target environment!

Result: Existing environment replaced with cloned data

Mode 3: Clone to Different Server

Creates new environment on a different server (cross-server clone).

Use when:

Migrating environment to new infrastructure
Creating regional replica on different data center
Splitting environments across multiple servers

Requirements:

Target server ID (must be RUNNING)
Target server must have sufficient disk space
Environment name and type
Network connectivity between servers

Result: New environment on different server with cloned data

Sanitization Presets

Sanitization protects sensitive production data when cloning to staging/development environments.

Recommended (Default)

Best for: Staging environments that need realistic data without exposing sensitive information

What gets sanitized:

✅ Email servers disabled (prevents accidental email sending)
✅ Mail queue cleared (removes queued outbound emails)
✅ Customer emails anonymized (customer_123@staging.local)
✅ Phone numbers anonymized
✅ API keys cleared (payment gateways, integrations)
✅ Base URL updated to staging domain
✅ Asset bundles cleared (CSS/JS cache)

Preserves:

User accounts and passwords (for login)
Business logic and workflows
Module configurations
Database structure

Use when: Creating staging for UAT, QA testing, feature development

Minimal

Best for: Quick clones where you only need to prevent email sending

What gets sanitized:

✅ Email servers disabled
✅ Mail queue cleared
✅ Asset bundles cleared

Everything else: Kept as-is (including real emails, API keys, phone numbers)

Use when: Internal testing, performance benchmarking, quick duplicates Warning: Contains real production data - use only on secure networks

Full

Best for: Maximum data protection for external contractors or public demos

What gets sanitized:

✅ All email settings (servers, queue, templates)
✅ All customer data (emails, phones, addresses, company names)
✅ All security credentials (API keys, passwords, 2FA)
✅ All automation (crons, scheduled messages)
✅ Base URL updated
✅ Asset bundles cleared

Use when: Demo environments, contractor access, public showcases Note: Slowest sanitization process due to comprehensive data masking

None

Best for: Direct clone with zero modifications (use with extreme caution)

What gets sanitized:

✅ Asset bundles cleared (required for Odoo stability)

Everything else: Exact copy of production

Warning: ⚠️ Contains all production data including:

Real customer emails and phone numbers
Live API keys and payment credentials
Production passwords and authentication tokens
Live mail server configurations

Use when: Disaster recovery, exact production replica, forensic analysis Requirement: Target must be on isolated network with strict access controls

Custom Sanitization Options

Beyond presets, you can customize exactly what gets sanitized:

Email & Communications

Disable mail servers - Prevents outbound email (HIGH priority)
Clear mail queue - Removes queued emails (HIGH priority)
Disable mail templates - Deactivates email templates (MEDIUM priority)

Customer Data

Anonymize emails - Replace with user_ID@staging.local (HIGH priority)
Anonymize phones - Replace with random numbers (HIGH priority)
Anonymize addresses - Clear street addresses (MEDIUM priority)
Anonymize company names - Replace with generic names (LOW priority)

Security

Clear API keys - Remove payment gateway keys, OAuth tokens (HIGH priority)
Update base URL - Change to staging domain (HIGH priority)
Reset passwords - Set all passwords to default (MEDIUM priority)
Disable 2FA - Turn off two-factor authentication (LOW priority)

Automation

Disable crons - Turn off scheduled jobs (MEDIUM priority)
Clear scheduled messages - Remove scheduled emails/SMS (MEDIUM priority)

Required (Always Applied)

Clear asset bundles - Clear CSS/JS cache (REQUIRED for Odoo stability)

How to Clone an Environment

Step 1: Navigate to Clone Dialog

Go to Dashboard → Projects → Select project
Click Environments tab
Find the source environment you want to clone
Click Actions dropdown (⋮ icon)
Select Clone Environment

Clone dialog opens with 3 tabs: Target, Sanitization, Options

Step 2: Configure Target (Tab 1)

Option A: Create New Environment

Select "Create new environment" radio button
Environment Name:
- Auto-generated suggestion: {source-name}-clone-{timestamp}
- Example: production-clone-20241211
- Must be unique within project
Environment Type:
- Development - For active development
- Staging - For UAT and pre-production testing
- Production - For live operations (use with caution)
Server Selection (if cross-server):
- Toggle "Clone to different server"
- Select target server from dropdown
- Shows available disk space: Available: 45 GB / 100 GB
- Validates quota availability
Domain (optional):
- Leave blank for auto-generated subdomain
- Or enter custom domain: staging.mycompany.com

Option B: Replace Existing Environment

Select "Replace existing environment" radio button
Target Environment dropdown:
- Lists all other environments in the project
- Shows environment name, type, and status
- Example: staging (staging) - RUNNING
Confirmation:
- Red warning banner appears:
- "This will destroy the current data in staging!"
- Type environment name to confirm: staging
- Checkbox: "I understand this is destructive"

Critical Warning: Replacing destroys all data in target environment permanently!

Step 3: Choose Sanitization (Tab 2)

Preset Selection

Recommended (selected by default)
- Green badge: "Best for staging"
- Shows 6 options enabled
- Estimated impact: "~247 customer emails will be anonymized"
Minimal
- Blue badge: "Fastest"
- Shows 2 options enabled
- Estimated duration: "~2-3 minutes faster"
Full
- Orange badge: "Maximum protection"
- Shows 15 options enabled
- Estimated impact: "~1,234 records will be sanitized"
None
- Red badge: "⚠️ Use with caution"
- Orange warning: "Contains real production data"
- Checkbox required: "I understand the security risks"

Custom Options (Advanced)

Click "Customize sanitization options" (expand section)
Email & Communications category:
- ☑ Disable mail servers
- ☑ Clear mail queue
- ☐ Disable mail templates
Customer Data category:
- ☑ Anonymize emails (shows estimated count: "~247 emails")
- ☑ Anonymize phones
- ☐ Anonymize addresses
- ☐ Anonymize company names
Security category:
- ☑ Clear API keys (shows found: "3 keys")
- ☑ Update base URL
- ☐ Reset passwords
- ☐ Disable 2FA
Automation category:
- ☐ Disable crons
- ☐ Clear scheduled messages

Impact Preview: "These options will affect approximately 325 records"

Step 4: Configure Options (Tab 3)

Include Filestore

Toggle: Include filestore (attachments, images)
Default: Enabled
Impact:
- Enabled: Clone includes all uploaded files (~2.3 GB)
- Disabled: Database only, no attachments (faster, smaller)
Size Display: "Filestore size: 2.3 GB (estimated +15 minutes)"

Use cases:

Enable: Full environment replica with documents/images
Disable: Structure-only clone, testing migrations, speed

Advanced Options

Database Compression (checkbox):

Compress database during backup (slower backup, faster transfer)
Recommended for cross-server clones
Default: Disabled

Parallel Transfer (checkbox):

Use multiple threads for file transfer (faster, more CPU)
Only for cross-server clones
Default: Enabled

Step 5: Review and Start Clone

Review Summary Panel (right sidebar):

Source: production (RUNNING)
Target: staging-clone-20241211 (NEW)
Server: same-server
Sanitization: Recommended (6 options)
Include filestore: Yes (2.3 GB)

Estimated Duration: ~12 minutes
Estimated Size: 3.8 GB total

Quota Validation:
- Green checkmark: "Quota available"
- Or red X: "Insufficient quota - need 2 GB RAM"
Click "Start Clone" button (bottom-right)

Clone Progress Tracking

Progress Modal

Automatically opens after starting clone. Shows:

Header:

Status badge: "CLONING" (blue, animated)
Progress bar: 45% complete
Elapsed time: "5 min 23 sec"
Estimated remaining: "~7 minutes"

Current Step (highlighted):

Step 5 of 10: Backing Up Database
├─ Dumping PostgreSQL database...
├─ Compressed size: 1.2 GB
└─ Progress: 45% (682 MB / 1.2 GB)

All Steps List:

✅ Pre-checks (2%) - Completed in 2s
✅ Validating (5%) - Completed in 3s
✅ Creating Target (10%) - Completed in 45s
✅ Copying Addons (18%) - Completed in 67s
🔄 Backing Up Database (40%) - In progress...
⏳ Backing Up Filestore (55%)
⏳ Restoring Database (70%)
⏳ Restoring Filestore (85%)
⏳ Sanitizing (95%)
⏳ Verifying (100%)

Logs Section (scrollable):

[2024-12-11 10:45:23] INFO  Starting clone operation
[2024-12-11 10:45:25] INFO  Pre-checks passed
[2024-12-11 10:45:28] INFO  Source environment validated
[2024-12-11 10:46:13] INFO  Target environment created
[2024-12-11 10:47:20] INFO  Custom modules copied (245 MB)
[2024-12-11 10:47:25] INFO  Starting database backup...
[2024-12-11 10:48:30] INFO  Database backup progress: 45%

Actions:

Cancel Clone button (only available at steps 1-3)
Minimize button (continues in background)
Close button (after completion)

Progress Updates: Polls API every 2 seconds for status

Clone Steps Explained

Step 1: Pre-Checks (2%, ~2-5 seconds)

What happens: Validate prerequisites before starting

Checks performed:

Source environment exists and is accessible
Source status is RUNNING or STOPPED
Target server exists (if specified) and is RUNNING
Disk space available on target server
Organization quota available (CPU, RAM, disk, environment count)
User has required permissions
Target configuration is valid

Success Indicator: "Pre-checks passed - ready to clone" Potential Error: "Insufficient disk space on target server - need 15 GB"

Step 2: Validating (5%, ~3-10 seconds)

What happens: Validate source environment health

Validation:

Database is accessible and responsive
Source containers are running properly
Database connection works (test query)
Filestore directory exists (if including)

Success Indicator: "Source environment validated successfully" Potential Error: "Cannot connect to source database"

Step 3: Creating Target (10%, ~30-60 seconds)

What happens: Create or prepare target environment

For create_new mode:

Create new ProjectEnvironment record
Generate unique subdomain
Assign to target server
Create Docker network
Create database container
Create Odoo container (stopped)
Configure Traefik routing

For replace mode:

Stop target environment containers
Destroy existing database
Clear filestore directory
Preserve environment configuration

Success Indicator: "Target environment created: staging-clone-20241211" Potential Error: "Failed to create Docker containers"

Step 4: Copying Addons (18%, ~30-90 seconds)

What happens: Copy custom modules from source to target

Process:

SSH into source server
Locate source addons directory: /opt/paasportal/ENV_ID/addons/
Copy platform addons
Copy organization addons
Copy project repository
Copy additional repositories
Rsync to target server (if cross-server)
Set proper ownership and permissions

Success Indicator: "Copied 245 MB of custom modules" Note: This includes all Git repositories configured for the source

Step 5: Backing Up Database (40%, ~1-10 minutes)

What happens: Create PostgreSQL dump of source database

Command:

docker exec SOURCE_ID_db pg_dump -U odoo -F c -b -v -f /tmp/clone_CLONE_ID.dump DB_NAME

Process:

Connect to source PostgreSQL container
Run pg_dump with custom format (-F c)
Include blobs/large objects (-b)
Verbose output (-v)
Store temporary dump: /tmp/clone_CLONE_ID.dump

Progress Tracking: Monitors file size growth Success Indicator: "Database backed up: 1.2 GB" Duration: Depends on database size (10 MB/second typical)

Step 6: Backing Up Filestore (55%, ~2-15 minutes)

What happens: Backup filestore attachments and uploads

Process:

SSH into source server
Locate filestore: /var/lib/odoo (inside container)
Create tar archive with gzip compression
Store: /tmp/clone_CLONE_ID_filestore.tar.gz
Calculate checksum for verification

Command:

docker exec SOURCE_ID_odoo tar -czf /tmp/filestore.tar.gz -C /var/lib/odoo .

Progress Tracking: File size and compression ratio Success Indicator: "Filestore backed up: 2.3 GB (compressed from 3.1 GB)" Note: Skipped if include_filestore: false

Step 7: Restoring Database (70%, ~2-12 minutes)

What happens: Restore database dump to target

Process:

SSH into target server
Transfer dump file (if cross-server via scp)
Drop existing target database (if exists)
Create fresh database: CREATE DATABASE TARGET_DB
Restore dump using pg_restore

Command:

docker exec TARGET_ID_db pg_restore -U odoo -d TARGET_DB -v -F c /tmp/clone_CLONE_ID.dump

Progress Tracking: Restore output parsing Success Indicator: "Database restored: 1.2 GB" Potential Error: "Restore failed - incompatible PostgreSQL versions"

Step 8: Restoring Filestore (85%, ~1-10 minutes)

What happens: Extract filestore to target container

Process:

Transfer filestore archive to target (if cross-server)
Extract archive into target filestore directory
Set ownership to odoo:odoo
Verify file count matches

Command:

docker exec TARGET_ID_odoo tar -xzf /tmp/filestore.tar.gz -C /var/lib/odoo
docker exec TARGET_ID_odoo chown -R odoo:odoo /var/lib/odoo

Success Indicator: "Filestore restored: 2.3 GB (15,234 files)" Note: Skipped if include_filestore: false

Step 9: Sanitizing (95%, ~10-120 seconds)

What happens: Apply data sanitization SQL commands

Process: For each enabled sanitization option (in order):

Execute SQL command via psql
Count affected rows
Log execution time
Record result (success/failure, row count)

Example commands:

-- Disable mail servers
UPDATE ir_mail_server SET active = false;
 
-- Anonymize emails
UPDATE res_partner
SET email = CONCAT('user_', id, '@staging.local')
WHERE email IS NOT NULL
  AND id NOT IN (SELECT partner_id FROM res_users WHERE active = true);
 
-- Clear API keys
DELETE FROM ir_config_parameter
WHERE key LIKE '%api_key%' OR key LIKE '%secret%' OR key LIKE '%token%';
 
-- Update base URL
UPDATE ir_config_parameter
SET value = 'https://staging-clone.apps.oec.sh'
WHERE key = 'web.base.url';

Results Logged:

✅ disable_mail_servers: 3 servers disabled
✅ clear_mail_queue: 127 emails removed
✅ anonymize_emails: 247 emails anonymized
✅ anonymize_phones: 182 phones anonymized
✅ clear_api_keys: 12 keys removed
✅ update_base_url: URL updated
✅ clear_asset_bundles: 45 bundles cleared

Success Indicator: "Sanitization completed: 7 options applied, 616 records affected" Duration: ~10-20 seconds per option (depends on database size)

Step 10: Verifying (100%, ~5-15 seconds)

What happens: Verify clone completed successfully

Verification:

Database is accessible and healthy
Target environment containers running
Filestore permissions correct
Domain routing configured
Traefik labels applied
Basic health check passes

Command:

docker exec TARGET_ID_odoo odoo-bin --version
curl -f http://localhost:PORT/web/database/selector

Success Indicator: "Clone verification passed" Potential Error: "Target environment not responding"

Visual Feedback

During Clone

Progress Modal:

Status Badge: Blue "CLONING" with animated spinner
Progress Bar: Fills from 0% to 100% with gradient
Current Step: Highlighted in blue with spinner icon
Completed Steps: Green checkmarks
Pending Steps: Gray with clock icon
Logs: Auto-scrolling with color-coded messages (INFO=gray, WARNING=orange, ERROR=red)

Update Frequency: Polls every 2 seconds

Upon Success

Success State:

Status Badge: Green "COMPLETED"
Progress Bar: Full (100%) in green
All Steps: Green checkmarks
Duration Display: "Completed in 12 min 34 sec"

Sanitization Summary:

Sanitization Results:
✅ 3 mail servers disabled
✅ 247 customer emails anonymized
✅ 182 phone numbers anonymized
✅ 12 API keys cleared
✅ Base URL updated

Target Environment Card:
- Name: staging-clone-20241211
- Status: RUNNING
- URL: Clickable link to environment
- Button: "Open Environment" (opens in new tab)

Toast Notification: "Clone completed successfully!" (green, 5 seconds)

Email Notification: Sent to user with summary

Upon Failure

Failure State:

Status Badge: Red "FAILED"
Progress Bar: Stops at last completed percentage
Failed Step: Red X icon with error message

Error Details:

Step Failed: Restoring Database (70%)
Error: pg_restore: [archiver (db)] could not execute query
Details: incompatible_pg_versions

Error Log: Full error stack highlighted in red
Actions Available:
- "Retry Clone" button (same configuration)
- "View Error Details" link (expands full logs)
- "Contact Support" link (opens ticket with logs attached)

Toast Notification: "Clone failed at step 7 - See details" (red, persistent)

Cleanup: Partial target environment is destroyed automatically

Common Errors and Solutions

Problem: "Insufficient Disk Space"

Symptoms:

Error at Step 1: Pre-Checks
Message: "Target server needs 15 GB free, only 8 GB available"

Causes:

Target server disk nearly full
Large database or filestore

Solution:

Navigate to Settings → Servers
Find target server
Option A: Free up space
- Stop unused environments on that server
- Delete old backups
- Clean up Docker images: docker system prune -a
Option B: Select different server with more space
Option C: Disable filestore inclusion (clone database only)
Retry clone operation

Problem: "Quota Exceeded"

Symptoms:

Error at Step 1: Pre-Checks
Message: "Cannot create environment - RAM quota exceeded"

Causes:

Organization quota limit reached
Creating new environment would exceed limits

Solution:

Navigate to Settings → Usage
Check current quota usage:
- CPU: 15/16 cores (94%)
- RAM: 28/32 GB (87%)
- Environments: 9/10 (90%)
Option A: Free up quota
- Stop environments: Stopped envs release quota
- Delete unused environments
Option B: Use replace mode instead of create new
Option C: Upgrade organization plan at Settings → Billing
Retry clone operation

Problem: "Source Database Connection Failed"

Symptoms:

Error at Step 2: Validating
Message: "Cannot connect to source database"

Causes:

Source environment stopped or crashed
Database container not responding
Network connectivity issue

Solution:

Navigate to source environment detail page
Check Status: Must be RUNNING or STOPPED
If STOPPED: Start environment first
If RUNNING but database down:
- Go to Logs tab
- Select "PostgreSQL Container"
- Check for errors (OOM, disk full, corruption)
If database corrupt:
- Restore from recent backup
- Fix corruption issues
Test database:
- Click Terminal tab
- Connect to database container
- Run: psql -U odoo -d DATABASE_NAME -c "SELECT 1;"
Retry clone after database is healthy

Problem: "Cross-Server Transfer Failed"

Symptoms:

Error at Step 7: Restoring Database
Message: "Failed to transfer backup file to target server"

Causes:

Network connectivity issue between servers
Firewall blocking SSH/SCP
Target server SSH credentials invalid
Temporary network interruption

Solution:

Test connectivity from source to target:

ssh root@TARGET_IP "echo 'Connection test successful'"

Check firewall rules:
- Target server must allow SSH (port 22) from source IP
- Verify security group / iptables rules
Verify SSH credentials:
- Navigate to Settings → Servers
- Find target server
- Click Test Connection
- If fails: Update SSH key/password
Retry clone operation
- System will attempt transfer again
- May succeed on retry (temporary network issue)

Problem: "Sanitization SQL Error"

Symptoms:

Error at Step 9: Sanitizing
Message: "Failed to execute sanitization: anonymize_emails"
Specific error: column "email" does not exist

Causes:

Custom Odoo modules modified database schema
Sanitization SQL assumes standard Odoo schema
Database version incompatibility

Solution:

Review error details in clone progress modal
Identify which option failed: anonymize_emails
Retry with different preset:
- Use "Minimal" instead of "Recommended"
- Or use "None" (no sanitization)
Custom sanitization:
- Clone with "None" preset
- Manually sanitize after clone completes
- Write custom SQL for your schema
Report issue if standard Odoo schema:
- Contact support with error details
- May be bug in sanitization SQL

Problem: "Target Environment Not Starting"

Symptoms:

Clone completes but target shows STOPPED
Error at Step 10: Verifying
Message: "Target environment not responding"

Causes:

Odoo container failed to start
Database configuration mismatch
Resource limits too low (OOM crash)
Module dependency issues

Solution:

Navigate to target environment detail page
Click Logs tab
Select "Odoo Container"
Look for startup errors:
- MemoryError: Increase RAM allocation
- ModuleNotFoundError: Missing Python dependency
- DatabaseError: Database connection issue
Fix and restart:
- Adjust resources if needed (RAM, CPU)
- Install missing dependencies
- Redeploy environment
If database corrupt during sanitization:
- Delete target environment
- Retry clone with different sanitization preset

Sanitization Results

After clone completes, view sanitization impact:

Results Summary (in success modal)

Sanitization Applied: Recommended Preset

Email & Communications:
  ✅ Disabled 3 outgoing mail servers
  ✅ Cleared 127 queued emails

Customer Data:
  ✅ Anonymized 247 customer emails
     (Example: john@company.com → user_42@staging.local)
  ✅ Anonymized 182 phone numbers
     (Example: +1-555-1234 → +1-555-9999)

Security:
  ✅ Cleared 12 API keys and secrets
     (Stripe, PayPal, Google OAuth tokens)
  ✅ Updated base URL
     (From: https://app.company.com
      To: https://staging-clone.apps.oec.sh)

Assets:
  ✅ Cleared 45 asset bundles (CSS/JS cache)

Total Records Affected: 616
Sanitization Duration: 23 seconds

Detailed Results (API response)

{
  "sanitization_result": [
    {
      "option_key": "disable_mail_servers",
      "success": true,
      "affected_rows": 3,
      "duration_ms": 45
    },
    {
      "option_key": "anonymize_emails",
      "success": true,
      "affected_rows": 247,
      "duration_ms": 1250
    },
    {
      "option_key": "clear_api_keys",
      "success": true,
      "affected_rows": 12,
      "duration_ms": 89
    }
  ]
}

Clone Time Estimation

Before starting clone, see estimated duration:

Factors Affecting Duration:

Database Size (largest factor)
- Small (less than 100 MB): +1-2 minutes
- Medium (100 MB - 1 GB): +5-10 minutes
- Large (1-5 GB): +15-30 minutes
- Very Large (5+ GB): +30-60+ minutes
Filestore Size
- None (disabled): 0 minutes
- Small (less than 500 MB): +1-3 minutes
- Medium (500 MB - 2 GB): +5-10 minutes
- Large (2+ GB): +10-20+ minutes
Server I/O Performance
- SSD: Baseline
- HDD: +50% time
- Network storage: +100% time
Cross-Server Clone
- Same datacenter: +10-20% time
- Different datacenter: +50-100% time
- International transfer: +100-200% time
Sanitization Complexity
- None: +5 seconds
- Minimal: +10-15 seconds
- Recommended: +20-40 seconds
- Full: +60-120 seconds

Estimation Formula:

Total Time = Base (30s)
           + Database Transfer (size / 10 MB/s)
           + Filestore Transfer (size / 20 MB/s)
           + Cross-Server Overhead (if applicable)
           + Sanitization (10-120s)

Example Estimates:

Database	Filestore	Mode	Preset	Estimated Time
100 MB	500 MB	Same server	Recommended	~3-5 minutes
500 MB	1 GB	Same server	Recommended	~8-12 minutes
2 GB	3 GB	Same server	Full	~25-35 minutes
500 MB	1 GB	Cross-server	Minimal	~12-18 minutes
100 MB	None	Same server	None	~2-3 minutes

API Reference

Clone Environment Endpoint

POST /api/v1/environments/{env_id}/clone
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Path Parameters:

env_id (UUID, required) - Source environment UUID

Request Body:

{
  "target": {
    "create_new": true,
    "name": "staging-clone-20241211",
    "environment_type": "staging",
    "vm_id": "server-uuid-here",
    "domain": "staging.mycompany.com"
  },
  "sanitization_preset": "recommended",
  "sanitization_options": {
    "disable_mail_servers": true,
    "clear_mail_queue": true,
    "anonymize_emails": true,
    "anonymize_phones": true,
    "clear_api_keys": true,
    "update_base_url": true,
    "clear_asset_bundles": true
  },
  "include_filestore": true
}

Response (202 Accepted):

{
  "id": "clone-op-uuid",
  "source_environment_id": "source-uuid",
  "target_environment_id": "target-uuid",
  "status": "pending",
  "progress": {
    "current_step": "pre_checks",
    "progress_percent": 2,
    "steps": [
      {
        "name": "Pre-Checks",
        "status": "in_progress",
        "progress_percent": 2
      }
    ]
  },
  "sanitization_options": {
    "disable_mail_servers": true,
    "anonymize_emails": true
  },
  "started_at": "2024-12-11T10:45:00Z"
}

Error Responses:

Status	Error Code	Description
400	`INVALID_SOURCE_STATUS`	Source environment not RUNNING or STOPPED
400	`INSUFFICIENT_DISK_SPACE`	Target server doesn't have enough space
400	`QUOTA_EXCEEDED`	Organization quota limit reached
400	`INVALID_TARGET_CONFIG`	Target configuration invalid
403	`PERMISSION_DENIED`	Missing required permission
404	`ENVIRONMENT_NOT_FOUND`	Source environment doesn't exist
404	`SERVER_NOT_FOUND`	Target server doesn't exist
429	`RATE_LIMIT_EXCEEDED`	Too many clone requests

Get Clone Status Endpoint

GET /api/v1/clone-operations/{clone_op_id}
Authorization: Bearer JWT_TOKEN

Response (200 OK):

{
  "id": "clone-op-uuid",
  "source_environment_id": "source-uuid",
  "target_environment_id": "target-uuid",
  "status": "sanitizing",
  "progress": {
    "current_step": "sanitizing",
    "progress_percent": 95,
    "steps": [
      {
        "name": "Pre-Checks",
        "status": "completed",
        "progress_percent": 100,
        "duration_seconds": 2
      },
      {
        "name": "Sanitizing",
        "status": "in_progress",
        "progress_percent": 60
      }
    ]
  },
  "sanitization_result": [
    {
      "option_key": "anonymize_emails",
      "success": true,
      "affected_rows": 247,
      "duration_ms": 1250
    }
  ],
  "started_at": "2024-12-11T10:45:00Z",
  "duration_seconds": 745
}

Cancel Clone Endpoint

POST /api/v1/clone-operations/{clone_op_id}/cancel
Authorization: Bearer JWT_TOKEN

Response (200 OK):

{
  "message": "Clone operation cancelled successfully",
  "clone_operation_id": "clone-op-uuid",
  "status": "cancelled"
}

Error Responses:

Status	Error Code	Description
400	`CANNOT_CANCEL`	Clone too far progressed (after backup starts)
404	`CLONE_NOT_FOUND`	Clone operation doesn't exist

Related Features

Create Environment - Create new environment from scratch
Edit Environment - Modify cloned environment settings
Deploy Environment - Deploy changes to cloned environment
Create Backup - Backup cloned environment
View Deployment Logs - Monitor clone operation logs

Best Practices

Cloning Strategy

For Staging Environments:

Clone from production weekly or bi-weekly
Use Recommended sanitization preset
Include filestore for realistic testing
Test thoroughly before promoting to production

For Development Environments:

Clone from staging monthly
Use Minimal sanitization (faster)
Optionally exclude filestore (faster clones)
Create isolated clone per developer or feature

For Production Promotion:

Use Replace mode (staging → production)
Use None sanitization (keep real data)
Schedule during maintenance window
Backup production before replacing
Test staging thoroughly before promotion

Data Protection

Sensitive Data Handling:

Always use sanitization when cloning production to non-production
Never use "None" preset for external contractor access
Verify sanitization results after clone completes
Restrict access to cloned environments (use RBAC permissions)
Monitor cloned environments for data leaks

Compliance Considerations:

GDPR: Sanitize personal data (emails, phones, addresses)
PCI DSS: Clear payment credentials and API keys
HIPAA: Full sanitization for health data
SOC 2: Document sanitization procedures

Performance Optimization

Speed Up Clones:

Exclude filestore if attachments not needed
Use same-server clones (faster than cross-server)
Use Minimal sanitization for internal clones
Clone during off-peak hours
Use SSD storage on target server

Reduce Clone Size:

Archive old data in production before cloning
Vacuum database before cloning: VACUUM FULL ANALYZE
Clean up attachments and temp files
Use database compression for cross-server

Quota Management

Plan Clones Ahead:

Check quota before creating multiple clones
Delete unused clone environments regularly
Use replace mode instead of creating new (saves quota)
Monitor organization usage at Settings → Usage

Troubleshooting Checklist

Before starting clone, verify:

Source environment status is RUNNING or STOPPED
Target server has sufficient disk space (database + filestore + 20% overhead)
Organization has available quota (if creating new environment)
User has project.environments.create or project.environments.update permission
Target server is RUNNING and accessible
Network connectivity between servers (if cross-server)
SSH credentials are valid for target server

If clone fails:

Check clone progress logs for specific error
Verify source database is healthy
Test target server connectivity
Check disk space during clone (may fill up mid-operation)
Review sanitization errors (may need different preset)
Contact support if error unclear

Last Updated: December 11, 2025 Applies to: OEC.SH v2.0+ Related Sprint: Sprint 2E41 - Documentation System

Environment Variables Deployment Logs & Monitoring