Edit Environment

Feature ID: ENV-002 Category: Environments Required Permission: project.environments.update API Endpoint: PATCH /api/v1/projects/{project_id}/environments/{env_id}

Overview

Modify an existing environment's configuration, scale resources, change server assignment, update domain settings, and adjust Odoo parameters. Changes can be applied immediately or saved for the next deployment.

Use this feature to:

• Scale CPU, RAM, or disk resources up or down
• Reassign environment to a different server
• Change Git branch or toggle auto-deploy
• Update custom domain configuration
• Adjust Odoo configuration parameters
• Modify PostgreSQL optimization settings
• Update environment variables

Important: Most configuration changes require a manual redeploy to take effect. Resource scaling does NOT automatically trigger redeployment.

Prerequisites

Required Access

• Permission: project.environments.update (Project Admin or Org Owner)
• Organization Membership: Active member of the organization
• Environment Access: Environment must belong to your project

Environment State

• Any Status: Environment can be edited in any status (pending, running, stopped, error)
• Production Protection: Production environments have additional deletion safeguards

Infrastructure

• Available Quota (for scaling): Sufficient organization quota for increased resources
• Running Servers (for reassignment): At least one server in RUNNING status

How to Edit an Environment

Step 1: Navigate to Environment Settings

1. Go to Dashboard → Projects
2. Click on the project containing the environment
3. Click the Environments tab
4. Locate the environment you want to edit
5. Click the Edit icon (pencil) or View button on the environment row
6. Click the Settings tab at the top of the environment page

You will be at /environments/{env-id}/edit in the Settings view.

Step 2: Choose Settings Category

The Settings view has 5 tabs:

1. Server Resources - Server assignment, CPU, RAM, Disk allocation
2. Domain - Custom domain configuration and SSL status
3. Database - Odoo configuration and PostgreSQL optimization
4. Repositories - Git branch, auto-deploy, addon repositories
5. Advanced - Environment size analysis, danger zone (destroy)

Unsaved Changes Indicator: Tabs with pending changes show an orange "Unsaved" badge.

Server Resources Tab

Change Server Assignment

When to change: Move environment to a different physical server

1. Navigate to Settings → Server Resources tab
2. Find the Server dropdown (shows current server or "No server assigned")
3. Click the dropdown to see available servers
   • Display format: {server-name} | {ip-address} | {available-capacity}
   • Only RUNNING servers are selectable
4. Select the new server
5. Important: Verify new server has sufficient capacity (shown in dropdown)
6. Click Save Changes at bottom of tab

Server Requirements:

• Status must be RUNNING (not provisioning or offline)
• Must belong to your organization
• Must have available capacity for environment's current resources
• Environment count must be below server's max_projects limit (usually 8)

What happens:

• Environment's vm_id is updated to new server
• No automatic redeploy - you must manually deploy to move containers
• Next deployment will create containers on the new server

Unassign Server

To remove server assignment:

1. Click the X button in the server dropdown
2. Server field becomes "No server assigned"
3. Click Save Changes

Note: Environment cannot be deployed without an assigned server.

Scale CPU Resources

Range: 0.25 - 32 cores (limited by server capacity and organization quota)

1. In Server Resources tab, find CPU Cores slider
2. Drag slider or enter value directly
   • Increment: 0.5 core steps
   • Display shows: Total cores, PostgreSQL allocation (30%), Odoo allocation (70%)
3. Capacity Indicator: Watch the server capacity bar
   • Green: Resources available
   • Red: Exceeds server capacity (save disabled)
4. Quota Indicator: Check organization quota usage
   • Updates in real-time as you adjust resources
5. Click Save Changes

Scaling Up:

• Requires available organization quota
• Must not exceed assigned server's total cores
• PostgreSQL cores auto-recalculated (30% of new total)

Scaling Down:

• Can reduce to minimum 0.25 cores
• Frees up quota for other environments
• PostgreSQL cores auto-recalculated

Recommended Allocations:

Scale RAM Resources

Range: 256 MB - 131,072 MB (128 GB) - limited by server capacity and quota

1. In Server Resources tab, find RAM dropdown
2. Select from preset options:
   • 512 MB, 1 GB, 2 GB, 4 GB, 8 GB, 16 GB, 32 GB, 64 GB, 128 GB
