Deployment Commands

Overview

m87 provides powerful deployment management for running applications on remote devices. Deployments allow you to register jobs that execute automatically when devices come online, making them ideal for managing fleets of intermittently-connected edge devices.

Use deployments when:

Your devices are not always online
You need to deploy to multiple devices
You want automated deployment workflows
You need to observe and monitor running services
You want deployment rollback capabilities

Deploy Command

Add a run spec (docker-compose or custom) to a deployment.

Syntax

m87 <device> deploy <FILE> [OPTIONS]

Options

Flag	Description
`--type <TYPE>`	Spec type: `auto`, `compose`, `runspec`, or `deployment` (default: auto)
`--name <NAME>`	Optional display name for the run spec
`--deployment-id <ID>`	Add to specific deployment (defaults to active deployment)

Examples

# Auto-detect and deploy docker-compose.yml
m87 rpi deploy ./docker-compose.yml

# Explicitly specify compose type
m87 rpi deploy ./docker-compose.yml --type compose

# Deploy with custom name
m87 rpi deploy ./docker-compose.yml --name my-web-app

# Deploy custom run spec YAML
m87 rpi deploy ./custom-spec.yml --type runspec

# Deploy to specific deployment
m87 rpi deploy ./spec.yml --deployment-id dep_123abc

# Deploy complete deployment configuration
m87 rpi deploy ./deployment.yml --type deployment

How Deploy Works

Automatic conversion: Docker Compose files are automatically converted to m87 run specs
Active deployment: If no deployment ID is specified, the file is added to the active deployment
Auto-creation: If no active deployment exists, a new one is created automatically
Execution: The deployment runs when the device is online

The CLI automatically detects whether your file is a Docker Compose file or a custom run spec by looking for the services key in the YAML.

Undeploy Command

Remove a run spec from a deployment.

Syntax

m87 <device> undeploy <JOB_ID> [OPTIONS]

Options

Flag	Description
`--deployment-id <ID>`	Remove from specific deployment (defaults to active)

Examples

# Remove run spec by name
m87 rpi undeploy my-compose

# Remove from specific deployment
m87 rpi undeploy my-compose --deployment-id dep_123abc

# Remove using original file path
m87 rpi undeploy ./docker-compose.yml

Undeploy removes the run spec from the deployment configuration but doesn’t immediately stop running containers. The deployment system handles cleanup according to the spec’s configuration.

Deployment Subcommands

Manage deployments on devices with the deployment subcommand group.

List Deployments

View all deployments for a device.

m87 <device> deployment list

Output includes:

Deployment ID
Creation date
Active status
Number of run specs

Create New Deployment

Create a new deployment.

# Create inactive deployment
m87 <device> deployment new

# Create and activate immediately
m87 <device> deployment new --active

Creating multiple deployments allows you to prepare different configurations and switch between them easily.

Show Deployment Details

View details of a deployment including all run specs.

# Show currently active deployment
m87 <device> deployment show

# Show as YAML
m87 <device> deployment show --yaml

# Show specific deployment by ID
m87 <device> deployment show --deployment-id dep_123abc

# Show specific deployment as YAML
m87 <device> deployment show --deployment-id dep_123abc --yaml

Deployment Status

Check the execution status of a deployment.

# View status of active deployment
m87 <device> deployment status

# View status with logs
m87 <device> deployment status --logs

# Check specific deployment
m87 <device> deployment status --deployment-id dep_123abc --logs

Status information includes:

Deployment execution state
Run spec states (pending, running, completed, failed)
Health check results
Timestamps
Logs (with --logs flag)

Activate Deployment

Set which deployment is active.

# Activate specific deployment
m87 <device> deployment activate dep_123abc

Only one deployment can be active at a time. Activating a new deployment deactivates the previous one.

View Active Deployment

Check which deployment is currently active.

m87 <device> deployment active

Remove Deployment

Delete a deployment.

# Remove deployment (prompts for confirmation)
m87 <device> deployment rm dep_123abc

# Remove without confirmation
m87 <device> deployment rm dep_123abc --force

Removing a deployment cannot be undone. Make sure you have backups if needed.

Clone Deployment

Duplicate an existing deployment.

# Clone deployment (inactive)
m87 <device> deployment clone dep_123abc

# Clone and activate immediately
m87 <device> deployment clone dep_123abc --active

Use cases for cloning:

Create staging/production variants
Test configuration changes safely
Prepare deployment rollbacks

Update Deployment

Modify an existing deployment (advanced).

m87 <device> deployment update [OPTIONS]

The update command supports advanced operations like removing, replacing, moving, and renaming run specs. See m87 <device> deployment update --help for detailed options.

Real-World Workflows

Initial Deployment

# 1. Deploy docker-compose file
m87 rpi deploy ./docker-compose.yml

# 2. Check status
m87 rpi deployment status --logs

# 3. Monitor execution
m87 rpi logs -f

# 1. Deploy web service
m87 rpi deploy ./web/docker-compose.yml --name web

# 2. Deploy API service
m87 rpi deploy ./api/docker-compose.yml --name api

# 3. Deploy database
m87 rpi deploy ./db/docker-compose.yml --name database

# 4. View complete deployment
m87 rpi deployment show --yaml

Update Deployment

# 1. Make changes to docker-compose.yml locally
vim docker-compose.yml

# 2. Remove old version
m87 rpi undeploy my-app

# 3. Deploy new version
m87 rpi deploy ./docker-compose.yml --name my-app

