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:
Option | Type | Description | Example |
---|---|---|---|
name | string | The name of the service and container | "name": "nginx" |
image | string | The Docker image to use | "image": "nginx:latest" |
command | string | string[] | The command to run in the container | "command": "/my/app" or "command": ["npm", "start"] |
environment | object | Environment variables | "environment": {"FOO": "bar"} |
restart | string | Container restart policy | "restart": "always" |
Port Configuration
Options related to exposing ports:
Option | Type | Description | Example |
---|---|---|---|
internalPort | number | The main port exposed by the container | "internalPort": 80 |
addPorts | array | Additional ports to expose | See 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:
Option | Type | Description | Example |
---|---|---|---|
volumes | array | List of volume mappings | See example below |
Example volumes
configuration:
"volumes": [{
"hostPath": "/host/path",
"containerPath": "/container/path",
"readOnly": false,
"shared": false,
"private": false
}]
Network Configuration
Options related to networking:
Option | Type | Description | Example |
---|---|---|---|
networkMode | string | Custom network mode | "networkMode": "host" |
extraHosts | string[] | Additional /etc/hosts entries | "extraHosts": ["host1:ip1"] |
hostname | string | Container hostname | "hostname": "mycontainer" |
Health Check Configuration
Options for container health monitoring:
Option | Type | Description | Example |
---|---|---|---|
healthCheck | object | Container health check configuration | See 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:
Option | Type | Description | Example |
---|---|---|---|
deploy | object | Resource limits and reservations | See example below |
ulimits | object | Resource limits | See example below |
shmSize | string | Size 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:
Option | Type | Description | Example |
---|---|---|---|
privileged | boolean | Run container with elevated privileges | "privileged": true |
capAdd | string[] | Add container capabilities | "capAdd": ["NET_ADMIN"] |
capDrop | string[] | Drop container capabilities | "capDrop": ["NET_ADMIN"] |
securityOpt | string[] | Security options | "securityOpt": ["no-new-privileges"] |
readOnly | boolean | Mount root filesystem as read only | "readOnly": true |
user | string | Username or UID | "user": "1000:1000" |
Advanced Configuration
Additional options for fine-tuning:
Option | Type | Description | Example |
---|---|---|---|
entrypoint | string | string[] | Container entrypoint | "entrypoint": "./entrypoint.sh" |
workingDir | string | Working directory inside container | "workingDir": "/app" |
tty | boolean | Allocate a pseudo-TTY | "tty": true |
stdinOpen | boolean | Keep STDIN open | "stdinOpen": true |
stopSignal | string | Signal to stop the container | "stopSignal": "SIGTERM" |
stopGracePeriod | string | Time to wait to stop container | "stopGracePeriod": "10s" |
pid | string | PID namespace | "pid": "host" |
sysctls | object | Sysctl settings | "sysctls": {"net.core.somaxconn": 1024} |
logging | object | Logging configuration | See example below |
devices | string[] | Device mappings | "devices": ["/dev/ttyUSB0:/dev/ttyUSB0"] |
Example logging
configuration:
"logging": {
"driver": "json-file",
"options": {
"max-size": "10m"
}
}
Dependencies
Options for managing service dependencies:
Option | Type | Description | Example |
---|---|---|---|
dependsOn | object | string | Service dependencies | See example below |
isMain | boolean | Indicates where traefik labels should be applied | "isMain": true |
Example dependsOn
configuration:
"dependsOn": {
"db": {
"condition": "service_healthy"
}
}
Architecture Overrides
Options for architecture-specific configurations:
Option | Type | Description | Example |
---|---|---|---|
overrides | array | Architecture-specific service configurations | See 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
, orsecurityOpt
.
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.