3. Or enter custom value in MB
   • Display shows: Total RAM, PostgreSQL allocation (30%), Odoo allocation (70%)
4. Capacity Indicator: Verify server has available memory
5. Click Save Changes

Scaling Considerations:

• Odoo requires minimum 1 GB RAM for stable operation
• PostgreSQL benefits from larger cache (30% allocation)
• Each Odoo worker consumes ~150-300 MB RAM

Recommended Allocations:

Scale Disk Storage

Range: 1 - 1000 GB (limited by server capacity and quota)

1. In Server Resources tab, find Disk Space slider
2. Drag slider or enter value
   • Increment: 5 GB steps
   • Minimum shown in UI: 5 GB (backend minimum: 1 GB)
3. Growth Recommendation: Check current usage first
   • Navigate to Advanced tab → Environment Size section
   • Review Database Size, Filestore Size, Addons Size
   • Add 20-30% buffer for growth
4. Click Save Changes

Disk Usage Breakdown:

• Database: PostgreSQL database files (~10-50% of total)
• Filestore: Uploaded attachments, images, documents (~30-70%)
• Addons: Custom modules and dependencies (~5-10%)
• Logs: Application and system logs (~5-10%)

Scaling Down Warning:

• Cannot scale disk below current usage
• Check Advanced → Environment Size before reducing
• Backend validates disk >= current total size

Override PostgreSQL Resources (Advanced)

By default, PostgreSQL receives 30% of total CPU and RAM. To customize:

1. In Server Resources tab, scroll to PostgreSQL Resources Override
2. Click Custom PostgreSQL Allocation toggle to enable
3. Set PostgreSQL CPU Cores:
   • Range: 0.1 - 16 cores
   • Default: 30% of total CPU
4. Set PostgreSQL RAM:
   • Range: 128 MB - 65,536 MB
   • Default: 30% of total RAM
5. Odoo Resources: Automatically calculated
   • Odoo CPU = Total CPU - PostgreSQL CPU
   • Odoo RAM = Total RAM - PostgreSQL RAM
6. Click Save Changes

When to override:

• High read/write database workload → Increase PostgreSQL allocation
• Compute-heavy Odoo operations → Decrease PostgreSQL allocation
• Large database with complex queries → Increase PostgreSQL RAM

Domain Tab

Update Custom Domain

Use case: Point your own domain to the environment

1. Navigate to Settings → Domain tab
2. System URL (read-only): Shows auto-generated {subdomain}.apps.oec.sh
3. Custom Domain field: Enter your domain (e.g., app.mycompany.com)
4. Click Save Changes
5. Configure DNS (required):
   • Go to your DNS provider
   • Create A record: app.mycompany.com → Server IP address
   • Wait for DNS propagation (5-60 minutes)
6. Verify DNS: Return to this tab, click Verify DNS button
7. SSL Provisioning: Once verified, SSL certificate auto-provisions via Let's Encrypt

Domain Status Indicators:

• Pending: DNS not yet verified
• Verifying: DNS propagation in progress
• Verified: DNS confirmed, SSL provisioning started
• Active: SSL certificate installed, HTTPS working
• Failed: DNS verification or SSL provisioning failed

Troubleshooting:

• DNS not propagating: Wait 5-60 minutes, some providers take longer
• SSL failed: Ensure port 80 and 443 are open on server
• Domain already in use: Each domain can only be used by one environment

Remove Custom Domain

1. Navigate to Settings → Domain tab
2. Clear the Custom Domain field
3. Click Save Changes
4. Environment reverts to using system URL only

Database Tab

Update Odoo Configuration

Configure Odoo runtime parameters (odoo.conf settings):

1. Navigate to Settings → Database tab
2. Scroll to Odoo Configuration section
3. Use Preset (optional): Select from predefined configurations
   • Minimal: Basic settings, low resource usage
   • Standard: Recommended for most environments
   • Production: Optimized for live deployments
   • High Performance: Maximum performance settings
4. Or customize parameters:

Common Parameters:

5. Click Save Changes
6. Redeploy Required: Changes take effect on next deployment

Worker Calculation:

