Skip to content

Stack Template

You can create custom stacks by defining one via template or by forking stacks provided by Wodby.

Stack template is a YML defining services, it's basically a simplified and limited version of kubernetes schema in a format very close to docker compose.

Managed stacks are more functional

Stacks provided by Wodby (including forks) may have additional configurations not covered by templates.

Service Configuration Reference

This section contains a list of all configuration options supported by a service definition.

Name Description Mandatory Schema
image The image the container is running. string
image_pull Always - always pull the image; IfNotPresent - only pull the image if it does not already exist on the server. string
entrypoint Entrypoint string or array. The docker image’s ENTRYPOINT is used if this is not provided. string, string array
command Arguments to the entrypoint. The docker image’s CMD is used if this is not provided. string, string array
working_dir Container’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. string
environment List of environment variables to set in the container. string array
volumes Volumes to mount into the container’s filesystem. string array
memory Memory rules and limitations int, string
cpu CPU resources rules and limitations int, string
ports List of ports to expose from the container. string array
check_ready Describes a health check to be performed against a container to determine whether it is alive or ready to receive traffic. string array
deployment Deployment enables declarative updates for services. string array
security_context Security context holds security configuration that will be applied to a container. string array

memory

You can specify memory limits and requests for a container in the following formats:

128 - Request 128Mb of memory.
512:1024 - Request 512Mb of memory. Limit 1Gb of memory.

Limit is a maximum memory (in megabytes) available for a container. When a container exceeds this limit, it will be terminated (and automatically started again). Request defines how much memory must be available on a server to start this container (used in clusters).

cpu

You can specify CPU limits and requests for a container in the following formats:

1000 - Request 1 Core.
1500 - Request 1.5 Core.
650 - Request 0.65 Core.
200:250 - Request 0.2 Core. Limit 0.25 Core.
Minimum value is 100.

Limit is a # of CPU cores (1000 for 1 core) available for a container. When a container exceeds this limit, it will be terminated (and automatically started again). Request defines how many CPU cores must be available on a server to start this container (used in clusters).

ports

Expose ports for a container in the format [PUBLIC_PORT::BUNDLE_PORT:CONTAINER_PORT].

Examples:

  • Map container's port 8080 to 80 for other containers within a stack.

    services:
        backend:
            image: example/backend
            ports:
                - "80:8080"
    

  • Same as "8080:8080"

    "8080"
    

  • Map 8080 to a public port within the range 31222-32222.

    "auto::8080"
    

  • Map 8080 to a public port 80, edge is a reverse proxy handling 80 and 443 ports. A technical domain *.wodby.cloud will be generated for the first public port exposed via edge.

    "edge::8080"
    

  • Map 8080 to a public 32223.

    "32223::8080"
    

  • Map 8080 to 80 both public and within a stack.

    "edge::80:8080"
    

  • Map 8080 to 80 within a stack, assign public port automatically.

    "auto::80:8080"
    

  • Map 8080 to 80 within a stack, assign a specific public port from range 31222-32222

    "32223::80:8080"
    

check-ready

Name Description Mandatory Schema
exec Exec specifies the action to take. command - array of strings
initial_delay_seconds Number of seconds after the container has started before liveness probes are initiated. int
period_seconds How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1. int
failure_threshold Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1. int
success_threshold Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Minimum value is 1. int
timeout_seconds Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. int

deployment

Name Description Mandatory Schema
strategy rolling_update or recreate (rolling_update by default). Always use recreate strategy for stateful services like database and search engines. string
replicas Number of desired containers. This is a pointer to distinguish between explicit zero and not specified. Defaults to 1. int
min_ready_seconds Minimum number of seconds for which a newly created service should be ready without any of its container crashing, for it to be considered available. Defaults to 0. int
progress_deadline_seconds The maximum time in seconds for a deployment to make progress before it is considered to be failed, not set by default. int
max_surge The maximum number of containers that can be scheduled above the desired number of containers. Value must be an absolute number. Defaults to 1. int
max_unavailable The maximum number of containers that can be unavailable during the update. Value must be an absolute number. Defaults to 1. int
type If set to CI the service will be used for CI deployments. CI services excluded from the initial deployment (replicas set to 0) until you deploy your first build to avoid deployment failures. string

security_context

Name Description Mandatory Schema
privileged Run container in privileged mode. Processes in privileged containers are essentially equivalent to root on the host. boolean
capabilities The capabilities to add/drop when running containers. Defaults to the default set of capabilities granted by the container runtime. array of strings
read_only_root_filesystem Whether this container has a read-only root filesystem. Default is false. string
run_as_non_root Indicates that the container must run as a non-root user. If true, the Kubelet will validate the image at runtime to ensure that it does not run as UID 0 (root) and fail to start the container if it does. If unset or false, no such validation will be performed. string
run_as_user The UID to run the entrypoint of the container process. Defaults to user specified in image metadata if unspecified. int

Global Volumes

You can define global volumes and use them in services under volumes. We recommend using ./ as a host path to mount volumes which is an equals /srv/wodby/instances/<Instance UUID>.

Example:

services:
    myapp:
        image: example/myapp
        ports:
            - 'edge::80/tcp'
        volumes:
            - 'docroot:/var/www'
            - 'db:/var/www'
volumes:
    docroot:
        path: ./docroot
    db:
        path: ./db

Variable Substitution

You can define variables and substitute them in services under environment.

Example:

services:
    backend:
        image: example/backend
        ports:
            - 'edge::80/tcp'
        environment:
            username: '%user'
            password: '%pass'

variables:
    user: 'admin'
    pass: 'auto:password:64'

Examples

services:
    db:
        image: mysql
        environment:
            MYSQL_ROOT_PASSWORD: '%db_password'
        volumes:
            - './mysql:/var/lib/mysql'
        deployment:
            strategy: recreate            
    php:
        image: php
        environment:
            DB_USER: root
            DB_PASSWORD: '%db_password'
        memory: '512:1024'
        cpu: '900'
        deployment:
            type: ci      
        security_context: 
            capabilities:
                add:    
                    - SYS_PTRACE
                drop:
                    - SYS_ADMIN
    nginx:
        image: nginx
        ports:
            - "edge::80:80"
variables:
    db_password: 'auto:password:64'

Permissions

If you mount volumes from the server, the owner of the mounted directory in a container will be root (UID 0). This may cause issues because very often main process run from a different user. To avoid potential problems make sure you're either fixing volumes permissions in your container entrypoint script (recommended) or run the main process as root.