Uffizzi Compose File Reference

This document describes the Uffizzi Compose file that is used to define and preview multi-container applications on the Uffizzi platform. Based on Docker Compose, a Uffizzi Compose file is a structured YAML format that provides Uffizzi with configuration details needed to preview an application. Uffizzi Compose utilizes the Docker Compose custom extension field (opens in a new tab), x-uffizzi, to specify configuration options used by Uffizzi. This means that all Uffizzi Compose files are valid Docker Compose v3.9 (opens in a new tab) files; however, the reverse is not necessarily true since Uffizzi only supports a subset of the full Docker Compose specification. This document describes all parameters that are supported by Uffizzi Compose and which are required or optional.

Compose file structure

The Uffizzi Compose file is a YAML file defining services (required), configs, secrets, volumes, and x-uffizzi elements such as ingress (required). Other Compose top-level elements networks and version are not currently supported by Uffizzi (Unsupported elements are simply ignored by Uffizzi). As a YAML file, a Uffizzi Compose should comply with the YAML Specification (opens in a new tab). It is recommended to name your Uffizzi Compose file docker-compose.uffizzi.yml (Note: You can use either the .yml or .yaml extension). At a minimum, a Uffizzi Compose file must include services and ingress (a sub-level element of x-uffizzi). Services are the containers that make up your application, and ingress tells Uffizzi which container should receive incoming HTTPS traffic. Ingress requires a service and port number that the service is listening on.

Uffizzi extension

Docker Compose supports vendor-specific extensions (opens in a new tab) for platforms like Uffizzi to supplement the Compose specification with parameters that are specific to that vendor's platform. For example, the Uffizzi extension, x-uffizzi, tells Uffizzi which service should receive incoming HTTP traffic:

x-uffizzi:
  ingress:
    service: web
    port: 8080

The example above is valid Docker Compose syntax because the docker-compose CLI ignores any field prefixed with x-. This allows users to still run docker-compose config on a Uffizzi Compose file to check for valid Docker Compose format.

!!! info

The x- extension prefix works for both top-level and sub-level definitions within a compose file.

Services

As with Docker Compose, a Service is an abstract definition of a computing resource within an application that can be combined with other components. Services are deployed as containers on Uffizzi. A valid services definition is required for a Uffizzi Compose file.

Ingress

Ingress exposes HTTPS routes from outside your preview environment to your application services. Ingress requires a service and port number as parameters. A valid ingress definition is required for a Uffizzi Compose file.

Configs

Configs allow you to add configuration files to your applications. Configs are only supported in Uffizzi CI. If you use a different CI provider, you should use env_file. Config files are expected to be in the same git repository as your compose file. All file paths are relative from the root of the current repository. Configs are optional for Uffizzi Compose files.

Secrets

Secrets provide a mechanism for supplying sensitive environment variables (such as passwords, secret keys, access tokens, etc.) to your application services. The environment variables are defined as name/value pairs and are injected at runtime. Secrets are optional for Uffizzi Compose files.

Volumes

Volumes provide a way to persist data used by containers in a given Uffizzi environment. Volumes will persist for the lifetime of a Uffizzi environment, and they are destroyed when the environment is destroyed. Uffizzi supports both empty volumes and host (i.e. non-empty) volumes. Empty volumes can be either named or anonymous. Host volumes are mounted from a host mount path.

Each volume has a size limit of 1MB compressed. Support for larger volumes is planned. A volume has read+write access by default. This means that two or more containers that mount the same volume can safely write to it. Alternatively, you may specify read-only access.

Example Uffizzi Compose file

This is an example Docker Compose file for Uffizzi CI. If you are using a different CI provider, see our CI guides for building a Docker Compose template.

docker-compose.uffizzi.yml

`x-uffizzi` extension configuration reference

x-uffizzi extension top-level element

This option provides Uffizzi with configuration information required for deploying and managing previews of your application stack.

services:
  foo:
    image: foo:latest
x-uffizzi:
  ingress:
    service: foo
    port: 8080
  continuous_previews: 
    deploy_preview_when_image_tag_is_created: true
    delete_preview_after: 48h
    share_to_github: true

ingress (required)

This section contains example configurations supported by an ingress definition.

service (required)

The service that should receive incoming HTTPS traffic. The ingress service should be one of the services defined within the top-level services.

