wheels deploy exec
Execute commands in deployed containers.
Synopsis
wheels deploy:exec <command> [options]
Description
The wheels deploy:exec
command allows you to execute commands inside deployed Docker containers on your servers. This is useful for running administrative tasks, debugging, or accessing services directly.
Arguments
command
- Command to execute in container (required)
Options
servers=<string>
- Execute on specific servers (comma-separated list)service=<string>
- Service to execute in: app or db (default: app)--interactive
- Run command interactively (default: false)
Examples
List files in application container
wheels deploy:exec "ls -la"
Run database migrations
wheels deploy:exec "box run-script migrate"
Access CommandBox REPL interactively
wheels deploy:exec "box repl" --interactive
Execute MySQL commands in database container
wheels deploy:exec "mysql -u root -p" service=db --interactive
Check application logs
wheels deploy:exec "tail -f logs/application.log"
Execute on specific server
wheels deploy:exec "df -h" servers=web1.example.com
How It Works
The command:
Connects to target servers via SSH
Determines the container name based on service
Executes the command using
docker exec
Returns the output or provides interactive access
Service Selection
Application Container (default)
# Executes in the main application container
wheels deploy:exec "ls -la"
Database Container
# Executes in the database container
wheels deploy:exec "mysql -u root -p" service=db --interactive
Interactive vs Non-Interactive
Non-Interactive (default)
Command runs and returns output
Suitable for simple commands
Output is captured and displayed
Interactive Mode
Provides terminal access
Required for commands needing input
Useful for REPL, database shells, etc.
Output Example
Non-interactive command
Wheels Deploy Remote Execution
==================================================
Executing: ls -la
Container: myapp
total 24
drwxr-xr-x 1 root root 4096 Jan 15 14:30 .
drwxr-xr-x 1 root root 4096 Jan 15 14:30 ..
drwxr-xr-x 1 root root 4096 Jan 15 14:30 app
drwxr-xr-x 1 root root 4096 Jan 15 14:30 config
-rw-r--r-- 1 root root 512 Jan 15 14:30 box.json
-rw-r--r-- 1 root root 256 Jan 15 14:30 server.json
Multiple servers
Wheels Deploy Remote Execution
==================================================
Executing: uptime
Container: myapp
Server: web1.example.com
------------------------------
14:35:22 up 45 days, 3:21, 0 users, load average: 0.15, 0.12, 0.18
Server: web2.example.com
------------------------------
14:35:23 up 32 days, 7:45, 0 users, load average: 0.23, 0.19, 0.21
Common Use Cases
Administrative Tasks
# Clear application cache
wheels deploy:exec "box run-script clearCache"
# Run scheduled tasks
wheels deploy:exec "box task run maintenance"
# Check disk usage
wheels deploy:exec "df -h /app"
Database Operations
# MySQL backup
wheels deploy:exec "mysqldump -u root myapp > /backup/myapp.sql" service=db
# PostgreSQL vacuum
wheels deploy:exec "psql -U postgres -c 'VACUUM ANALYZE;'" service=db
# Check database size
wheels deploy:exec "mysql -u root -e 'SELECT table_schema, SUM(data_length + index_length) / 1024 / 1024 AS size_mb FROM information_schema.tables GROUP BY table_schema;'" service=db
Debugging
# View application logs
wheels deploy:exec "tail -n 100 /app/logs/application.log"
# Check running processes
wheels deploy:exec "ps aux"
# Monitor resource usage
wheels deploy:exec "top -b -n 1"
# Check environment variables
wheels deploy:exec "env | grep WHEELS"
File Management
# Create backup
wheels deploy:exec "tar -czf /tmp/backup.tar.gz /app/uploads"
# Check file permissions
wheels deploy:exec "ls -la /config"
# Remove old logs
wheels deploy:exec "find /app/logs -name '*.log' -mtime +30 -delete"
Security Considerations
Command Injection: Commands are passed directly to the shell
Permissions: Runs with container user permissions
Sensitive Data: Be careful with commands that expose secrets
Audit Trail: Commands are not logged by default
Limitations
Cannot execute commands requiring GUI
Interactive mode requires TTY support
Output limited by SSH buffer size
No automatic error handling
Best Practices
Quote Complex Commands: Use quotes for commands with special characters
Test First: Test commands locally before running in production
Use Service Parameter: Specify service explicitly for clarity
Avoid Sensitive Output: Redirect sensitive data to files
Check Exit Codes: Verify command success in scripts
Troubleshooting
Container Not Found
Verify deployment is active
Check container name matches service name
Ensure Docker is running
Permission Denied
Check SSH user has Docker access
Verify container user permissions
Use sudo if necessary (configure in deploy.json)
Command Not Found
Ensure command exists in container
Check PATH environment variable
Use full path to executables
Interactive Mode Issues
Ensure terminal supports TTY
Use SSH directly for complex interactions
Check SSH client configuration
See Also
wheels deploy:status - Check deployment status
wheels deploy:logs - View deployment logs
wheels deploy:push - Deploy application
Last updated
Was this helpful?