Introduction to OEC.SH

What is OEC.SH?

OEC.SH (Odoo Enterprise Cloud Shell) is a multi-tenant Odoo hosting platform that enables digital agencies, Odoo developers, and SaaS companies to deploy, manage, and scale Odoo environments with complete infrastructure control.

Built for developers who want:

• Full control over Odoo deployments
• Multi-project hosting capabilities
• Bring Your Own Server (BYOS) flexibility
• Git-based deployment workflows
• Production-grade infrastructure without DevOps overhead

Key Value Proposition: Deploy 3-10 Odoo projects per server with enterprise-grade features and complete infrastructure control.

Platform Overview

What Makes OEC.SH Different?

Target Users

1. Digital Agencies

• Manage 5-20+ client Odoo projects
• Require white-label deployments
• Need multi-client hosting capabilities
• Want simplified client management

2. Odoo Developers

• Build custom Odoo applications
• Need staging/production parity
• Require git-based workflows
• Want automated deployment pipelines

3. SaaS Companies

• Multi-tenant Odoo applications
• Need scalable infrastructure
• Require high availability (read replicas)
• Need flexible resource allocation

4. Enterprises

• Internal Odoo deployments
• Data sovereignty requirements (BYOS)
• Compliance needs (GDPR, HIPAA)
• Need advanced RBAC and audit trails

Architecture Explained

Multi-Tenant Hierarchy

OEC.SH uses a 3-tier hierarchy for organizing deployments:

Organization (Company/Agency)
    ├── Projects (Odoo Applications)
    │   ├── Environments (Dev, Staging, Prod)
    │   │   ├── Deployed on Server 1
    │   │   ├── Deployed on Server 2
    │   │   └── Deployed on Server 3
    │   └── Environments
    └── Projects

Key Architectural Principle: Environments (not projects) are the deployment unit. Multiple environments from different projects can coexist on the same server.

1. Organizations

What is an Organization?

• A company, agency, or team workspace
• The multi-tenant boundary for billing and access control
• Contains projects, servers, team members, and settings

Organization Features:

• Team member management (owners, admins, developers, viewers)
• Role-based access control (55+ granular permissions)
• Shared resources (servers, storage, Git connections)
• Unified usage tracking
• Resource quotas (CPU, RAM, disk, environments)

Example Organizations:

• Acme Digital Agency - 15 members, 30 client projects, 5 BYOS servers
• TechCorp SaaS - 5 developers, 10 platform environments
• Enterprise Inc - 50 users, 20 internal projects, BYOS with GDPR compliance

2. Projects

What is a Project?

• A single Odoo application/codebase
• Connected to a Git repository (GitHub/GitLab)
• Can have multiple environments (dev, staging, production)
• Shares configuration across environments

Project Configuration:

• Git Repository: Source code location (custom addons, modules)
• Odoo Version: 14.0, 15.0, 16.0, 17.0, 18.0, 19.0
• Docker Image: Official Odoo or custom registry images
• Module Repositories: Additional addon sources (OCA, private repos)
• Webhooks: Automatic deployments on git push

Example Projects:

• Client A - ERP - Odoo 18.0, custom manufacturing modules, 3 environments
• Client B - CRM - Odoo 17.0, standard CRM, 2 environments
• Internal Portal - Odoo 19.0, custom portal, 4 environments (dev/staging/prod/demo)

3. Environments

What is an Environment?

• An isolated Odoo instance (running containers)
• Deployed to a specific server
• Has dedicated resources (CPU, RAM, disk)
• Accessible via unique URL (subdomain or custom domain)

Environment Types:

Environment Architecture:

Environment Containers (per environment):
├── Odoo Container (Python application)
│   ├── Odoo 18.0 runtime
│   ├── Custom addons from Git
│   ├── Module repositories
│   └── Workers: 2-8 (configurable)
├── PostgreSQL Container (database)
│   ├── Primary database
│   ├── PgBouncer (connection pooling)
│   └── Optional: Read Replica (Odoo 18+)
└── Traefik Routing (automatic SSL)
    ├── HTTP → HTTPS redirect
    ├── Let's Encrypt certificates
    └── Custom domain support