# 4. Monitor deployment
m87 rpi deployment status --logs

Staging and Production

# 1. Create staging deployment
m87 rpi deployment new

# 2. Deploy to staging
m87 rpi deploy ./docker-compose.staging.yml \
  --deployment-id <staging-id> \
  --name staging-app

# 3. Activate staging
m87 rpi deployment activate <staging-id>

# 4. Test staging
m87 rpi deployment status --logs

# 1. Clone staging to production
m87 rpi deployment clone <staging-id>

# 2. Update production config if needed
m87 rpi undeploy staging-app --deployment-id <prod-id>
m87 rpi deploy ./docker-compose.prod.yml \
  --deployment-id <prod-id> \
  --name prod-app

# 3. Activate production
m87 rpi deployment activate <prod-id>

Rollback Deployment

# 1. List deployments to find previous version
m87 rpi deployment list

# 2. Activate previous deployment
m87 rpi deployment activate <previous-deployment-id>

# 3. Verify rollback
m87 rpi deployment status --logs

Fleet Deployment

# Deploy same configuration to multiple devices
for device in rpi1 rpi2 rpi3 edge1 edge2; do
  echo "Deploying to $device..."
  m87 $device deploy ./docker-compose.yml --name fleet-app
done

# Check status across fleet
for device in rpi1 rpi2 rpi3 edge1 edge2; do
  echo "\n=== $device ==="
  m87 $device deployment status
done

Docker Compose Conversion

When you deploy a Docker Compose file, m87 automatically converts it to a run spec.

Example Conversion

Input (docker-compose.yml):

services:
  web:
    image: nginx:alpine
    container_name: web
    restart: unless-stopped
    ports:
      - "80:80"
  
  app:
    build: .
    container_name: app
    restart: unless-stopped
    environment:
      - NODE_ENV=production

Deployed to device:

m87 rpi deploy ./docker-compose.yml --name my-web-app

The CLI handles:

Converting compose format to m87 run spec
Uploading build contexts if needed
Configuring restart policies
Setting up environment variables
Managing container lifecycles

Deployment vs Direct Docker Commands

Feature	Deployment	Direct Docker
Works when offline	✓ Queued for execution	✗ Requires online device
Automatic retry	✓ Built-in	✗ Manual
Health monitoring	✓ Continuous	✗ Manual
Rollback support	✓ Easy	✗ Manual
Fleet management	✓ Centralized	✗ Per-device
Immediate execution	Depends on device	✓ Immediate
Simple one-off tasks	✗ Overhead	✓ Simple

Choose deployments for:

Production applications
Fleet management
Intermittent connectivity
Automated workflows

Choose direct docker commands for:

Development and debugging
One-off tasks
Immediate execution needs
Interactive work

Monitoring Deployments

# View current status
m87 rpi deployment status

# View with execution logs
m87 rpi deployment status --logs

# View logs from deployed containers
m87 rpi logs -f

# View logs with specific tail
m87 rpi logs --tail 100

# Overall device health
m87 rpi status

# View system metrics
m87 rpi metrics

Best Practices

Deployment best practices:

Use version tags - Tag deployments with version numbers for easy tracking
Test in staging - Create staging deployments before production
Keep backups - Clone deployments before making major changes
Monitor logs - Use --logs flag to catch issues early
Use meaningful names - Name run specs clearly with --name flag
Document configs - Add comments to docker-compose files
Regular cleanup - Remove old deployments you no longer need

Docker Integration - Direct Docker commands
Device Access - Monitor deployed applications
File Transfer - Deploy application files

Get Started

Core Concepts

CLI Commands

Guides

Advanced

Deployment Commands

Overview

Deploy Command

Syntax

Options

Examples

How Deploy Works

Undeploy Command

Syntax

Options

Examples

Deployment Subcommands

List Deployments

Create New Deployment

Show Deployment Details

Deployment Status

Activate Deployment

View Active Deployment

Remove Deployment

Clone Deployment

Update Deployment

Real-World Workflows

Initial Deployment

Update Deployment

Staging and Production

Rollback Deployment

Fleet Deployment

Docker Compose Conversion

Example Conversion

Deployment vs Direct Docker Commands

Monitoring Deployments

Best Practices

​Overview

​Deploy Command

​Syntax

​Options

​Examples

​How Deploy Works

​Undeploy Command

​Syntax

​Options

​Examples

​Deployment Subcommands

​List Deployments

​Create New Deployment

​Show Deployment Details

​Deployment Status

​Activate Deployment

​View Active Deployment

​Remove Deployment

​Clone Deployment

​Update Deployment

​Real-World Workflows

​Initial Deployment

​Update Deployment

​Staging and Production

​Rollback Deployment

​Fleet Deployment

​Docker Compose Conversion

​Example Conversion

​Deployment vs Direct Docker Commands

​Monitoring Deployments

​Best Practices

​Related Commands

Overview

Deploy Command

Syntax

Options

Examples

How Deploy Works

Undeploy Command

Syntax

Options

Examples

Deployment Subcommands

List Deployments

Create New Deployment

Show Deployment Details

Deployment Status

Activate Deployment

View Active Deployment

Remove Deployment

Clone Deployment

Update Deployment

Real-World Workflows

Initial Deployment

Update Deployment

Staging and Production

Rollback Deployment

Fleet Deployment

Docker Compose Conversion

Example Conversion

Deployment vs Direct Docker Commands

Monitoring Deployments

Best Practices

Related Commands