Features
Environments
Create Environment

Create Environment

Feature ID: ENV-001 Category: Environments Required Permission: project.environments.create API Endpoint: POST /api/v1/projects/{project_id}/environments

Overview

Deploy a new Odoo environment within your project. Environments are isolated instances of Odoo running on your infrastructure, each with dedicated resources (CPU, RAM, disk), database, and configuration.

Use this feature when you need to:

  • Set up a development environment for testing new features
  • Create a staging environment for UAT (User Acceptance Testing)
  • Deploy a production environment for live operations
  • Spin up isolated environments for different teams or clients

What happens during creation:

  1. OEC.SH validates your organization quota and server capacity
  2. A unique subdomain is generated (e.g., acme-staging.apps.oec.sh)
  3. Environment record is created with status pending
  4. PostgreSQL resources are auto-calculated (30% of total allocation)
  5. Environment is ready to deploy (separate action)

Prerequisites

Before creating an environment, ensure you have:

Required Access

  • Permission: project.environments.create (Project Admin or Org Owner)
  • Organization Membership: Active member of the organization

Infrastructure Requirements

  • At least one server configured: Navigate to Settings → Servers to add a server
  • Server status: Server must be RUNNING (not provisioning or offline)
  • Available quota: Your organization must have sufficient quota for the requested resources

Project Setup

  • Existing project: Navigate to Dashboard → Projects and select the target project
  • Git connection (optional): Connect GitHub/GitLab/Bitbucket for auto-deploy

How to Create an Environment

Step 1: Navigate to Environment Creation

  1. Go to Dashboard → Projects
  2. Click on the project where you want to create the environment
  3. Click the Environments tab
  4. Click Add Environment button (top-right)

You will be redirected to /projects/{project-id}/environments/new

Step 2: Configure Basic Settings

Environment Name

  • Field: Environment Name
  • Location: First field in the form
  • Behavior: Auto-generated based on your project slug and environment type
    • Pattern: {project-slug}-{env-type}-{random}
    • Example: acme-staging-ab12, myproject-production-xy89
  • Validation:
    • Lowercase letters, numbers, and hyphens only
    • Must be unique within the project
  • Recommendation: Use the auto-generated name for consistency

Environment Type

  • Field: Type dropdown
  • Options:
    • Development - For active development and testing
    • Staging - For pre-production validation
    • Production - For live operations
  • Impact: Type affects billing, backup frequency, and deletion protection
  • Recommendation: Start with Development for initial setup

Step 3: Select Target Server

Server Selection

  • Field: Server dropdown
  • Display Format: Shows {server-name} | {ip-address} | {available-capacity}
  • Capacity Indicator: Shows remaining CPU, RAM, and disk space
  • Test Connection: Click Test Connection to verify server availability before proceeding

Server Requirements:

  • Must belong to your organization
  • Status must be RUNNING (green indicator)
  • Must have sufficient capacity for requested resources
  • Environment count below server's max_projects limit (default: 8)

If no servers available:

  1. Go to Settings → Servers
  2. Click Add Server
  3. Configure server connection details
  4. Wait for status to change to RUNNING

Step 4: Allocate Resources

Configure CPU, RAM, and disk allocation for your environment.

CPU Cores

  • Field: CPU Cores (number input)
  • Range: 0.25 - 32 cores
  • Default: 1.0 core
  • Increment: 0.25 core steps
  • Recommendation:
    • Development: 1-2 cores
    • Staging: 2-4 cores
    • Production: 4-8 cores

RAM (Memory)

  • Field: RAM (MB) (number input)
  • Range: 256 MB - 131,072 MB (128 GB)
  • Default: 2048 MB (2 GB)
  • Increment: 256 MB steps
  • Recommendation:
    • Development: 2-4 GB
    • Staging: 4-8 GB
    • Production: 8-16 GB

Disk Space

  • Field: Disk (GB) (number input)
  • Range: 1 - 1000 GB
  • Default: 10 GB
  • Recommendation:
    • Development: 10-20 GB
    • Staging: 20-50 GB
    • Production: 50-200 GB

Quota Validation:

  • As you adjust resources, OEC.SH checks your organization quota in real-time
  • Green indicator: Resources available
  • Red indicator: Quota exceeded - reduce resources or upgrade plan

PostgreSQL Resource Override (Advanced)

By default, PostgreSQL receives 30% of total CPU and RAM allocation. You can override this:

  1. Click Advanced PostgreSQL Settings (expand section)
  2. Toggle Custom PostgreSQL Resources
  3. Set PostgreSQL CPU Cores (range: 0.1 - 16 cores)
  4. Set PostgreSQL RAM (range: 128 MB - 65,536 MB)

Important: Remaining resources are allocated to Odoo:

  • odoo_cpu = total_cpu - postgres_cpu
  • odoo_ram = total_ram - postgres_ram

Step 5: Configure Domain

Subdomain (System-Generated)

  • Field: Subdomain (text input)
  • Format: {your-name}.apps.oec.sh
  • Auto-generated: Based on project slug and environment type
  • Validation:
    • Must match DNS label format: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
    • Must be globally unique across all OEC.SH environments
  • SSL Certificate: Automatically provisioned via Let's Encrypt