services:
  foo:
    image: foo:latest
  nginx-loadbalancer:
    image: nginx:latest
x-uffizzi:
  ingress:
    service: nginx-loadbalancer
    port: 8080

port (required)

The port number the ingress service container is listening for traffic on.

services:
  foo:
    image: foo:latest
  nginx-loadbalancer:
    image: nginx:latest
x-uffizzi:
  ingress:
    service: nginx-loadbalancer
    port: 8080

additional_subdomains

By default, Uffizzi generates a unique hostname for each preview environment of the form:

{preview-id}.app.uffizzi.com

If your application requires that a service be exposed at a specific subdomain—for example, auth.{preview-id}.app.uffizzi.com, you can define a list of additional_subdomains, as follows:

x-uffizzi:
  ingress:
    service: app
    port: 80
    additional_subdomains:
      - "auth"
      - "my_landing"

With this configuration, Uffizzi will provision two additional hostnames:

auth.{preview-id}.app.uffizzi.com
my_landing.{preview-id}.app.uffizzi.com

continuous_previews

Continuous Previews (CP) are an automation-enabled best practice that encourages cross-functional teams to continuously collaborate during the development process by providing feedback on features that are still in progress. With CP, git topic branches are previewed using on-demand test environments before they are merged into a downstream branch. Continuous Previews settings are optional for Uffizzi Compose.

When specified, the continuous previews policies are globally scoped, i.e. the policies apply to all services in the compose file. This behavior can be overrided with the service-level x-uffizzi-continuous-previews option).

This section contains example configurations supported by a continuous_previews definition.

deploy_preview_when_pull_request_is_opened

!!! important This option is for Uffizzi CI only. If you are using a different CI provider, see the Getting Started guide for building a Docker Compose template.

Possible values: true, false

Uffizzi will setup webhooks on your git repositories to watch for open pull requests (PR). If a PR is opened, Uffizzi will build the commit and deploy a new preview.

x-uffizzi:
  continuous_previews:
    deploy_preview_when_pull_request_is_opened: true

!!! important This option requires that you have first connected your git repository in the Uffizzi Dashboard.

delete_preview_when_pull_request_is_closed

!!! important This option is for Uffizzi CI only. If you are using a different CI provider, see our CI guides for building a Docker Compose template.

Possible values: true, false

Should be used with deploy_preview_when_pull_request_is_opened.

Uffizzi will setup webhooks on your git repositories to watch for closed pull requests (PR). If a PR is closed, Uffizzi will destroy the preview associated with the corresponding commit.

x-uffizzi:
  continuous_previews:
    deploy_preview_when_pull_request_is_opened: true
    delete_preview_when_pull_request_is_closed: true

!!! important This option requires that you have first connected your git repository in the Uffizzi Dashboard.

deploy_preview_when_image_tag_is_created

!!! important This option is for Uffizzi CI only. If you are using a different CI provider, see the Getting Started guide for building a Docker Compose template.

Possible values: true, false

Uffizzi will deploy a preview each time a new tag is created for one of the images defined in services.

services:
  frontend:
    image: foo:latest
  backend:
    image: bar:latest 
x-uffizzi:
  continuous_previews:
    deploy_preview_when_image_tag_is_created: true

!!! important This option requires that you have first configured webhooks on your container registry.

!!! tip Uffizzi will preview all images tagged with uffizzi_request_# where # is a pull request number. This is useful if you want Uffizzi to only preview images built from pull requests. To enable this behavior, set deploy_preview_when_image_tag_is_created: false, then configure your build system or CI/CD tool to tag images generated from pull requests with the uffizzi_request_# tag.

delete_preview_after

Delete preview after a certain number of hours (optional)

Possible values: 1-720h

x-uffizzi:
  continuous_previews:
    deploy_preview_when_image_tag_is_created: true
    delete_preview_after: 24h

If delete_preview_when_pull_request_is_closed is also specified, Uffizzi will delete the preview based on whichever event (timeout or closed PR) happens first.

share_to_github

Possible values: true, false

After a preview is deployed, post the URL in a comment to the GitHub pull request issue.

x-uffizzi:
  continuous_previews:
    deploy_preview_when_pull_request_is_opened: true
    delete_preview_when_pull_request_is_closed: true
    share_to_github: true