• Formula: workers = (CPU_cores * 2) + 1
• Example: 4 CPU cores → 9 workers
• Minimum: 2 workers
• Maximum: Limited by RAM (each worker ~200 MB)

Configure PostgreSQL Optimization

Enable or disable PostgreSQL performance features:

PGTune (Auto-Configuration)

1. Navigate to Settings → Database tab
2. Find PostgreSQL Optimization section
3. Toggle Enable PGTune
   • Enabled (default): Auto-generates optimal PostgreSQL config based on allocated resources
   • Disabled: Uses PostgreSQL defaults
4. Click Save Changes
5. Redeploy Required: Changes apply on next deployment

What PGTune configures:

• shared_buffers - Memory for caching (25% of RAM)
• effective_cache_size - OS cache estimation (75% of RAM)
• work_mem - Memory per query operation
• maintenance_work_mem - Memory for maintenance operations
• max_connections - Maximum concurrent connections

PgBouncer (Connection Pooling)

1. In PostgreSQL Optimization section
2. Toggle Enable PgBouncer
   • Enabled (default): Activates connection pooling
   • Disabled: Direct PostgreSQL connections
3. Pool Size (advanced): Auto-calculated or custom
   • Formula: pool_size = (CPU_cores * 2) + 1
   • Range: 10-100 connections
4. Click Save Changes
5. Redeploy Required: Changes apply on next deployment

PgBouncer Benefits:

• Reduces PostgreSQL connection overhead
• Improves performance under high concurrent load
• Typical performance gain: 20-30% with 50+ concurrent users

Port Configuration:

• PostgreSQL: Port 5432 (container-internal)
• PgBouncer: Port 6432 (Odoo connects here when enabled)

Repositories Tab

Change Git Branch

Use case: Switch to a different branch for deployment

1. Navigate to Settings → Repositories tab
2. Find Git Branch dropdown
   • Shows all branches from connected Git repository
   • Current branch is highlighted
3. Select new branch from dropdown
4. Click Save Changes

What happens:

• Environment's git_branch is updated
• If auto-deploy enabled: Deployment triggers automatically
• If auto-deploy disabled: Next manual deployment uses new branch

Common Use Cases:

• Development → Feature branch (e.g., feature/new-module)
• Staging → Release branch (e.g., release/v2.0)
• Production → Stable branch (e.g., main, production)

Toggle Auto-Deploy

Use case: Enable/disable automatic deployment on git push

1. In Repositories tab, find Auto-Deploy toggle
2. Click toggle to enable/disable
   • Enabled: Deployment triggered on git push to git_branch
   • Disabled: Manual deployment only
3. Click Save Changes

Recommendation:

• ✅ Enable for Development environments (fast iteration)
• ⚠️ Consider for Staging environments (automated testing)
• ❌ Disable for Production environments (manual control)

Manage Addon Repositories

Use case: Add or remove custom Odoo addon repositories

1. In Repositories tab, scroll to Addon Repositories section
2. Add Addon Repository:
   • Click Add Addon Repository button
   • Select repository from dropdown (from your Git connections)
   • Select branch
   • Click Add
3. Remove Addon Repository:
   • Find repository in the list
   • Click Remove icon (X)
4. Click Save Changes
5. Redeploy Required: Warning appears - "Redeploy to apply addon changes"

Deployment Behavior:

• Addon repositories are cloned during deployment
• Modules are added to Odoo addons path
• Modules become available in Odoo Apps list

Advanced Tab

View Environment Size

Check current disk space usage breakdown:

1. Navigate to Settings → Advanced tab
2. Environment Size section shows:
   • Database Size: PostgreSQL database files (in MB/GB)
   • Filestore Size: Uploaded attachments and documents
   • Addons Size: Custom modules and dependencies
   • Total Size: Sum of all components
   • Last Updated: When size calculation last ran

Use this information to:

• Plan disk scaling (before running out of space)
• Identify growth trends
• Estimate backup sizes

Size Refresh: Sizes update every 6 hours automatically

Destroy Environment (Danger Zone)

Warning: This permanently deletes the environment and all associated data.

1. Navigate to Settings → Advanced tab
2. Scroll to Danger Zone (collapsed by default)
3. Click Destroy Environment button
4. Backup Decision dialog appears (if backups exist):
   • Keep All Backups: Delete environment, keep all backups (orphaned)
   • Keep Latest Backup: Delete environment, keep only most recent backup
   • Delete All Backups: Delete environment and all backups from storage
