--- name: oro-cloud description: OroCloud Enterprise Cloud operations reference covering deployment, upgrades, maintenance commands, backups, environment configuration, monitoring, and cloud architecture. Use when deploying to OroCloud, running maintenance operations, configuring cloud environments, troubleshooting cloud deployments, or planning cloud infrastructure. --- # OroCommerce Cloud (OroCloud) Operations and maintenance reference for OroCloud Enterprise environments. Docs: https://doc.oroinc.com/cloud/ ## Architecture Overview OroCloud runs on GCP or OCI with fully redundant infrastructure: | Component | Details | |---|---| | CDN/LB | GCP CDN or Cloudflare (DDoS protection, edge caching) | | Web Nodes | >= 2 nodes across availability zones, Nginx + PHP-FPM | | Database | PostgreSQL with automatic failover (primary + secondary zone) | | Search | Elasticsearch cluster (EE) | | Message Queue | RabbitMQ cluster (EE) | | Cache | Redis Sentinel cluster | | File Storage | GridFS clustered (MongoDB) | | SMTP | Dedicated SMTP relay (multi-relay HA) | All resources within a single region, distributed across zones. ## EE-Specific Stack (Always Available) Since this is Enterprise Cloud, these are always available (not optional): - **Elasticsearch** >= 8.4.1 for search indexing (`ORO_SEARCH_URL`) - **RabbitMQ** 3.12.x for message queue (`ORO_MQ_DSN=amqp://...`) - **Redis** 7.2.x for cache + sessions - **GridFS** (MongoDB) for file storage - **Organization Types** for multi-org feature restrictions - **Field ACL** for field-level permissions ## Maintenance Tool (orocloud-cli) All operations on OroCloud environments use `orocloud-cli`. ### Deployment ```bash orocloud-cli deploy # initial deployment ``` ### Upgrades ```bash orocloud-cli upgrade # with downtime (full) orocloud-cli upgrade:rolling # no downtime (safe for minor versions) orocloud-cli upgrade:source # code-only, no platform:update ``` Rolling/source upgrades: safe only when DB schema doesn't change. Do NOT drop tables/columns or alter column types during rolling upgrades. ### Application Packages (v5.0+) Prebuilt packages shared across environments (dev/stag/uat/prod): ```bash orocloud-cli app:package:build 5.1.0 --label="GA Release" orocloud-cli app:package:list orocloud-cli app:package:deploy --rolling harborio.oro.cloud/proj-stag1/orocommerce:5_1_0 orocloud-cli app:package:upgrade --rolling 5.1.0 ``` Significantly faster than standard upgrade (400s vs 1300s). ### Backups ```bash orocloud-cli backup:create [--label=my-backup] orocloud-cli backup:list orocloud-cli backup:restore {backup_id} ``` Automatic backup schedule: - Hourly (retained 7 days) - Weekly (retained 4 weeks) - Monthly (retained 12 months) Encrypted with AES-256. RTO: 30 min to several hours. ### Maintenance Mode ```bash orocloud-cli maintenance:enable orocloud-cli maintenance:disable ``` ### Status & Logs ```bash orocloud-cli log:list orocloud-cli log:view {log_file} orocloud-cli config:validate orocloud-cli config:help ``` ## Environment Configuration (orocloud.yaml) All configuration managed via `orocloud.yaml` in the repository root. Docs: https://doc.oroinc.com/cloud/maintenance/advanced-use/ The maintenance agent merges three YAML files: 1. `/mnt/{ocom}/app/orocloud.yaml` (host-level) 2. `/mnt/{ocom}/app/www/orocloud.yaml` (repo root, common to all envs) 3. `/mnt/{ocom}/app/www/orocloud_{dev,stag,uat,prod}.yaml` (env-specific) Changes auto-applied within 10 minutes or on next deployment. Validate: `orocloud-cli config:validate` **Important:** Use single quotes only (no double quotes). Use spaces, not tabs. ### Deployment Configuration ```yaml orocloud_options: deployment: install_commands: - 'oro:install --sample-data=n --user-name=admin ...' upgrade_commands: - 'oro:platform:update' pre_upgrade_commands: - 'oro:maintenance-notification --message=Deploy\ start' post_upgrade_commands: - 'oro:maintenance-notification --message=Deploy\ finish' pre_maintenance_commands: [] # before maintenance lock post_maintenance_commands: [] # after maintenance unlock composer_command: '{{composer_cmd}} install --no-dev --optimize-autoloader' git_clone_recursive: true db_extensions: - 'uuid-ossp' - 'pgcrypto' before_backup_create_commands: [] after_backup_create_commands: [] ``` ### Application Configuration ```yaml orocloud_options: application: maintenance_page: 'public/maintenance.html' error_pages: 403: 'public/403.html' 502: 'public/502.html' web_backend_prefix: '/admin' consumers_debug_mode: false env_vars: COMPOSER_AUTH: '{"http-basic":{"repo.example.com":{"username":"u","password":"p"}}}' ``` ### Webserver Configuration ```yaml orocloud_options: webserver: header_x_frame: true redirects_map: '/old-url': '/new-url' redirects_map_include: - 'redirects/website1.yml' locations: 'root': type: 'php' location: '~ /index\.php(/|$)' auth_basic_enable: true auth_basic_userlist: user1: { ensure: 'present', password: 'pass' } allow: ['127.0.0.1'] deny: ['all'] 'admin': type: 'php' location: '~ /index\.php/admin(/|$)' auth_basic_enable: true auth_basic_userlist: admin: { ensure: 'present', password: 'pass' } access_policy: 'ip': 'type': 'allow' 'allow': ['192.168.0.0/16'] 'deny': ['10.0.0.1'] 'country': 'type': 'deny' 'allow': ['US', 'CA'] 'ua': 'deny': ['AcoiRobot', 'Wget'] limit_whitelist: - '8.8.8.8' limit_whitelist_uri: - '~(^/api/(.*))' newrelic_options: license_key: '' blackfire_options: agent_enabled: true server_id: '' server_token: '' ``` Location types: `php`, `static`, `rewrite`. WAF: IP/ASN/country/user-agent filtering + rate limiting + bot detection. HTTP 451 returned for WAF blocks. ### Scheduled Tasks ```yaml orocloud_options: schedule: 'my_task': command: 'orocloud-cli app:console "my:command"' minute: '*/5' hour: '*' ``` ## Environment Variables Set via `orocloud_options.application.env_vars`. Standard Oro env vars (`ORO_DB_URL`, `ORO_MQ_DSN`, etc.) are pre-configured. Never set empty values (`ORO_VAR=` or `ORO_VAR=NULL`); omit the variable instead. ## Per-Environment Configuration Use environment-specific YAML files (recommended approach): ``` orocloud.yaml # common to all environments orocloud_dev.yaml # dev-only overrides orocloud_stag.yaml # staging-only overrides orocloud_prod.yaml # production-only overrides ``` ### Real-World Examples **Production** (`orocloud.yaml`) -- redirect root to storefront: ```yaml orocloud_options: webserver: redirects_map: '/': '/home/' ``` **Staging** (`orocloud_stag.yaml`) -- restrict outbound email: ```yaml orocloud_options: mail: whitelist: - 'yourcompany.com' - 'agency.com' ``` ### Cloud-Specific Symfony Config (config_cloud.yml) For OroCloud deployments, create `config/config_cloud.yml` importing prod config: ```yaml imports: - { resource: config_prod.yml } parameters: env(ORO_LOG_PATH): "php://stderr" env(ORO_MULTIHOST_ENABLED): true sftp_root_path: '%env(ORO_SFTP_ROOT_PATH)%' env(ORO_SFTP_ROOT_PATH): '%kernel.project_dir%/var/sftp' gaufrette_adapter.public: 'gridfs:%env(ORO_MONGODB_DSN_PUBLIC)%' gaufrette_adapter.private: 'gridfs:%env(ORO_MONGODB_DSN_PRIVATE)%' gaufrette_adapter.import_files: 'local:%env(ORO_IMPORT_EXPORT_PATH)%' env(APP_RUNTIME): Oro\Bundle\DistributionBundle\Runtime\CloudRuntime ``` Key differences from self-hosted prod: - Logs to stderr (captured by cloud infra) - File storage via GridFS (not local filesystem) - Cloud-specific runtime class - SFTP root path for file-based imports Docs: https://doc.oroinc.com/cloud/maintenance/dif-environments/ ## Patching ```bash orocloud-cli patch:apply /path/to/patch.diff # dry-run by default orocloud-cli patch:apply /path/to/patch.diff --force # actually apply orocloud-cli patch:list orocloud-cli patch:view /path/to/applied.patch orocloud-cli patch:revert /path/to/applied.patch --force ``` Patches removed on upgrade. Composer patches plugin (`cweagans/composer-patches`) also supported for vendor package patches. Docs: https://doc.oroinc.com/cloud/maintenance/patches/ ## Cron & Consumers Cron and MQ consumers are managed by Oro's infrastructure. Only consumers running before an upgrade will restart after. Custom cron via `CronCommandScheduleDefinitionInterface` or `orocloud.yaml` schedule. Custom scheduled tasks via `orocloud_options.schedule`. Docs: https://doc.oroinc.com/cloud/maintenance/scheduled-tasks/ ## Security Docs: https://doc.oroinc.com/cloud/security/ - **Network segmentation**: Application subnet (isolated) + Maintenance DMZ subnet - **No public IPs** on application nodes; traffic via LB or Cloudflare tunnel only - **VPN access**: OpenVPN with MFA for maintenance SSH (port 31194 UDP) - **WAF**: Bot detection (testcookie), request scanning (Naxsi), rate limiting - **PCI-DSS certified** (yearly reassessment) - **TLS termination**: at Cloudflare or GCP LB; HTTPS to app nodes not required Access policy configurable via `orocloud.yaml` `access_policy` section (IP, ASN, country, user-agent filtering). ## Monitoring Docs: https://doc.oroinc.com/cloud/monitoring/ Oro monitors internally (no customer access to internal alerts): - **OS metrics**: CPU, disk, RAM, swap, network, process count - **Component metrics**: Nginx, PostgreSQL, Redis, RabbitMQ, Elasticsearch - **Application metrics**: web checks, SSL, DNS, HTTP status, error rates, MQ queues/consumers, orders/users/SKU statistics Customer-available monitoring: - **GCP Operations Suite**: uptime checks, OS metrics (Metrics Explorer) - **NewRelic** and **Blackfire**: supported with your own license - **Logs**: `orocloud-cli log:list` / `log:view` Incident response: warning (routine) and critical (incident) thresholds. Customers notified by email for incidents. ## Disaster Recovery - Cold DR location (different IaaS region) - RPO: last daily backup - Minimum RTO: 60 minutes - Automatic DNS failover (if Oro-managed domain) - Primary and DR IPs provided at onboarding - DR approval required from customer before activation ## Key Differences from Self-Hosted | Aspect | Self-Hosted | OroCloud | |---|---|---| | Deployment | Manual or CI/CD | `orocloud-cli upgrade` | | Elasticsearch | Optional (EE) | Always available (cluster) | | RabbitMQ | Optional (EE) | Always available (cluster) | | File Storage | Local FS | GridFS (MongoDB cluster) | | Backups | Your responsibility | Automated (hourly/weekly/monthly) | | SSL/CDN | Your config | Managed (GCP CDN or Cloudflare) | | Scaling | Manual | Managed by Oro team | | Patching | Direct server access | `orocloud-cli patch:apply` | | Monitoring | Your tooling | Included (+ GCP suite, NewRelic, Blackfire) | | WAF | Your config | Included (bot detection, rate limiting, geo-blocking) | | Security | Your responsibility | PCI-DSS certified, VPN + MFA | | Config | Server files | `orocloud.yaml` (validated, versioned) |