!!! important This option requires that you have first connected your git repository in the Uffizzi Dashboard.

`services` configuration reference

This section contains example configurations supported by a services definition. Note that Uffizzi supports service name resolution, so you can reference any service you declare in any block of your Compose.

build

!!! important
This option is only supported by Uffizzi CI and in the context of a GitHub repository. It is not supported by other CI providers or directly via the uffizzi command-line. For example, Uffizzi will not build your application from a local workstation or remote development or CI server.

Configuration options that are applied at build time. In each example below, the default build context is Dockerfile, unless otherwise specified.

build can be specified either as a string containing a path to the build context:

services:
  webapp:
    build: ./dir

Here the build context is implied to be Dockerfile (i.e. Uffizzi expects that ./dir/Dockerfile exists).

Or, a build can be an object with the path specified with context. The path can be local (i.e., within the same file system or repository as the Uffizzi Compose file):

services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate

Or, the path can reference a remote repository (expects a URL):

services:
  webapp:
    build:
      context: https://github.com/ACCOUNT/example-repo#main
      dockerfile: Dockerfile-alternate

context

Either a path to a directory containing a Dockerfile, or a URL to a GitHub repository.

When the value supplied is a relative path, it is interpreted as relative to the location of the Compose file.

build:
  context: ./dir

The GitHub repository URL must include https://. If no branch is specified, Uffizzi uses the Default Branch as configured on GitHub.

build:
  context: https://github.com/ACCOUNT/example-repo#main

You can tell Uffizzi which branch and build context to use by leveraging the # and : symbols, respectively. For example:

| Build Syntax Suffix                                       | Branch Used   | Build Context Used |
| --------------------------------------------------------- |---------------|--------------------|
| https://github.com/ACCOUNT/example-repo                   | master        | /                  |
| https://github.com/ACCOUNT/example-repo#mybranch          | mybranch      | /                  |
| https://github.com/ACCOUNT/example-repo#:myfolder         | master        | /myfolder          |
| https://github.com/ACCOUNT/example-repo#main:myfolder     | main          | /myfolder          |

dockerfile

Alternate Dockerfile.

Compose uses an alternate file to build with. A build path must also be specified. Default is ./Dockerfile.

build:
  context: ./dir
  dockerfile: Dockerfile-alternate

args

Add build arguments, which are environment variables accessible only during the build process.

First, specify the arguments in your Dockerfile:

# syntax=docker/dockerfile:1
 
ARG buildno
ARG gitcommithash
 
RUN echo "Build number: $buildno"
RUN echo "Based on commit: $gitcommithash"

Then specify the arguments under the build key. You can pass a mapping or a list:

build:
  context: .
  args:
    buildno: 1
    gitcommithash: cdc3b19

build:
  context: .
  args:
    - buildno=1
    - gitcommithash=cdc3b19

!!! note Scope of build-args
In your Dockerfile, if you specify ARG before the FROM instruction, ARG is not available in the build instructions under FROM. If you need an argument to be available in both places, also specify it under the FROM instruction. Refer to the understand how ARGS and FROM interact (opens in a new tab) section in the documentation for usage details.

command

Override the default command.

command: bundle exec thin -p 3000

The command can also be a list, in a manner similar to dockerfile:

command: ["bundle", "exec", "thin", "-p", "3000"]

Command can be used as args for entrypoint and expressed in quotes as a list:

entrypoint: /usr/bin/nginx-debug
command: 
  - "-g"
  - "daemon off;"

configs

Grant access to configs on a per-service basis using the per-service configs configuration. Both Docker configs short syntax and long syntax (opens in a new tab) are supported.

!!! important
configs is only supported in Uffizzi CI. If you use an external CI provider, such as GitHub Actions, GitLab CI, or CircleCI, it is recommended that you pass configuration files using env_file instead. In this example, an environment variable LOKI_CONFIG is stored by your CI provider:

services:
  logging:
    image: mirror.gcr.io/grafana/loki:2.3.0
    env_file: ${LOKI_CONFIG}

Short syntax

The short syntax variant only specifies the config name. This grants the container access to the config and mounts it at / within the container. The source name and destination mountpoint are both set to the config name.

The following example uses the short syntax to grant the redis service access to the my_config resource. The value of my_config is set to the contents of the file ./my_config.txt.

