Custom Edge Deployment#

Overview#

Custom Edge Deployment allows us to deploy custom Docker Compose configurations directly to edge devices.

Key Features:#

  • Direct deployment of custom Docker Compose configurations

  • Preview changes when deploying to an existing deployment

  • Append or replace services in running deployments

When to Use Custom Edge Deployment vs OctaiPipe Steps#

  • Use Custom Edge Deployment when you need:

    • Custom container configurations

    • Direct control over Docker Compose settings

    • Deployment of third-party services

    • Fine-grained control over container networking and volumes

  • Use OctaiPipe Steps when you want:

    • Pre-configured OctaiPipe functionality

    • Abstracted pipeline management

    • Built-in integration with OctaiPipe features

    • Simplified deployment without Docker configuration

Basic Usage#

Prerequisites#

  • Registered edge device(s) in OctaiPipe

  • Valid Docker Compose configuration file

Standard Interface#

For most deployment scenarios, use the simple OctaiPipe interface function:

from octaipipe.deployment import deploy_to_edge_custom

result = deploy_to_edge_custom(
    docker_compose_path='path/to/docker-compose.yml',
    device_ids=['device-id'],
    name='my-deployment',
    description='Custom edge deployment example',
    device_groups=['group1'],  # Optional device groups
    append=False  # Set to True to append to existing deployment
)

This simplified interface provides the core functionality needed for most custom edge deployments.

Configuration Management#

Idempotent Deployments and Updates#

Docker Compose configurations are idempotent - the last submitted configuration defines the complete state of your deployment. You can:

Replace Configuration (default behavior):

  • Replace entire configuration

deploy_to_edge_custom(
    docker_compose_path='path/to/docker-compose.yml',
    device_ids=['device-id'],
    append=False  # Default behavior
)

Append Services:

  • Add new services while preserving existing deployed services, this functionality to merge configs is available if docker-compose is installed locally

deploy_to_edge_custom(
    docker_compose_path='additional-services.yml',
    device_ids=['device-id'],
    append=True  # Preserve existing services
)

Template Variables#

Use template variables in your Docker Compose files that will be automatically replaced during deployment.

services:
  myservice:
    container_name: myapp-{{ device_id }}  # Replaced with device ID
    environment:
      - DEPLOYMENT_ID={{ deployment_id }}  # Replaced with deployment ID
    volumes:
      - ./data-{{ device_id }}:/data      # Useful for device-specific paths
Available template variables:

  • {{ device_id }} - Replaced with the target device’s ID

  • {{ deployment_id }} - Replaced with the current deployment ID

Advanced Usage#

For scenarios requiring more control over the deployment process, you can use the DockerComposeDeploy class directly:

Advanced Deployment Example#

from octaipipe.deployment.edge.docker_compose_deploy import DockerComposeDeploy

# Initialize deployment
deployer = DockerComposeDeploy(
    docker_compose_path='path/to/docker-compose.yml',
    device_ids=['device-id'],
    device_groups=['group1'],  # Optional device groups
    deployment_id='new-or-existing-deployment-id',
    name='my-deployment',
    description='Custom edge deployment example'
)

# Deploy
result = deployer.deploy()

Advanced Configuration Management#

Preview and Validation#

DockerComposeDeploy automatically validates configurations and shows a preview diff of changes:

# Preview changes using current configuration
deployer.preview_changes()

# Or preview changes with a specific configuration
new_config: dict = {'services': {...}}
deployer.preview_changes(new_compose=new_config)

Example:

Docker-Compose Removed
- services:
-   service1:
-     image: alpine:latest
-     container_name: container1

Docker-Compose Added
+ services:
+   service2:
+     image: alpine:latest
+     container_name: container2
+     environment:
+       - NEW_VAR=value

Best Practices#

  1. Review change previews before deploying updates

  2. Use get_existing_compose() to view the existing state

  3. Use meaningful container names and labels

  4. Consider using template variables for device-specific configurations

Example Workflows#

Initial Deployment#

deployer = DockerComposeDeploy(
    docker_compose_path='initial-compose.yml',
    device_ids=['device1'],
    name='my-deployment'
)
deployer.deploy()

Updating Existing Deployment#

# Add new services to existing deployment
deployer = DockerComposeDeploy(
    docker_compose_path='additional-services.yml',
    device_ids=['device1'],
    deployment_id='existing-deployment-id'
)

# Preview changes before deploying
deployer.preview_changes()

# Deploy with append=True to preserve existing services
deployer.deploy(append=True)

Monitoring#

View deployment status and container states through the OctaiPipe portal or API.