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 /app/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