services:
  redis:
    image: redis:latest
    configs:
      - my_config
configs:
  my_config:
    file: ./my_config.txt

Long syntax

The long syntax provides more granularity in how the config is created within the service’s task containers.

source: The identifier of the config as it is defined in this configuration.
target: The path and name of the file to be mounted in the service’s task containers. Defaults to <source> if not specified.

!!! note uid, gid, and mode long syntax parameters are not supported.

services:
  loadbalancer:
      image: nginx:latest
      configs:
        - source: nginx-conf
          target: /etc/nginx/conf.d/override.conf
configs:
  nginx-conf:
    file: ./override.conf
x-uffizzi-ingress:
  service: loadbalancer
  port: 8080

deploy

Specify configuration related to the deployment and running of services.

x-uffizzi-auto-deploy-updates

Possible values: true, false
Default value: true

Auto deploys updates to an existing preview—either a new commit in the git repository or the deployed tag is updated. If this parameter is missing, Uffizzi will auto-deploy updates to repositories or images by default.

services:
  foo:
    build:
      context: github.com/UffizziCloud/foo#main
    deploy:
      x-uffizzi-auto-deploy-updates: false

!!! important
x-uffizzi-auto-deploy-updates is only supported in Uffizzi CI. If you use an external CI provider, such as GitHub Actions, GitLab CI, or CircleCI, deployment updates should be configured by your provider's event triggers. For example, in GitHub Actions this can be defined with push, pull_request and types:

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened,reopened,synchronize,closed]

resources: limits: memory

services:
  myservice:
    image: example.azurecr.io/example-service:latest
    deploy:
      resources:
        limits:
          memory: 500M

memory defaults to 125 megabytes, but you can use the following increments: 125M, 250M, 500M, 1000M, 2000M, 4000M.

entrypoint

Override the default entrypoint.

entrypoint: /code/entrypoint.sh

The entrypoint can also be a list, in a manner similar to dockerfile:

entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]

!!! note Setting entrypoint both overrides any default entrypoint set on the service’s image with the ENTRYPOINT Dockerfile instruction, and clears out any default command on the image - meaning that if there’s a CMD instruction in the Dockerfile, it is ignored.

env_file

Add environment variables from a file. Can be a single value or a list.

env_file: .env

env_file:
- ./common.env
- ./apps/web.env
- /opt/runtime_opts.env

Uffizzi expects each line in an env file to be in NAME=VALUE format.

FOO=bar

environment

Add environment variables as an array. Any boolean values (true, false, yes, no) need to be enclosed in quotes to ensure they are not converted to True or False by the YML parser.

environment:
  FOO: bar
  BAR: 'true'

healthcheck

Healthchecks let Uffizzi know when to restart a container. For example, a healthcheck could catch a deadlock, where an application is running, but unable to make progress. Restarting a container in such a state can help to make the application more available despite bugs.

Available params:

test
interval
timeout
retries
start_period
disable

`test`

Can be string or list of commands. If you use list of commands the first item must be one of: NONE, CMD, CMD-SHELL.

services:
  db:
    image: postgres:last
    healthcheck:
      test: ['CMD-SHELL', 'check']

`start_period`

Number of seconds after the container has started before healthcheck are initiated. Defaults to 0 seconds. Minimum value is 0.

Available formats: s, m, h, d

services:
  db:
    image: postgres:last
    healthcheck:
      test: ['CMD-SHELL', 'check']
      start_period: 5s

`interval`

How often (in seconds) to perform the healthcheck. Default to 10 seconds. Minimum value is 1.

Available formats: s, m, h, d

services:
  db:
    image: postgres:last
    healthcheck:
      test: ['CMD-SHELL', 'check']
      interval: 10s
      start_period: 5s

`timeout`

Number of seconds after which the healthcheck times out. Defaults to 1 second. Minimum value is 1.

Available formats: s, m, h, d

services:
  db:
    image: postgres:last
    healthcheck:
      test: ['CMD-SHELL', 'check']
      interval: 10s
      timeout: 5s
      start_period: 5s

`retries`

When a healthcheck fails, Uffizzi will try retries times before giving up. Giving up means restarting the container. Defaults to 3. Minimum value is 1.

services:
  db:
    image: postgres:last
    healthcheck:
      test: ['CMD-SHELL', 'check']
      interval: 10s
      timeout: 5s
      start_period: 5s
      retries: 5

