Dynamic Compose Reference

In Runtipi version v3.2.0 we added dynamic compose, a simplified and custom version of the docker-compose.yml file that allows for more control on how apps get deployed. For example, you can choose to only use the reverse proxy or only use ports. It also allows extra features like multiple appstores.

For a step-by-step guide on creating dynamic compose files, see Creating a dynamic compose file.

Try it out

You can validate your dynamic compose configuration using the validator below:

Docker Compose to Dynamic Config Converter

Converting an existing docker-compose.yml file to Runtipi’s dynamic compose format can be time-consuming and error-prone. We’ve created a tool to help you automatically convert your Docker Compose files to the dynamic compose format.

Configuration Options Reference

Basic Configuration

These are the most commonly used options when configuring a service:

Port Configuration

Options related to exposing ports:

Example addPorts configuration:

"addPorts": [{
  "containerPort": 8080,
  "hostPort": 8080,
  "tcp": true,
  "udp": false,
  "interface": "127.0.0.1"
}]

Volume Configuration

Options for mounting volumes:

Example volumes configuration:

"volumes": [{
  "hostPath": "/host/path",
  "containerPath": "/container/path",
  "readOnly": false,
  "shared": false,
  "private": false
}]

Network Configuration

Options related to networking:

Health Check Configuration

Options for container health monitoring:

Example healthCheck configuration:

"healthCheck": {
  "test": "curl --fail http://localhost",
  "retries": 3,
  "interval": "30s",
  "timeout": "10s",
  "start_interval": "5s",
  "start_period": "30s"
}

Resource Configuration

Options for container resource limits and deployment:

Example deploy configuration:

"deploy": {
  "resources": {
    "limits": {
      "cpus": "0.5",
      "memory": "512M",
      "pids": 100
    }
  }
}

Example ulimits configuration:

"ulimits": {
  "nproc": {"soft": 10, "hard": 20},
  "nofile": {"soft": 20, "hard": 30}
}

Security Configuration

Options related to container security:

Advanced Configuration

Additional options for fine-tuning:

Example logging configuration:

"logging": {
  "driver": "json-file",
  "options": {
    "max-size": "10m"
  }
}

Dependencies

Options for managing service dependencies:

Example dependsOn configuration:

"dependsOn": {
  "db": {
    "condition": "service_healthy"
  }
}

Architecture Overrides

Options for architecture-specific configurations:

The overrides option allows you to specify different configurations for specific architectures at the top level of your dynamic compose configuration. This is useful when you need to use different Docker images or settings for different CPU architectures (like arm64 vs amd64).

Example overrides configuration:

"overrides": [
  {
    "architecture": "arm64",
    "services": [
      {
        "name": "app",
        "image": "myapp:arm64-latest",
        "environment": {
          "ARCHITECTURE": "arm64"
        }
      }
    ]
  }
]

How Architecture Overrides Work

When Runtipi starts a container, it automatically detects the current system architecture and applies any matching overrides from the overrides array. The system looks for overrides that match the current architecture, then merges those service-specific settings with the base service configuration.

Important aspects of the override system:

• You must include the name field in each service in the overrides to match with the base service
• Only specify the properties that need to be different for each architecture
• Properties from overrides are deep-merged with the base service configurations
• Array properties (like volumes or ports) in overrides completely replace the base arrays rather than being appended

Supported Architectures

Runtipi supports the following architecture types for overrides:

• amd64: Standard 64-bit x86 architecture (also known as x86_64)
• arm64: 64-bit ARM architecture (also known as aarch64)

Complete Example

Here’s a complete example showing how to use architecture overrides:

{
  "services": [
    {
      "name": "media-server",
      "image": "mediaserver:latest",
      "isMain": true,
      "internalPort": 8096,
      "volumes": [
        {
          "hostPath": "${APP_DATA_DIR}/config",
          "containerPath": "/config"
        },
        {
          "hostPath": "${RUNTIPI_MEDIA_DIR}",
          "containerPath": "/media"
        }
      ]
    }
  ],
  "overrides": [
    {
      "architecture": "arm64",
      "services": [
        {
          "name": "media-server",
          "image": "mediaserver:arm64-latest",
          "environment": {
            "ARM_SPECIFIC_VAR": "enabled"
          }
        }
      ]
    },
    {
      "architecture": "amd64",
      "services": [
        {
          "name": "media-server",
          "image": "mediaserver:amd64-latest",
          "deploy": {
            "resources": {
              "reservations": {
                "devices": [
                  {
                    "capabilities": ["gpu"]
                  }
                ]
              }
            }
          }
        }
      ]
    }
  ]
}

In this example:

• The base configuration defines common settings for the media-server service
• On arm64 systems, the service will use the ARM64-specific image and set an ARM-specific environment variable
• On amd64 systems, the service will use the AMD64-specific image and enable GPU acceleration
• The name “media-server” is included in each override to match with the base service

Note: Some of these options are advanced features that should be used with caution as they can affect container security and stability. Always refer to Docker documentation when using advanced options like privileged, capAdd, or securityOpt.

Tip: For most applications, you’ll only need the Basic Configuration and Port Configuration options. The other options are available for more complex use cases.