Skip to main content
The OroCloud application maintenance tool helps you run and control complex maintenance operations on your Oro application environment hosted in OroCloud.

​
Getting connected

Before running any maintenance commands, you need access to the OroCloud environment via VPN and SSH.
1

Connect via VPN

Use your .ovpn configuration file to connect to OroCloud via OpenVPN. See Connect VPN for OS-specific instructions.
2

Connect via SSH

Configure your password and SSH key as described in OroCloud Onboarding, then connect via SSH using:
  • The IP address and username provided by Oro Support, or
  • The gcloud CLI tool: gcloud compute ssh ocom-yourproject-prod1-maint1 --internal-ip

​
Key maintenance commands

Once connected, run orocloud-cli without parameters to list all available commands.
OroCloud maintenance commands may affect application performance. Use them with care. Contact the OroCloud or Oro Support team if you have questions.

​
Deploy

To deploy an Oro application with default installation parameters: 
orocloud-cli deploy
If the application is already deployed, this command is restricted. Contact Oro Support for a full re-deploy from scratch.

​
Upgrade

Choose the upgrade mode based on your requirements: 
orocloud-cli upgrade
This command:
  1. Enables maintenance mode
  2. Stops services (consumers, cron, websocket)
  3. Checks out the application code from the specified tag, branch, or commit
  4. Installs external dependencies via composer install
  5. Runs oro:platform:update including assets
  6. Warms up layout caches
Once cache warmup completes, maintenance mode is turned off.
Create a backup before launching an upgrade. If the upgrade fails, you can roll back to the previous state.

​
Application packages

For Oro applications version 5.0 and above, you can use pre-built application packages to speed up upgrades: 
# Build a package
orocloud-cli app:package:build [git-reference]

# List available packages
orocloud-cli app:package:list

# Deploy a package
orocloud-cli app:package:deploy [package]

# Build and deploy in one step
orocloud-cli app:package:upgrade [git-reference]
Using pre-built packages significantly reduces upgrade time and maintenance mode duration:
MethodTotal timeMaintenance mode
orocloud-cli upgrade~1300s~800s
orocloud-cli app:package:upgrade~750s~230s
orocloud-cli app:package:deploy (pre-built)~400s~230s

​
Backup

# Create a backup
orocloud-cli backup:create [--label=my-backup]

# List backups
orocloud-cli backup:list

# Restore from backup
orocloud-cli backup:restore {backup_date}
Restoring a backup recovers both the database and application code, and generates new caches. The command enables maintenance mode automatically and turns it off when complete.
Media files can only be restored via a request to Oro Support.

​
Sanitized backup

Sanitized backups are useful for sharing data with the Oro Support team, local debugging, or transferring data from production to staging. 
# Create sanitized backup
orocloud-cli backup:create:sanitized

# List sanitized backups
orocloud-cli backup:list:sanitized

# Restore from sanitized backup
orocloud-cli backup:restore:sanitized {backup_date}

# Delete sanitized backup
orocloud-cli backup:delete:sanitized [DATE]
The resulting backup is not encrypted and is located alongside regular encrypted backups.

​
Cache management

# Rebuild application cache
orocloud-cli cache:rebuild [--force]

# Update translations
orocloud-cli app:translation:update

# Warm up API and API doc caches
orocloud-cli app:cache:api

​
Application commands

Run any Oro application console command via: 
orocloud-cli app:console oro:user:list
orocloud-cli app:console "oro:user:list --all"
orocloud-cli app:console oro:search:reindex
Any app:console command has a default timeout of 1 hour and a memory limit of 2 GB. Contact support if you need to exceed these limits.

​
Maintenance mode

# Enable maintenance mode
maintenance:on [--force]

# Disable maintenance mode
maintenance:off [--force]
The Oro Support team receives a P1 notification after 1 hour of enabled maintenance mode. Use --downtime-duration and --downtime-comment options to specify custom downtime duration and avoid P1 escalation.

​
Configuration validation

Validate your orocloud.yaml configuration for syntax errors: 
orocloud-cli config:validate
orocloud-cli config:validate /mnt/ocom/app/orocloud.yaml
Valid changes are applied within 10 minutes or automatically during deployments.

​
In this section

Before you begin

Prerequisites: VPN, SSH, and SFTP access setup.

Maintenance commands

Full reference for all orocloud-cli maintenance commands.

Advanced configuration

Advanced orocloud.yaml configuration options.

Environment configuration

Configuration differences across environment types.

Pre-built assets

Upgrade using pre-built application packages.

Patches

How to apply patches to your OroCloud environment.

Error processing

Error processing and log monitoring.

Scheduled tasks

Add or remove scheduled tasks.

Environment variables

Add or remove environment variables.

FAQ

Frequently asked questions about maintenance operations.

Build docs developers (and LLMs) love

Get started for freeTalk to us