image

Specify the image to start the container from, as repository:tag. If no tag is specified, default is latest. If no registry is specified, default is hub.docker.com.

services:  
  cache:
    image: redis:latest  # Defaults to hub.docker.com

services:  
  web:
    image: example.azurecr.io/example-service:latest

!!! note
Uffizzi CI supports major cloud registries, as noted below. If you use an external CI provider with Uffizzi, such as GitHub Actions, GitLab CI, CircleCI, etc., you can deploy images from any registry that implements the generic Docker Registry HTTP API V2 (opens in a new tab) protocol, including:

Amazon ECR¹
Azure Container Registry¹
Cloudsmith
Docker Hub¹
GitHub Container Registry¹
Google Container Registry¹
JFrog (Artifactory) Container Registry
Quay

!!! important If you use Uffizzi CI, you must first add your registry credentials in the Uffizzi UI (Settings > Integrations). You do not need to provide Docker Hub credentials to pull public images from hub.docker.com.

secrets

Grant access to secrets on a per-service basis using the per-service secrets configuration. Uffizzi Compose currently supports the secrets short syntax (opens in a new tab) only.

!!! important
secrets are only supported in Uffizzi CI. If you use an external CI provider, such as GitHub Actions, GitLab CI, or CircleCI, it is recommended that you pass secrets using environment instead.

Uffizzi CI

Secrets are name/value pairs that provide a mechanism for securing and sharing environment variables across all services in a stack. The secret name/value pairs must be added in the Uffizzi Dashboard (UI).

In the following example, pg_user and pg_password are references to secrets invoked in the top-level secrets key. POSTGRES_USER and POSTGRES_PASSWORD are the names of secrets that have been added in the Uffizzi Dashboard. Their respective values are injected into the db service container once the stack is deployed.

=== "Uffizzi CI"

services:
  db:
    image: postgres:9.6
    secrets:
      - pg_user
      - pg_password
 
secrets:
  pg_user:
    external: true
    name: "POSTGRES_USER"
  pg_password:
    external: true
    name: "POSTGRES_PASSWORD"

External CI

Secrets should be stored as secrets using your external CI provider's interface abd referenced in your compose file using the environment element with variable substitution. In the following example, PG_USER and PG_PASSWORD are stored using GitHub Actions secrets (opens in a new tab) and referenced using variable substitution in a Docker Compose template.

See the Uffizzi resuable workflow (opens in a new tab) for example usage.

=== "GitHub Actions"

secrets:
  username: ${{ secrets.PG_USER }}
  password: ${{ secrets.PG_PASSWORD }}

=== "Docker Compose Template"

services:
  postgres:
    image: postgres:9.6
    environment:
      POSTGRES_USER: "${PGUSER}"
      POSTGRES_PASSWORD: "${PGPASSWORD}"
    deploy:
      resources:
        limits:
          memory: 500M

volumes

!!! Important

Each volume has a size limit of 1MB compressed. Support for larger volumes is planned (opens in a new tab).

A volume has read+write access by default. This means that two or more containers that mount the same volume can safely write to it. Alternatively, you may specify read-only access using the :ro short sytnax or read-only long syntax, as described in this section.

volumes defines mount host paths or named volumes, specified as sub-options to a service.

If the mount is a host path and only used by a single service, it may be declared as part of the service definition instead of the top-level volumes key.

To reuse a volume across multiple services, a named volume must be declared in the top-level volumes key.

This example shows a named volume (share_db) being used by the web service, and a bind mount defined for a single service

services:
 web:
   image: nginx:alpine
   volumes:
     - share_db:/db
       
volumes:
 share_db:

Uffizzi CI

Requirements for the host volumes (aka non-empty volumes):

As a source, you must use a directory that exists in the repository where your compose file is located.
The path for the source must be relative and start with ./.

External CI

Requirements for the host volumes (aka non-empty volumes):

As a source, you can use a directory or file.
The path for the source must be relative and can start with ./ or ../.
Uffizzi compress source file or directory to archive. And this archive should be less then 1 Mb.

!!! Note

For the host volumes the starting point for relative path is the directory where compose file is located.

Short syntax