Environment URLs:

• System-generated: acme-production.oec.sh (automatic)
• Custom domains: erp.acme-corp.com (user-provided)
• Multiple domains: Both system + custom simultaneously

4. Servers (VMs)

What is a Server?

• A physical or virtual machine running Docker
• Hosts multiple Odoo environments from different projects
• Two ownership models: BYOS (customer-owned) or Platform (OEC.SH-managed)

Server Specifications:

Multi-Project Architecture:

Server 1 (4 CPU, 8GB RAM):
├── Project A - Production (2 CPU, 4GB)
├── Project B - Staging (1 CPU, 2GB)
└── Project C - Development (0.5 CPU, 1GB)
Total: 3.5 CPU used / 4 available

Server 2 (8 CPU, 16GB RAM):
├── Client 1 - Production (2 CPU, 4GB)
├── Client 2 - Production (2 CPU, 4GB)
├── Client 3 - Staging (1 CPU, 2GB)
├── Client 4 - Development (1 CPU, 2GB)
└── Client 5 - Development (1 CPU, 2GB)
Total: 7 CPU used / 8 available

BYOS (Bring Your Own Server):

• Use your existing infrastructure
• DigitalOcean, AWS, Hetzner, OVH, bare metal
• Full data sovereignty and control
• Up to 10 environments per server

Platform-Managed Servers:

• OEC.SH provisions and manages infrastructure
• No server management overhead
• Automatic scaling and updates
• Ideal for teams without DevOps resources

5. Deployments

What is a Deployment?

• The process of building and starting an Odoo environment
• Triggered manually, via Git webhook, or API
• Takes 3-5 minutes for typical environments
• Real-time progress tracking (16 deployment steps)

Deployment Pipeline:

Trigger (Git push / Manual / API)
    ↓
