Skip to Content
DocumentationReferenceDynamic compose

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.

Docker Compose YAML

Dynamic Compose Output

⚠️

The converter works for most cases, but please review the converted configuration to ensure it meets your needs. Some advanced features may not be fully supported.

Configuration Options Reference

Basic Configuration

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

OptionTypeDescriptionExample
namestringThe name of the service and container"name": "nginx"
imagestringThe Docker image to use"image": "nginx:latest"
commandstring | string[]The command to run in the container"command": "/my/app" or "command": ["npm", "start"]
environmentobjectEnvironment variables"environment": {"FOO": "bar"}
restartstringContainer restart policy"restart": "always"

Port Configuration

Options related to exposing ports:

OptionTypeDescriptionExample
internalPortnumberThe main port exposed by the container"internalPort": 80
addPortsarrayAdditional ports to exposeSee example below

Example addPorts configuration:

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

Volume Configuration

Options for mounting volumes:

OptionTypeDescriptionExample
volumesarrayList of volume mappingsSee example below

Example volumes configuration:

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

Network Configuration

Options related to networking:

OptionTypeDescriptionExample
networkModestringCustom network mode"networkMode": "host"
extraHostsstring[]Additional /etc/hosts entries"extraHosts": ["host1:ip1"]
hostnamestringContainer hostname"hostname": "mycontainer"

Health Check Configuration

Options for container health monitoring:

OptionTypeDescriptionExample
healthCheckobjectContainer health check configurationSee example below

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:

OptionTypeDescriptionExample
deployobjectResource limits and reservationsSee example below
ulimitsobjectResource limitsSee example below
shmSizestringSize of /dev/shm"shmSize": "2gb"

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:

OptionTypeDescriptionExample
privilegedbooleanRun container with elevated privileges"privileged": true
capAddstring[]Add container capabilities"capAdd": ["NET_ADMIN"]
capDropstring[]Drop container capabilities"capDrop": ["NET_ADMIN"]
securityOptstring[]Security options"securityOpt": ["no-new-privileges"]
readOnlybooleanMount root filesystem as read only"readOnly": true
userstringUsername or UID"user": "1000:1000"

Advanced Configuration

Additional options for fine-tuning:

OptionTypeDescriptionExample
entrypointstring | string[]Container entrypoint"entrypoint": "./entrypoint.sh"
workingDirstringWorking directory inside container"workingDir": "/app"
ttybooleanAllocate a pseudo-TTY"tty": true
stdinOpenbooleanKeep STDIN open"stdinOpen": true
stopSignalstringSignal to stop the container"stopSignal": "SIGTERM"
stopGracePeriodstringTime to wait to stop container"stopGracePeriod": "10s"
pidstringPID namespace"pid": "host"
sysctlsobjectSysctl settings"sysctls": {"net.core.somaxconn": 1024}
loggingobjectLogging configurationSee example below
devicesstring[]Device mappings"devices": ["/dev/ttyUSB0:/dev/ttyUSB0"]

Example logging configuration:

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

Dependencies

Options for managing service dependencies:

OptionTypeDescriptionExample
dependsOnobject | stringService dependenciesSee example below
isMainbooleanIndicates where traefik labels should be applied"isMain": true

Example dependsOn configuration:

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

Architecture Overrides

Options for architecture-specific configurations:

OptionTypeDescriptionExample
overridesarrayArchitecture-specific service configurationsSee example below

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.

Last updated on