5. Type to Confirm: Enter environment name exactly to confirm
6. Click Destroy button

Production Protection:

• Production environments cannot be destroyed
• Error message: "Cannot delete production environment"
• Must change environment type first (contact support)

What gets deleted:

• Environment database record
• All deployment records
• All log entries
• Docker containers (if deployed)
• Database and filestore on server
• Optionally: Backups (based on selection)

Saving Changes

Save Flow

1. Make changes in any Settings tab
2. Unsaved Indicator: Tab shows orange "Unsaved" badge
3. Click Save Changes button at bottom of tab
4. Validation: Backend checks capacity, quota, server status
5. Success: Changes saved, badge removed, toast notification appears
6. Error: Validation errors displayed, changes not saved

Save Button States:

• Enabled (blue): Changes pending, validation passed
• Disabled (gray): No changes or validation failed
• Loading (spinner): Save in progress

Validation Errors

Common validation errors:

Visual Feedback

During Editing

• Tab Badges: Orange "Unsaved" badge on tabs with pending changes
• Capacity Bars: Real-time server capacity indicators (green/red)
• Quota Meters: Organization quota usage percentage bars
• Field Validation: Red borders and error messages on invalid fields

Upon Save

• Success Toast: "Settings saved successfully" (green notification, top-right)
• Tab Badge Removed: "Unsaved" badge disappears
• Form Reset: Pending changes counter resets to 0

Upon Error

• Error Toast: Specific error message (red notification, top-right)
• Field Highlights: Invalid fields outlined in red
• Inline Messages: Error descriptions below affected fields

What Requires Redeployment

Changes That Require Manual Redeploy

The following changes are saved but only take effect after redeploying:

• Server Assignment: Containers must be recreated on new server
• Resource Scaling: CPU/RAM/Disk changes require container restart
• Custom Domain: DNS and SSL configuration updates
• Odoo Configuration: odoo.conf parameters
• PostgreSQL Optimization: PGTune and PgBouncer settings
• Addon Repositories: New repositories must be cloned
• Environment Variables: Docker container environment

To apply changes: Click Deploy button in environment header or overview tab.

Changes That Auto-Deploy (if enabled)

• Git Branch Change: If auto-deploy enabled, triggers deployment automatically
• Git Push: If auto-deploy enabled, deployment triggers on push to git_branch

Common Scenarios

Scenario 1: Scale Up Production for High Traffic

Goal: Increase resources before Black Friday sale

1. Navigate to environment → Settings → Server Resources tab
2. Scale up resources:
   • CPU: 4 cores → 8 cores
   • RAM: 8 GB → 16 GB
3. Click Save Changes
4. Go to Overview tab → Click Deploy to apply changes
5. Monitor deployment logs for completion
6. Verify increased resources in Monitoring tab

Estimated Downtime: 2-5 minutes (container restart)

Scenario 2: Move Environment to Different Server

Goal: Migrate to a new, more powerful server

1. Ensure new server is in RUNNING status
2. Navigate to environment → Settings → Server Resources tab
3. Change Server dropdown to new server
4. Verify new server has capacity
5. Click Save Changes
6. Go to Overview tab → Click Deploy
7. Deployment creates containers on new server
8. Old containers are stopped and removed

Estimated Downtime: 3-7 minutes (full redeployment)

Scenario 3: Switch Staging to Feature Branch

Goal: Test new feature in staging environment

1. Navigate to staging environment → Settings → Repositories tab
2. Change Git Branch to feature/new-checkout-flow
3. Click Save Changes
4. If auto-deploy disabled: Manually click Deploy
5. If auto-deploy enabled: Deployment triggers automatically
6. Monitor deployment in Logs tab
7. Test feature at staging URL

Scenario 4: Enable PgBouncer for Better Performance

Goal: Improve database connection performance

1. Navigate to environment → Settings → Database tab
2. Find PostgreSQL Optimization section
3. Toggle Enable PgBouncer to ON
4. Click Save Changes
5. Go to Overview tab → Click Deploy
6. Wait for deployment completion (PgBouncer container created)
7. Verify in logs: pgbouncer container started

