feat: initial commit — BMAD tooling, Claude memories, firmware scaffold
Adds the complete project foundation: - BMAD BMM workflow tooling (_bmad/) - Claude slash commands, skills, and project memories (.claude/) - ESP32 firmware scaffold (PlatformIO + Waveshare e-ink driver) - .gitignore excluding _bmad-output/ and .pio/ build artifacts Planning artifacts (PRD, architecture, epics) are intentionally not tracked — they live in _bmad-output/ per project convention. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,364 @@
|
||||
---
|
||||
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: '<key>'
|
||||
blackfire_options:
|
||||
agent_enabled: true
|
||||
server_id: '<id>'
|
||||
server_token: '<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) |
|
||||
Reference in New Issue
Block a user