The short syntax uses the generic [SOURCE:]TARGET[:MODE] format, where SOURCE can be either a host path or volume name. TARGET is the container path where the volume is mounted. Standard modes are ro for read-only and rw for read-write (default).

volumes:
  # Anonymous volume. Just specify a path and let Uffizzi create a volume
  - /var/lib/mysql
 
  # Anonymous volume with read-only access
  - /var/lib/mysql:ro
    
  # Named volume
  - data_volume:/var/lib/mysql
 
  # Named volume with read-only access
  - shared_db:/var/lib/mysql:ro
 
  # Host volume  
  - ./db/mysql:/var/lib/mysql
 
  # Host volume with read-only access
  - ./db/mysql:/var/lib/mysql:ro

Long syntax

The long form syntax allows the configuration of additional fields that can’t be expressed in the short form.

source: the source of the mount, a path on the host for a bind mount, or the name of a volume defined in the top-level volumes key. Not applicable for a tmpfs mount.
target: the path in the container where the volume is mounted
read_only: flag to set the volume as read-only

services:
  web:
    image: nginx:alpine
    volumes:
        source: mydata
        target: /data
        read-only: true
 
volumes:
  mydata:

!!! Warning

The 'source' and 'target' options are required for the long syntax. Therefore you can't use long syntax with anonymous volumes.

x-uffizzi-continuous-previews

An option for specifying continuous previews policies per service. This option overrides global continuous_previews policies for the service where it is specified.

x-uffizzi:
  ingress:
    service: frontend
    port: 80
  continuous_previews:
    deploy_preview_when_image_tag_is_created: true
    delete_preview_after: 24h
services:
  frontend: 
    image: foo:latest
  backend:
    image: bar:latest
    x-uffizzi-continuous-previews:
      deploy_preview_when_image_tag_is_created: false

In this example, a preview will be triggered when a new tag is created for frontend but not for backend. This is because the continuous previews policies are set to false within the backend service definition, which overrides the global policies. The frontend service definition contains no such override, so continuous previews will still be enabled for frontend.

deploy_preview_when_pull_request_is_opened

!!! important This option is for Uffizzi CI only. If you are using a different CI provider, see our CI guides for building a Docker Compose template.

A service-level option or override

If the global optiondeploy_preview_when_pull_request_is_opened is also specified, this service-level option overrides the global option.

Possible values: true, false

Uffizzi will setup webhooks on your git repositories to watch for open pull requests (PR). If a PR is opened, Uffizzi will build the commit and deploy a new preview.

This parameter can be used as a standalone option:

x-uffizzi:
  ingress:
    service: foo
    port: 80
services:
  foo:
    image: foo:latest
    x-uffizzi-continuous_previews:
      deploy_preview_when_pull_request_is_opened: true
      delete_preview_when_pull_request_is_closed: true

Or as an override:

x-uffizzi:
  ingress:
    service: foo
    port: 80
  continuous-previews:
    deploy_preview_when_pull_request_is_opened: true
    delete_preview_when_pull_request_is_closed : true
services:
  foo:
    build:
      context: https://github.com/example/foo#main
    x-uffizzi-continuous_previews:
      deploy_preview_when_pull_request_is_opened: false
  bar:
    build: 
      context: https://github.com/example/bar#main

In this example, a preview will not be deployed when a pull request is opened on the example/foo repository because deploy_preview_when_pull_request_is_open : false overrides the global setting. However, an open pull request on example/bar repository will still trigger a new preview.

!!! important This option requires that you have first connected your git repository in the Uffizzi Dashboard.

delete_preview_when_pull_request_is_closed

!!! important This option is for Uffizzi CI only. If you are using a different CI provider, see the Getting Started guide for building a Docker Compose template.

A service-level option or override

If the global optiondelete_preview_when_pull_request_is_closed is also specified, this service-level option overrides the global option.

Possible values: true, false

Should be used with deploy_preview_when_pull_request_is_opened.

Uffizzi will setup webhooks on your git repositories to watch for closed pull requests (PR). If a PR is closed, Uffizzi will destroy the preview associated with the corresponding commit.

This parameter can be used as a standalone option:

x-uffizzi:
  ingress:
    service: foo
    port: 80
services:
  foo:
    image: foo:latest
    x-uffizzi-continuous_previews:
      deploy_preview_when_pull_request_is_opened: true
      delete_preview_when_pull_request_is_closed: true