1. Queue deployment task
2. Validate environment configuration
3. Clone Git repository (main branch)
4. Clone module repositories (OCA, private)
5. Create PostgreSQL database
6. Deploy PgBouncer (connection pooling)
7. Generate Odoo configuration (odoo.conf)
8. Pull Docker image (Odoo version)
9. Create Odoo container
10. Install database (base modules)
11. Update module list
12. Install custom addons
13. Configure Traefik routing
14. Request SSL certificate (Let's Encrypt)
15. Health check (HTTP 200 from Odoo)
16. Mark deployment complete
    ↓
Environment Running (accessible via URL)

Deployment Triggers:

• Manual: Click "Deploy" button in UI
• Git Webhook: Push to monitored branch
• API: Programmatic deployment via REST API
• Clone: Deploy from cloned environment
• Restore: Deploy from backup

Deployment Monitoring:

• Real-time progress updates (SSE)
• Detailed logs for each step
• Error messages with troubleshooting hints
• Deployment history with duration and status

6. Backups

What is a Backup?

• Point-in-time snapshot of environment data
• Includes PostgreSQL database + Odoo filestore
• Encrypted and verified before upload
• Stored in configured cloud storage
• Managed with GFS (Grandfather-Father-Son) retention

Backup Architecture:

Environment Data
├── PostgreSQL Database (pg_dump)
│   ├── Schema (tables, indexes, constraints)
│   ├── Data (all rows)
│   └── Size: 10 MB - 5 GB typical
└── Odoo Filestore (tar.gz)
    ├── Attachments (documents, images)
    ├── Reports (PDFs)
    ├── Mail attachments
    └── Size: 100 MB - 50 GB typical
        ↓
Create ZIP Archive
├── dump.sql (plain-text SQL)
├── filestore.tar.gz (compressed)
└── manifest.json (metadata, checksums)
        ↓
Upload to Cloud Storage
├── AWS S3 (enterprise)
├── Cloudflare R2 (recommended)
├── Backblaze B2 (archival)
├── MinIO (self-hosted)
├── SFTP (legacy)
└── FTP (legacy)
        ↓
GFS Retention Management
├── Daily: 7 days
├── Weekly: 4 weeks
├── Monthly: 12 months
├── Yearly: 2 years
└── Permanent: Never expires

Backup Types:

• Manual: On-demand user-initiated backups
• Automated: Scheduled via backup policy (2 AM daily)
• Pre-Restore: Safety backup before restore
• Pre-Upgrade: Safety backup before Odoo version upgrade

Backup Use Cases:

• Disaster recovery (restore from catastrophic failure)
• Environment cloning (copy production to staging)
• Version rollback (restore after bad deployment)
• Data migration (move between servers)
• Compliance archival (legal/regulatory requirements)

Key Platform Concepts

Multi-Project per VM Architecture

Traditional Hosting (1:1 model):

Server 1: Client A Production
Server 2: Client B Production
Server 3: Client C Production
Total: 3 servers for 3 clients

OEC.SH (Multi-Project model):

Server 1 (4 CPU, 8GB):
├── Client A Production (2 CPU, 4GB)
├── Client B Production (1 CPU, 2GB)
└── Client C Production (1 CPU, 2GB)

Total: 1 server for 3 clients

Key Benefits:

• Share server resources across multiple projects
• Efficient resource utilization (3-10 projects per server)
• Flexible resource allocation per environment
• Simplified infrastructure management

Resource Quota System

Organization Quotas:

• Total CPU Quota: Maximum CPU cores across all environments
• Total RAM Quota: Maximum memory across all environments
• Total Disk Quota: Maximum disk space across all environments
• Max Environments: Maximum number of active environments
• Max Servers: Maximum number of BYOS servers

Per-Environment Limits:

• Max CPU per Environment: Prevents single environment from hogging resources
• Max RAM per Environment: Ensures fair resource distribution
• Max Disk per Environment: Controls storage usage

Quota Enforcement:

• Real-time validation during environment creation
• Quota warnings when approaching limits (80% usage)
• Quota exceeded errors prevent over-allocation
• Replica resources counted (30% CPU/RAM, 100% disk)

Quota Scaling:

• Organization-level limits prevent over-provisioning
• Contact support for custom quota requirements

Git-Based Workflows

Supported Git Providers:

• GitHub (OAuth App or Personal Access Token)
• GitLab (OAuth App or Personal Access Token)
• GitHub Enterprise (self-hosted)
• GitLab Self-Managed (self-hosted)

Git Connection Methods:

1. OAuth: One-click authorization, automatic token refresh
2. Personal Access Token (PAT): Fine-grained permissions, revocable
3. GitHub App: Organization-wide installation, enhanced security

Webhook Automation:

Developer pushes to Git
    ↓
GitHub/GitLab sends webhook
    ↓
OEC.SH verifies HMAC signature
    ↓
Check auto-deploy settings
    ↓
If enabled: Queue deployment
    ↓
Deploy environment with new code
    ↓
Notify team via SSE/email

Branch Strategies:

• Single-branch: All environments deploy from main
• Multi-branch: Each environment tracks different branch
  • Dev → develop
  • Staging → staging
  • Production → main
• Tag-based: Production deploys from tagged releases only

Environment Cloning

What is Cloning?

• Create a new environment from an existing one
• Copies database, filestore, and configuration
• Optionally sanitizes sensitive data
• Deploys to same or different server

Clone Process:

Source Environment (Production)
    ↓
1. Create backup (database + filestore)
2. Apply sanitization (if selected)
3. Create target environment
4. Restore backup to target
5. Reconfigure target (URLs, workers)
6. Deploy target environment
    ↓
Target Environment (Staging)

Sanitization Presets:

Sanitization Actions:

• Email: Replace with user+{id}@example.com
• Passwords: Reset to password123 (change immediately)
• API Keys: Remove external integrations (Stripe, PayPal)
• Mail Queue: Clear outbound emails (prevent accidental sends)
• Crons: Disable scheduled jobs (prevent duplicate processing)

Clone Use Cases:

• Create staging from production (for testing)
• Create development from staging (for feature work)
• Create demo from production (for sales demos)
• Clone to different server (for migration)

Custom Domains & SSL

Domain System:

• System-generated subdomains: projectname-envtype.oec.sh (automatic)
• Custom domains: erp.company.com (user-provided)
• Wildcard domains: *.company.com (DNS provider integration)

SSL Certificate Provisioning:

Custom Domain Added
    ↓
1. DNS verification (check CNAME/A record)
2. Request Let's Encrypt certificate
3. ACME DNS-01 or HTTP-01 challenge
4. Certificate issued (valid 90 days)
5. Auto-renewal (every 60 days)
    ↓
HTTPS Enabled (automatic redirect)

DNS Provider Integrations:

• Cloudflare: Full automation (API)
• AWS Route53: Full automation (API)
• DigitalOcean DNS: Full automation (API)
• Manual: User adds DNS records themselves

Multi-Domain Support:

• Primary URL: acme-production.oec.sh
• Custom domain 1: erp.acme-corp.com
• Custom domain 2: odoo.acme.com
• All domains route to same environment with SSL

PostgreSQL Read Replicas

What is a Read Replica?

• A read-only copy of the PostgreSQL primary database
• Streams changes from primary in near-real-time
• Used for reporting, analytics, and read-heavy operations
• Reduces load on primary database

Requirements:

• Odoo Version: 18.0 or 19.0 ONLY (older versions not supported)
• Environment Type: Production recommended
• Resources: 30% of primary CPU/RAM, 100% of disk

Replication Architecture:

Primary PostgreSQL Container
    ↓ (Streaming replication)
Read Replica Container
    ↓
Odoo connects to:
├── Primary: Writes, transactions
└── Replica: Reports, exports, analytics

Health Monitoring:

• Replication Lag: Measured in bytes and seconds
• Lag Thresholds:
  • Normal: <10 MB, <5 seconds
  • Warning: 10-100 MB, 5-30 seconds
  • Critical: >100 MB, >30 seconds
• Status Indicators: Online, Lagging, Offline, Error
• Auto-check: Every 2 minutes (ARQ cron job)

Use Cases:

• Large report generation (without blocking writes)
• Analytics dashboards (real-time insights)
• Data exports (without impacting users)
• Business intelligence tools (external BI connections)

Platform Capabilities

1. Git-Based Deployments

Features:

• Connect GitHub/GitLab repositories (OAuth or PAT)
• Automatic webhook setup (push triggers deploy)
• Branch-specific deployments (dev, staging, prod)
• Tag-based releases (production deploys from tags)
• Deployment history with logs and rollback

Workflow Example:

# Developer workflow
git checkout -b feature/new-module
git commit -m "Add new inventory module"
git push origin feature/new-module
# → Automatic deployment to dev environment
 
git checkout staging
git merge feature/new-module
git push origin staging
# → Automatic deployment to staging environment
 
# Tag release for production
git tag v1.5.0
git push origin v1.5.0
# → Manual deployment to production (if configured)

2. Environment Cloning with Sanitization

Clone Wizard:

1. Select source environment (production)
2. Choose target (new staging environment)
3. Select sanitization preset (recommended)
4. Choose target server (same or different)
5. Configure resources (CPU, RAM, disk)
6. Deploy cloned environment

Data Sanitization:

• Email addresses: [email protected]
• Passwords: Reset to temporary password
• API keys: Removed (Stripe, payment gateways)
• Mail queue: Cleared (prevent accidental sends)
• Scheduled actions: Disabled (prevent duplicate crons)

Clone Time Estimation:

Database size: 500 MB → ~2 minutes
Filestore size: 2 GB → ~5 minutes
Total clone time: ~7 minutes

3. Multi-Cloud Backups

7 Storage Providers Supported:

Backup Features:

• GFS retention (daily, weekly, monthly, yearly)
• Encrypted at rest (AES-256)
• Verified after upload (SHA-256 checksums)
• Automated scheduling (daily at 2 AM)
• Manual on-demand backups
• Cross-provider redundancy

4. Custom Domains with Auto-SSL

Domain Management:

• System-generated: myproject-prod.oec.sh
• Custom domains: erp.mycompany.com
• Wildcard SSL: *.mycompany.com
• Multi-domain per environment

SSL Automation:

• Let's Encrypt certificates (free, auto-renewed)
• DNS verification (Cloudflare, Route53, DigitalOcean)
• HTTP verification (manual DNS)
• 90-day validity, renewed at 60 days
• Zero downtime during renewal

DNS Provider Integration:

Add Custom Domain: erp.mycompany.com
    ↓
1. Verify domain ownership (DNS check)
2. Configure Traefik routing
3. Request Let's Encrypt certificate
4. Complete DNS-01 challenge (automatic)
5. Certificate issued
6. Update environment URL
    ↓
HTTPS Ready: https://erp.mycompany.com

5. Netdata Monitoring

Monitoring Architecture:

OEC.SH Platform (Netdata Parent)
    ↑ (Streaming API key authentication)
Customer Server 1 (Netdata Child)
Customer Server 2 (Netdata Child)
Customer Server 3 (Netdata Child)

Metrics Collected:

• System: CPU usage, memory, disk I/O, network
• Docker: Container stats (per environment)
• PostgreSQL: Connections, queries, locks, cache hit ratio
• Odoo: HTTP requests, response times, worker status
• Disk: Space usage, IOPS, latency
• Network: Bandwidth, packet loss, connections

Alert Configuration:

• CPU usage >80% for 5 minutes
• Memory usage >90% for 5 minutes
• Disk usage >85%
• Container down (health check failed)
• PostgreSQL connections >80% of max
• Replica lag >100 MB or >30 seconds

Monitoring Dashboard:

• Real-time metrics (1-second resolution)
• Historical data (24 hours by default)
• Per-environment breakdowns
• Capacity planning insights
• Alert history and acknowledgment

6. RBAC Permission System

3-Tier Permission Hierarchy:

Portal Level (Platform Administration)
├── portal.admin (full platform access)
└── portal.support (view all, limited actions)

Organization Level (Team Management)
├── org.projects.create (create projects)
├── org.servers.create (add servers)
├── org.members.manage (invite/remove members)
├── org.billing.manage (subscription, invoices)
└── 30+ organization permissions

Project Level (Environment Management)
├── project.environments.create
├── project.environments.deploy
├── project.backups.create
├── project.backups.restore
└── 20+ project permissions

6 System Roles:

Permission Examples:

• org.projects.create - Create new projects
• org.servers.delete - Delete servers
• project.environments.deploy - Deploy environments
• project.backups.restore - Restore from backups
• org.billing.view - View invoices and usage
• org.members.manage - Invite/remove team members

Permission Enforcement:

• Backend: @require_permission("permission.code") decorator
• Frontend: <AbilityGate can="permission.code"> component
• API: Returns 403 Forbidden if unauthorized
• Cache: Redis-cached abilities (5-min TTL)

Next Steps

Quick Start Guide (15 Minutes)

Follow these 6 steps to deploy your first Odoo environment:

1. Create Account & Organization

   • Sign up with email
   • Verify email address
   • Set up 2FA (recommended)
   • Time: 3 minutes

2. Add Your First Server

   • Prepare server (Ubuntu 20.04+, Docker)
   • Add server to OEC.SH
   • Test SSH connection
   • Time: 5 minutes

3. Configure Storage Provider

   • Choose provider (Cloudflare R2 recommended)
   • Add credentials
   • Test connection
   • Time: 3 minutes

4. Create Your First Project

   • Connect Git repository (GitHub/GitLab)
   • Select Odoo version (18.0 recommended)
   • Configure project settings
   • Time: 2 minutes

5. Deploy First Environment

   • Create development environment
   • Allocate resources (2 CPU, 4 GB RAM)
   • Deploy and monitor progress
   • Time: 5 minutes (includes deployment)

6. Access Your Odoo Instance

   • Open environment URL
   • Login with default credentials
   • Change admin password
   • Start building!

Total Time: 15-20 minutes from signup to running Odoo instance

Core Features to Explore

After deploying your first environment, explore these key features:

Production Readiness:

• Custom Domains - Configure erp.yourcompany.com
• SSL Certificates - Automatic Let's Encrypt
• Backup Policies - Automated daily backups
• Read Replicas - High availability (Odoo 18+)

Team Collaboration:

• Invite Team Members - Add developers, clients
• Role-Based Access - Control permissions
• Git Connections - Shared repository access
• Project Members - Project-specific access

Advanced Workflows:

• Environment Cloning - Copy production to staging
• Automated Deployments - Deploy on git push
• Monitoring Setup - Track performance
• Import from Odoo.sh - Migrate existing projects

Technical Resources

Documentation Sections:

• Features - Comprehensive feature documentation
• API Reference - REST API documentation
• Guides - Best practices and workflows
• Troubleshooting - Common issues and solutions

Support Channels:

• Community: Discord server (https://discord.gg/CDFyF9Ek (opens in a new tab))
• Email: [email protected] (response: 24-48 hours)
• Priority Support: Slack channel (Professional+ plans)
• Enterprise Support: Dedicated account manager

External Resources:

• GitHub: https://github.com/oecsh/platform (opens in a new tab)
• Status Page: https://status.oec.sh (opens in a new tab)
• Blog: https://oec.sh/blog (opens in a new tab)
• Changelog: https://oec.sh/changelog (opens in a new tab)

Who Should Use OEC.SH?

✅ Great Fit For:

• Digital agencies managing 5+ Odoo client projects
• Odoo developers needing staging/production environments
• SaaS companies building on Odoo
• Enterprises with BYOS requirements
• Organizations needing advanced RBAC and audit trails
• Teams requiring flexible multi-environment hosting

❌ Not Ideal For:

• Non-technical users without Git/Docker knowledge
• Single Odoo instance with no development needs
• Legacy Odoo versions (pre-14.0)
• Windows-based deployments (Linux only)
• Teams requiring managed application support

Frequently Asked Questions

General Questions

Q: What versions of Odoo are supported? A: Odoo 14.0, 15.0, 16.0, 17.0, 18.0, 19.0. Official Odoo images or custom Docker images.

Q: Can I use Odoo Enterprise? A: Yes, if you have an Odoo Enterprise license. Contact Odoo directly for licensing.

Q: Is OEC.SH affiliated with Odoo S.A.? A: No, OEC.SH is an independent hosting platform. Odoo Enterprise licenses must be purchased separately.

Q: What operating systems are supported? A: Ubuntu 20.04+, Debian 11+. CentOS, Rocky Linux, and Alpine Linux are supported with multi-distro updates (Sprint 2E28).

Technical Questions

Q: How many projects can I deploy per server? A: Depends on resources. Typical: 3-10 projects per server (4-8 CPU cores, 8-16 GB RAM).

Q: Can I SSH into my environments? A: You can SSH into BYOS servers. For environment debugging, use docker exec commands via the API or UI.

Q: How are backups encrypted? A: Backups are encrypted at rest using AES-256 by the storage provider. In-transit encryption via HTTPS/TLS.

Q: What is the RTO/RPO for disaster recovery? A: RTO (Recovery Time Objective): 15-30 minutes. RPO (Recovery Point Objective): Last automated backup (daily at 2 AM).

Migration Questions

Q: Can I import my existing Odoo.sh project? A: Yes, use the Migration Wizard (Sprint 2E7). Import backup from Odoo.sh, deploy to OEC.SH environment.

Q: Can I export my data and leave OEC.SH? A: Yes, download backups anytime (PostgreSQL dump + filestore). No lock-in, standard formats.

Q: How long does migration take? A: 15-30 minutes for typical projects. Larger databases (10+ GB) may take 1-2 hours.

Related Documentation

Getting Started:

• Create Account & Organization - Sign up and initial setup
• Add Your First Server - BYOS server setup
• Configure Storage Provider - Cloud storage setup
• Create Your First Project - Project creation
• Deploy First Environment - Environment deployment

Core Features:

• Environments - Environment management
• Deployments - Deployment workflows
• Backups - Backup and restore
• Servers - Server management
• Custom Domains - Domain and SSL setup

Advanced Features:

• Read Replicas - PostgreSQL high availability
• Environment Cloning - Clone with sanitization
• Netdata Monitoring - Performance monitoring
• RBAC Permissions - Access control
• Migration from Odoo.sh - Import existing projects

Last Updated: December 11, 2024 Applies to: OEC.SH v2.0+ Related Sprint: Sprint 2E42 - Phase 1 Documentation Next Steps: Create Account & Organization →