Skip to main content
Zerops provides Docker support through dedicated Virtual Machine (VM) environments, ensuring maximum compatibility and isolation while maintaining integration with the broader Zerops ecosystem.

​
Supported Versions

When importing a Docker service, use version format:
  • docker@27

​
Why VMs?

While Zerops primarily uses native Linux containers for optimal performance, this VM-based approach allows you to run virtually any Docker container while maintaining Zerops’ robust infrastructure management. You can learn more about differences between Containers and Virtual Machines in Zerops.

​
Important Considerations

Before using Docker services, consider these important aspects:

​
Virtual Machine Environment

Docker services in Zerops operate in a full VM environment, which has several implications:
  • Slower Boot Times: VMs require more time to initialize due to full kernel boot
  • Higher Resource Usage: VMs include additional system overhead compared to native containers
  • Scaling Limitations:
    • Vertical scaling requires VM restart
    • Resources must be set as fixed values (no min-max ranges)
    • Zerops automatically restarts the VM when resource values are changed in UI
  • Storage Management: Disk space can only be increased, not decreased without recreation
  • Build Phase Limitations: Build phase runs in containers, not in the VM environment

​
Advantages

Despite these limitations, Docker services offer some benefits:
  • Broad Compatibility: Run almost any Docker container with minimal modification
  • Familiar Environment: Standard Docker runtime environment

​
Configuration Guide

​
Basic Structure

Docker services in Zerops are configured through the zerops.yaml file. Here’s a typical configuration pattern:
zerops.yaml
zerops:
  - setup: app
    run:
      prepareCommands:
        - docker image pull <your-image>:<version>  # Always use specific version tags
      start: docker run --network=host <your-image>:<version>
      ports:
        - port: <port-number>
          httpSupport: true
Always use specific version tags (like 1.0.0) instead of :latest. Zerops caches the prepareCommands output, which means a new :latest image won’t be automatically pulled on subsequent deployments unless the cache is manually cleared or the commands change.
Refer to the Docker recipe repository for an example configuration.
We are actively working on improving the speed of image caching after run.prepareCommands and reducing the startup time of runtime VMs. These improvements will be released in future updates.

​
Network Configuration

Docker services require the --network=host flag for proper integration with Zerops:
  • Direct Port Management: Ports are managed through zerops.yaml
  • Simplified Configuration: Avoids double port exposure in Docker and Zerops
  • Native Performance: Direct access to host networking

​
Environment Variables

When using Docker services, there’s an additional layer to consider since environment variables defined in Zerops must be explicitly passed to your Docker containers.

​
1. Defining Variables in Zerops

Define your environment variables in the run.envVariables section of your zerops.yaml:
zerops.yaml
zerops:
  - setup: app
    run:
      envVariables:
        DB_HOST: ${db_hostname}
        DB_PORT: ${db_port}

​
2. Passing Variables to Docker Containers

For single containers, pass variables using the -e flag:
zerops.yaml
run:
  prepareCommands:
    - docker image pull my-application:1.0.0
  start: docker run -e DB_HOST -e DB_PORT --network=host my-application:1.0.0
For Docker Compose setups, pass environment variables in your docker-compose.yaml:
docker-compose.yaml
services:
  api:
    image: my-application:1.0.0
    network_mode: host
    environment:
      - DB_HOST
      - DB_PORT

​
Docker Compose Support

For projects using Docker Compose, additional configuration is required:

​
1. File Deployment

zerops.yaml
build:
  deployFiles: ./docker-compose.yaml
  addToRunPrepare: ./docker-compose.yaml

​
2. Network Mode

docker-compose.yaml
services:
  your-service:
    image: your-image:1.0.0
    network_mode: host

​
3. Start Command

zerops.yaml
run:
  start: docker compose up --force-recreate

​
Implementation Examples

​
Single Container

zerops.yaml
zerops:
  - setup: app
    run:
      prepareCommands:
        - docker image pull crccheck/hello-world:1.0.0
      start: docker run --network=host crccheck/hello-world:1.0.0
      ports:
        - port: 8000
          httpSupport: true

​
Single Service with Docker Compose

zerops.yaml
zerops:
  - setup: api
    build:
      deployFiles: ./docker-compose.yaml
      addToRunPrepare: ./docker-compose.yaml
    run:
      prepareCommands:
        - docker compose pull api
      start: docker compose up api --force-recreate
      ports:
        - port: 8000
          httpSupport: true

​
Multiple Services with Docker Compose

zerops.yaml
zerops:
  - setup: apps
    build:
      deployFiles: ./docker-compose.yaml
      addToRunPrepare: ./docker-compose.yaml
    run:
      prepareCommands:
        - docker compose pull
      start: docker compose up --force-recreate
      ports:
        - port: 8000
          httpSupport: true

​
Scaling Operations

Docker services in Zerops have specific scaling characteristics:

​
Vertical Scaling

  • Resources must be defined with fixed values instead of min-max ranges
  • CPU, RAM, and disk are specified as single values: 
    verticalAutoscaling:
  cpu: 3
  ram: 2
  disk: 20
  • Any change to these values through the UI triggers an automatic VM restart
  • Plan your resource allocation carefully to minimize scaling operations

​
Horizontal Scaling

  • Still supports multiple containers through minContainers and maxContainers
  • Consider breaking large services into smaller components
  • Implement proper health checks for reliable scaling
  • Use horizontal scaling when possible to avoid VM restarts

​
Best Practices

​
Image Management

  • Always use specific version tags instead of :latest to prevent caching issues
  • Keep images small to reduce deployment time
  • Use multi-stage builds for optimized images

​
Resource Planning

  • Account for VM overhead in resource allocation
  • Plan for longer initialization times
  • Consider the impact on scaling operations

​
Migration Consideration

  • Evaluate if your workload could run on native containers
  • Consider gradual migration for complex applications
  • Balance development effort against operational benefits

​
Limitations and Workarounds

​
Build Phase

Since the build phase runs in containers rather than VMs:
  • Use run.prepareCommands for Docker-specific build steps
  • Consider external CI/CD for complex Docker builds
  • Leverage pre-built images when possible

​
Support

For advanced configurations or custom requirements:

Build docs developers (and LLMs) love

Get started for freeTalk to us