Performance Gain: 20-30% for high-concurrency workloads

API Reference

Update Environment Endpoint

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

Path Parameters:

• project_id (UUID, required) - The project UUID
• env_id (UUID, required) - The environment UUID

Request Body (all fields optional):

{
  "name": "updated-name",
  "vm_id": "new-server-uuid",
  "domain": "app.mycompany.com",
  "subdomain": "new-subdomain",
  "git_branch": "feature/branch",
  "auto_deploy": true,
  "port": 8069,
  "cpu_cores": 4.0,
  "ram_mb": 8192,
  "disk_gb": 50,
  "postgres_cpu_cores": 1.2,
  "postgres_ram_mb": 2458,
  "odoo_config": {
    "workers": 8,
    "max_cron_threads": 2,
    "log_level": "info"
  },
  "environment_vars": {
    "CUSTOM_VAR": "new_value"
  },
  "is_active": true
}

Response (200 OK):

{
  "id": "env-uuid",
  "name": "updated-name",
  "vm_id": "new-server-uuid",
  "environment_type": "staging",
  "subdomain": "new-subdomain",
  "system_url": "https://new-subdomain.apps.oec.sh",
  "status": "running",
  "cpu_cores": 4.0,
  "ram_mb": 8192,
  "disk_gb": 50,
  "postgres_cpu_cores": 1.2,
  "postgres_ram_mb": 2458,
  "odoo_cpu_cores": 2.8,
  "odoo_ram_mb": 5734,
  "updated_at": "2024-12-11T11:30:00Z"
}

Error Responses:

Full API Documentation: See Environment API Reference

Related Features

• Create Environment - Deploy a new environment
• Deploy Environment - Deploy updated configuration
• Clone Environment - Duplicate environment with data
• View Deployment Logs - Monitor deployment progress
• Manage Servers - Configure and monitor servers
• Organization Quota - View and manage resource quota
• Custom Domains - Configure custom domain and SSL

Best Practices

Resource Scaling

Scale Gradually:

• Increase resources by 25-50% at a time
• Monitor performance after each change
• Avoid over-provisioning (wastes quota)

Monitor Before Scaling:

• Check Monitoring tab for CPU/RAM usage
• Scale up if consistently above 70-80% usage
• Scale down if consistently below 30% usage

Plan for Growth:

• Development: Start small, scale as needed
• Staging: Match production specifications
• Production: Add 20-30% buffer for traffic spikes

Server Management

Use Multiple Servers:

• Separate development and production servers
• Isolate high-traffic environments
• Plan for disaster recovery (multi-server redundancy)

Test Server Changes:

• Always use Test Connection before saving
• Verify capacity indicators show green
• Check server status in Settings → Servers

Configuration Management

Test in Development First:

• Make configuration changes in dev environment
• Validate changes work as expected
• Promote tested config to staging, then production

Document Custom Settings:

• Keep notes on custom Odoo config parameters
• Document why specific settings were chosen
• Track configuration history in version control

Review Odoo Worker Count:

• Formula: workers = (CPU_cores * 2) + 1
• Adjust based on actual load patterns
• Monitor worker memory usage

Git Workflow

Branch Strategy:

• Development → Feature branches
• Staging → Release candidates or develop branch
• Production → Stable branch (main, production)

Auto-Deploy Usage:

• ✅ Enable: Development environments
• ⚠️ Consider: Staging with automated tests
• ❌ Avoid: Production environments

PostgreSQL Optimization

Always Enable PGTune:

• Provides significant performance improvement
• Auto-adjusts config based on resources
• Zero configuration required

Enable PgBouncer for Production:

• Improves performance with 20+ concurrent users
• Minimal overhead
• Recommended for all production environments

Consider Read Replica (Odoo 18+):

• Use for read-heavy workloads
• Offload reporting queries
• Requires 30% additional CPU/RAM, 100% disk

Next Steps

After editing your environment:

1. Deploy changes - See Deploy Environment
2. Monitor deployment - See View Deployment Logs
3. Verify changes - Check environment URL and test functionality
4. Monitor performance - Use Monitoring tab for real-time metrics
5. Create backup - See Create Manual Backup

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