Or as an override:

x-uffizzi:
  ingress:
    service: foo
    port: 80
  continuous-previews:
    deploy_preview_when_pull_request_is_opened: true
    delete_preview_when_pull_request_is_closed : true
services:
  foo:
    build:
      context: https://github.com/example/foo#main
    x-uffizzi-continuous_previews:
      deploy_preview_when_pull_request_is_opened: true
      delete_preview_when_pull_request_is_closed : false
  bar:
    build:
      context: https://github.com/example/bar#main

In this example, foo will not be deleted when the pull request is closed because delete_preview_when_pull_request_is_closed : false overrides the global setting.

!!! important This option requires that you have first connect your git repository in the Uffizzi Dashboard.

deploy_preview_when_image_tag_is_created

!!! important This option is for Uffizzi CI only. If you are using a different CI provider, see our CI guides for building a Docker Compose template.

A service-level option or override

If the global optiondeploy_preview_when_image_tag_is_created is also specified, this service-level option overrides the global option.

Possible values: true, false

Uffizzi will deploy a preview each time a new tag is created for one of the images defined in services.

This parameter can be used as a standalone option:

x-uffizzi:
  ingress:
    service: foo
    port: 80
services:
  foo:
    image: foo:latest
    x-uffizzi-continuous_previews:
      deploy_preview_when_image_tag_is_created: true

Or as an override:

x-uffizzi:
  ingress:
    service: foo
    port: 80
  continuous-previews:
    deploy_preview_when_image_tag_is_created: false
services:
  foo:
    image: foo:latest
    x-uffizzi-continuous_previews:
      deploy_preview_when_image_tag_is_created: true
  bar:
    image: bar:latest
  baz:
    image: baz:latest

In this example, previews are disabled for all services except foo because the override is specified for this service.

!!! important This option requires that you have first configured webhooks on your container registry.

delete_preview_after

A service-level option or override

If the global optiondelete_preview_after is also specified, this service-level option overrides the global option.

Delete preview after a certain number of hours (optional)

Possible values: 1-720h

This parameter can be used as a standalone option:

x-uffizzi:
  ingress:
    service: foo
    port: 80
services:
  foo:
    image: foo:latest
    x-uffizzi-continuous_previews:
      deploy_preview_when_image_tag_is_created: true
      delete_preview_after: 24h

Or as an override:

x-uffizzi:
  ingress:
    service: foo
    port: 80
  continuous-previews:
    deploy_preview_when_image_is_created: true
    delete_preview_after: 1h
services:
  foo:
    image: foo:latest
    x-uffizzi-continuous_previews:
      delete_preview_after: 24h
  bar:
    image: bar:latest

In this example, foo wil be deleted after 24 hours, instead of 1 hour.

share_to_github

A service-level option or override

If the global optionshare_to_github is also specified, this service-level option overrides the global option.

Possible values: true, false

After a preview is deployed, post the URL in a comment to the GitHub pull request issue.

This parameter can be used as a standalone option:

Or as an override:

x-uffizzi:
  ingress:
    service: foo
    port: 80
  continuous_previews:
    deploy_preview_when_pull_request_is_opened: true
    delete_preview_when_pull_request_is_closed: true
    share_to_github: false
services:
  foo:
    build: 
      context: https://github.com/example/foo#main
    x-uffizzi-continuous_previews:
      share_to_github: true
  bar:
    image: bar:latest

In this example, the preview URL will only be shared to GitHub when a pull request is opened on repository foo (but not bar).

!!! important This option requires that you have first connected your GitHub account in the Uffizzi Dashboard.

`configs` configuration reference

The top-level configs declaration defines configs that can be granted to the services in this stack. The source of the config is a file (external source is currently not supported).

services:
  logging:
    image: mirror.gcr.io/grafana/loki:2.3.0
    env_file: ${LOKI_CONFIG}

=== "External CI"

services:
  hello-world:
    build:
      context: https://github.com/ACCOUNT/hello-world:main
    env_file: ${FOO_BACKING_SERVICE}
 
ingress:
  service: hello-world
  port: 80

=== "Uffizzi CI"

services:
  hello-world:
    build:
      context: https://github.com/ACCOUNT/hello-world:main
 
  redis:
    image: redis:latest
    configs:
      - my_config
 
