Skip to main content

​
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

FlagDescription
--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

​
How Deploy Works

  1. Automatic conversion: Docker Compose files are automatically converted to m87 run specs
  2. Active deployment: If no deployment ID is specified, the file is added to the active deployment
  3. Auto-creation: If no active deployment exists, a new one is created automatically
  4. 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

FlagDescription
--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
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

​
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
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
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

​
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

​
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

FeatureDeploymentDirect 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 executionDepends 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

​
Best Practices

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