System URL Example: https://acme-staging.apps.oec.sh

Custom Domain (Optional)

  • Field: Custom Domain (text input)
  • Format: Your own domain (e.g., app.acme.com)
  • Requirements:
    1. You own the domain
    2. You configure DNS A record pointing to server IP
    3. OEC.SH verifies DNS and provisions SSL
  • Status Indicator: Shows verification progress
  • Note: Leave blank to use system subdomain only

Step 6: Git Configuration

Branch Selection

  • Field: Git Branch (dropdown)
  • Display: Lists all branches from connected Git repository
  • Default: Project's default branch (usually main or master)
  • Note: If no Git connection exists, this section is disabled

Auto-Deploy

  • Field: Auto-Deploy (toggle switch)
  • Behavior:
    • Enabled: Automatically redeploy when branch receives new commits
    • Disabled: Manual deployment only
  • Recommendation: Enable for Development, disable for Production

Step 7: PostgreSQL Optimizations

Enable performance optimizations for PostgreSQL:

PGTune

  • Toggle: Enable PGTune
  • Default: Enabled
  • What it does: Auto-generates optimal PostgreSQL configuration based on allocated resources
  • Configuration: Applied to postgresql.conf during deployment

PgBouncer

  • Toggle: Enable PgBouncer
  • Default: Enabled
  • What it does: Connection pooling to improve database performance under load
  • Pool Size: Auto-calculated based on RAM allocation
  • Port: 6432 (separate from PostgreSQL's 5432)

Read Replica (Odoo 18.0+ Only)

  • Toggle: Enable Read Replica
  • Default: Disabled
  • Requirements: Odoo version 18.0 or 19.0
  • What it does: PostgreSQL streaming replication for read-heavy workloads
  • Resource Cost: Consumes 30% CPU/RAM, 100% disk of primary
  • Note: Can be enabled later if needed

Step 8: Odoo Configuration (Advanced)

Click Odoo Configuration (expand section) to customize odoo.conf parameters:

Configuration Presets

  • Minimal: Basic settings for small deployments
  • Standard: Recommended for most use cases
  • Production: Optimized for live environments
  • High Performance: Maximum performance settings

Custom Parameters

Configure specific odoo.conf parameters:

  • Workers: Number of Odoo worker processes (default: auto-calculated)
  • Max Cron Threads: Concurrent scheduled job threads
  • Database Filter: Regex pattern for database access control
  • Log Level: Logging verbosity (debug, info, warning, error)
  • Email Settings: SMTP configuration for outbound email
  • Session Timeout: User session expiration time

Most Common Settings:

  • workers = 4 (for production)
  • max_cron_threads = 2
  • log_level = info

Step 9: Select Addon Repositories (Optional)

If you have custom Odoo addons in separate repositories:

  1. Click Addon Repositories (expand section)
  2. Select repositories from your Git connections
  3. Specify branch for each repository
  4. Repositories are cloned during deployment

Step 10: Review and Create

  1. Review all settings in the form
  2. Check quota indicator shows green (resources available)
  3. Click Create Environment button (bottom of form)

What happens next:

  • Environment is created with status pending
  • A modal dialog appears: "Deploy Now?"
    • Click Deploy Now to immediately start deployment
    • Click Deploy Later to deploy manually from the project page

Visual Feedback

During Creation

  • Form Validation: Real-time validation messages appear below each field
  • Quota Indicator: Shows as percentage bar (green = available, red = exceeded)
  • Server Capacity: Updates as you change resource allocations
  • Subdomain Availability: Checkmark appears if subdomain is unique

Upon Success

  • Success Message: "Environment created successfully" (green toast notification)
  • Deploy Modal: Dialog asking whether to deploy now or later
  • Redirect: After deploy decision, redirected to project environments page

Upon Failure

  • Error Message: Specific error appears at top of form (red banner)
  • Field Errors: Individual fields highlight in red with error messages

Common Errors and Solutions

Problem: "Insufficient Quota" Error

Symptoms:

  • Error message: "Cannot create environment - CPU quota exceeded"
  • Quota indicator shows red
  • Create button disabled

Cause: Your organization's quota limit has been reached

Solution:

  1. Navigate to Settings → Usage
  2. Check current quota usage
  3. Option A: Stop or delete unused environments to free up quota
  4. Option B: Navigate to Settings → Billing and upgrade your plan
  5. Return to environment creation form

Problem: "Server Capacity Exceeded" Error

Symptoms:

  • Error message: "Selected server does not have sufficient capacity"
  • Server dropdown shows red indicator

Cause: The selected server doesn't have enough available resources

Solution:

  1. Option A: Select a different server with more capacity
  2. Option B: Reduce requested CPU, RAM, or disk allocation
  3. Option C: Add a new server at Settings → Servers

Problem: "Subdomain Already Exists" Error

Symptoms:

  • Error message: "Subdomain 'acme-prod' is already in use"
  • Subdomain field shows red X icon

Cause: Another environment is using this subdomain

Solution:

  1. Change the subdomain to something unique
  2. Add a suffix: acme-prod-2, acme-prod-new
  3. Include environment type: acme-staging, acme-dev

Problem: "No Servers Available" Error

Symptoms:

  • Server dropdown is empty or disabled
  • Message: "No servers available in your organization"

Cause: No servers are configured or all servers are offline

Solution:

  1. Navigate to Settings → Servers
  2. Click Add Server
  3. Configure server connection:
    • Connection Type: SSH Key or Password
    • Server IP: Your server's public IP
    • Port: SSH port (default 22)
    • Authentication: Provide SSH key or password
  4. Click Test Connection
  5. Wait for server status to change to RUNNING (may take 2-5 minutes)
  6. Return to environment creation form

Problem: Read Replica Toggle Disabled

Symptoms:

  • Read Replica toggle is grayed out
  • Tooltip: "Read Replica requires Odoo 18.0 or higher"

Cause: Your project's Odoo version is older than 18.0

Solution:

  • Read Replica is only supported for Odoo 18.0 and 19.0
  • If needed, create a new project with Odoo 18.0+
  • Or upgrade your project's Odoo version (see upgrade documentation)

API Reference

Create Environment Endpoint

POST /api/v1/projects/{project_id}/environments
Content-Type: application/json
Authorization: Bearer {jwt_token}

Path Parameters:

  • project_id (UUID, required) - The project UUID

Request Body:

{
  "name": "acme-staging-1",
  "env_type": "staging",
  "vm_id": "server-uuid-here",
  "subdomain": "acme-staging",
  "cpu_cores": 2.0,
  "ram_mb": 4096,
  "disk_gb": 20,
  "postgres_cpu_cores": 0.6,
  "postgres_ram_mb": 1229,
  "git_branch": "develop",
  "auto_deploy": true,
  "enable_pgtune": true,
  "enable_pgbouncer": true,
  "enable_read_replica": false,
  "odoo_config": {
    "workers": 4,
    "max_cron_threads": 2,
    "log_level": "info"
  },
  "environment_vars": {
    "CUSTOM_VAR": "value"
  }
}

Response (201 Created):

{
  "id": "env-uuid",
  "name": "acme-staging-1",
  "project_id": "proj-uuid",
  "vm_id": "server-uuid",
  "environment_type": "staging",
  "subdomain": "acme-staging",
  "system_url": "https://acme-staging.apps.oec.sh",
  "status": "pending",
  "cpu_cores": 2.0,
  "ram_mb": 4096,
  "disk_gb": 20,
  "postgres_cpu_cores": 0.6,
  "postgres_ram_mb": 1229,
  "odoo_cpu_cores": 1.4,
  "odoo_ram_mb": 2867,
  "created_at": "2024-12-11T10:30:00Z"
}

Error Responses:

StatusError CodeDescription
400QUOTA_EXCEEDEDOrganization quota limit reached
400SERVER_CAPACITY_EXCEEDEDServer doesn't have enough resources
400SUBDOMAIN_EXISTSSubdomain is already in use
403PERMISSION_DENIEDMissing project.environments.create permission
404PROJECT_NOT_FOUNDProject doesn't exist
404SERVER_NOT_FOUNDSelected server doesn't exist

Full API Documentation: See Environment API Reference

Related Features

Best Practices

Resource Planning

For Development Environments:

  • CPU: 1-2 cores
  • RAM: 2-4 GB
  • Disk: 10-20 GB
  • Auto-deploy: Enabled

For Staging Environments:

  • CPU: 2-4 cores
  • RAM: 4-8 GB
  • Disk: 20-50 GB
  • Auto-deploy: Consider enabling for continuous testing

For Production Environments:

  • CPU: 4-8+ cores (based on load)
  • RAM: 8-16+ GB (based on concurrent users)
  • Disk: 50-200+ GB (based on data volume)
  • Auto-deploy: Disabled (manual control recommended)
  • Enable PGTune and PgBouncer
  • Consider Read Replica for read-heavy workloads

Naming Conventions

Use clear, descriptive environment names:

  • ✅ Good: acme-production, myapp-staging-eu, client-dev-feature-x
  • ❌ Avoid: test1, env2, temp

Include:

  • Project/client name
  • Environment type
  • Region (if multi-region)
  • Purpose (if specific feature branch)

Quota Management

  • Monitor usage: Check Settings → Usage regularly
  • Clean up: Delete unused development environments
  • Scale appropriately: Don't over-provision resources
  • Plan ahead: Ensure quota available before creating production environments

Security

  • Production isolation: Use separate servers for production environments
  • Custom domains: Use custom domains for production (not system subdomains)
  • SSL certificates: Always use HTTPS (auto-provisioned)
  • Database access: Configure db_filter in Odoo config to restrict database access

Next Steps

After creating your environment:

  1. Deploy the environment - See Deploy Environment
  2. Configure backups - See Create Backup
  3. Setup custom domain - See Custom Domain Configuration
  4. Monitor resources - See Environment Monitoring
  5. Invite team members - See Manage Organization Members

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

Environment LifecycleEdit Environment