configs:
  my_config:
    file: ./my_config.txt
 
ingress:
  service: hello-world
  port: 80

`secrets` configuration reference

A top-level reference to secrets that can be granted to the services in a stack.

!!! important
Top-level secrets is only supported in Uffizzi CI. If you use an external CI provider, such as GitHub Actions, GitLab CI, or CircleCI, it is recommended that you pass secrets using environment instead.

Uffizzi CI

Secrets are name/value pairs that provide a mechanism for securing and sharing environment variables across all services defined in the compose file. The source of the secret must be added in the Uffizzi Dashboard and invoked with external and secret name. If the external secret does not exist, you will see a secret-not-found error message in the Uffizzi Dashboard.

external: Indicates that the secret object (a name/value pair) is declared in the Uffizzi Dashboard (UI). Value must be true.
name: The name of the secret object in Uffizzi.

In the following example, POSTGRES_USER and POSTGRES_PASSWORD are the names of secrets that have been added in the Uffizzi Dashboard. Their respective values are available to the db service once the stack is deployed.

=== "Uffizzi CI"

services:
  db:
    image: postgres:9.6
    secrets:
      - pg_user
      - pg_password
 
secrets:
  pg_user:
    external: true
    name: "POSTGRES_USER"
  pg_password:
    external: true
    name: "POSTGRES_PASSWORD"

External CI

Secrets should be stored as secrets using your external CI provider's interface and referenced in your compose file using the environment element with variable substitution. In the following example, PG_USER and PG_PASSWORD are stored using GitHub Actions secrets (opens in a new tab) and referenced using variable substitution in a Docker Compose template.

See the Uffizzi resuable workflow (opens in a new tab) for example usage.

=== "GitHub Actions"

secrets:
  username: ${{ secrets.PG_USER }}
  password: ${{ secrets.PG_PASSWORD }}

=== "Docker Compose Template"

services:
  postgres:
    image: postgres:9.6
    environment:
      POSTGRES_USER: "${PGUSER}"
      POSTGRES_PASSWORD: "${PGPASSWORD}"
    deploy:
      resources:
        limits:
          memory: 500M

`volumes` configuration reference

!!! Important

Each volume has a size limit of 1MB compressed. Support for larger volumes is planned (opens in a new tab).

While it is possible to declare volumes on the fly as part of the service declaration, this section allows you to create named volumes that can be reused across multiple services.

Here’s an example of a two-service setup where a database’s data directory is shared with another service as a volume so that it can be periodically backed up:

services:
  db:
    image: db
    volumes:
      - ./some_init_db_data:/var/lib/db_init
      - /some_data:/var/lib/some_data
      - data-volume:/var/lib/db
 
  backup:
    image: backup-service
    volumes:
      - data-volume:/var/lib/backup/data
 
volumes:
  data-volume:

Supported by Uffizzi CI ↩ ↩² ↩³ ↩⁴ ↩⁵

Uffizzi Compose Secrets

Uffizzi Compose File Reference

Compose file structure

Uffizzi extension

Services

Ingress

Configs

Secrets

Volumes

Example Uffizzi Compose file

x-uffizzi extension configuration reference

ingress (required)

service (required)

port (required)

additional_subdomains

continuous_previews

deploy_preview_when_pull_request_is_opened

delete_preview_when_pull_request_is_closed

deploy_preview_when_image_tag_is_created

delete_preview_after

share_to_github

services configuration reference

build

context

dockerfile

args

command

configs

Short syntax

Long syntax

deploy

x-uffizzi-auto-deploy-updates

resources: limits: memory

entrypoint

env_file

environment

healthcheck

test

start_period

interval

timeout

retries

image

secrets

Uffizzi CI

External CI

volumes

Uffizzi CI

External CI

Short syntax

Long syntax

x-uffizzi-continuous-previews

deploy_preview_when_pull_request_is_opened

delete_preview_when_pull_request_is_closed

deploy_preview_when_image_tag_is_created

delete_preview_after

share_to_github

configs configuration reference

secrets configuration reference

Uffizzi CI

External CI

volumes configuration reference

Footnotes

`x-uffizzi` extension configuration reference

`services` configuration reference

`test`

`start_period`

`interval`

`timeout`

`retries`

`configs` configuration reference

`secrets` configuration reference

`volumes` configuration reference