The .yml file

You may define a .squash.yml at the root level of your repository. This file provides greater flexibility to control the build and execution of each deployment.

Squash works out of the box without the need of a .squash.yml file. In this case Squash searches for a Dockerfile or docker-compose.yml file within the root path of your application code.

The .squash.yml structure

The .squash.yml file is organized by deployments, each deployment represents a unique Dockerfile or docker-compose file:

deployments:
  AppName1:
        filename:
          ./src/DockerfileABC
  AppName2:
        filename:
          ./src/DockerfileXYZ

For the examples above, AppName1 and AppName2 are mandatory and are meant to be customized, they define a user friendly name for each Dockerfile/docker-compose file.

Settings within the .yml file are always specific to a given Dockerfile or docker-compose file.

Here is a typical .squash.yml file:

deployments:
  MyAppName:
        filename:
          ./myapp/Dockerfile
        context_path:
          ./myapp/docker
        environment:
          TEST_VAL=42
        ready_wait:
          120
        pre_launch:
          - target: 'myapp-service'
                command: cp
                docker: true
                options: './myapp {target}:/'
        post_launch:
          - target: 'myapp-service'
                command: exec
                docker: true
                options: '-it {target} echo hello world'
          - target: 'myapp-service'
                command: run
                docker: false
                options: '{target} echo TEST_VAL is $TEST_VAL'
          - target: 'myapp-service'
                command: exec
                options: '{target} echo domain is $SQUASH_DOMAIN'
        domain:
          example.com
        subdomains:
          Customer Subdomains:
                 - customer-abc
                 - customer-xyz
        dockerimage:
          myappcustom-img
        port_forwarding:
          8000:80
        build_options:
          --no-cache
        run_options: -v /assets/data:/usr/src/app/data

Supported .yml fields

always_build_images

  • This will turn off the Docker Image Cache for this deployment and always build the Docker image from scratch.
  • Mandatory field: No
  • Data Type: Boolean
  • Choices: True/False
  • Default value: False

assets_user_id

  • When the Assets Storage is enabled for a repository Squash automatically mounts a new folder under /assets/ for each deployment. By default the folder is mounted for the Linux user id 1000.
  • Mandatory field: No
  • Data Type: Integer
  • Choices: numeric choice equal or above 1000
  • Default value: 1000

backend_wait

  • Defines the waiting period (in seconds) after receiving an HTTP response from a successful deployment before the routing to the VM’s application is established. This is helpful for some containers where the application’s backend might need more time to startup after the web server has already started.
  • Mandatory field: No
  • Data Type: Integer
  • Default value: 0

build_options

  • Additional options that will be added to either the docker build or docker-compose build commands.
  • Mandatory field: No
  • Data Type: String
  • Default value: null

context_path

  • Used for Dockerfile deployments only. Defines the context path option, by default value is ‘.’.
  • Mandatory field: No
  • Data Type: String
  • Default value: ‘.’

copy_files

  • Defines files that should be copied, specified in <source> <destination> format.
  • Mandatory field: No
  • Data Type: String
  • Default value: null

copy_files_build_process

  • Defines files that should be copied only before build process, specified in <source> <destination> format. This step is skipped when Docker Image Cache or Persistent Storage snapshot is available.
  • Mandatory field: No
  • Data Type: String
  • Default value: null

default_pr_comment

  • Display the default GitHub Pull Request comment for a given deployment
  • Mandatory field: No
  • Data Type: Boolean
  • Default value: True

The default PR comment looks like this and it’s included by default for every Dockerfile/docker-compose file:

../_images/default-pr-comment.png

dockerfileonly

  • Forces to ignore any available docker-compose files and use a Dockerfile instead. By default, this option is defined automatically.
  • Mandatory field: No
  • Data Type: Boolean
  • Default value: True

dockerimage

  • Used for Dockerfile deployments only. Defines a docker image that should be used for the docker run command instead of building an image from Dockerfile. This image needs to be available in the public docker registry.
  • Mandatory field: No
  • Data Type: String
  • Default value: null

domain

  • A custom domain such as example.com. Please note that you need to contact our support in order to enable custom domains in your account.
  • Mandatory field: No
  • Data Type: String
  • Default value: null

.squash.yml sample:

deployments:
  MyAppName:
        filename:
          ./myapp/Dockerfile
        domain:
          example.com

environment

  • List of environment variables for Docker containers.
  • Mandatory field: No
  • Data Type: List of key: value pairs
  • Default value: null

Example:

deployments:
  MyAppName:
        filename:
          ./myapp/Dockerfile
        environment:
          TEST_VAL=42
          CLIENT_API_ID=7612

filename

  • This is the full path of a Dockerfile name or docker-compose.yml file
  • Mandatory field: No
  • Data Type: String
  • Default value: null

port_forwarding

  • Used for Dockerfile deployments only. Defines the port forwarding option. The first value refers to the port on the host deployment VM that communicates with Squash, the second value refers to the port number within the docker container itself. host_port_number:docker_container_port_number
  • Mandatory field: No
  • Data Type: String
  • Default value: 80:80

post_launch / pre_launch

  • post_launch and pre_launch will define a list of additional commands to be executed before or after the deployment’s launch.
    • target: name of the target container, required option
    • command docker/docker-compose command, required option
    • options command itself, {target} will be replaced with an accurate container name or id, required option
    • docker optional, Squash will use the docker command instead

pre_terminate

Use pre_terminate to define one or more commands that need to run right before a docker container is stopped. These commands will be executed within the container itself. This works when Squash automatically shuts down a deployment when the expire time is reached and during manual stop/restart actions.

Commands defined in pre_terminate will be executed in the exact order as defined in the .yml file. You may also define commands that only apply to specific containers (see example below).

  • Mandatory field: No
  • Data Type: List of scripts to run within the docker container
  • Default value: null

Example:

deployments:
  MyAppName:
        filename:
          ./myapp/Dockerfile
        pre_terminate:
          - ./src/scripts/script-1.sh
          - ./src/scripts/script-2.py

You may also specify commands that will only run for certain containers. In this case use the container name to group the scripts you want to run. Example:

pre_terminate:
  - container-nameABC:
      - ./src/scripts/script-1.sh
      - ./src/scripts/script-2.sh
  - container-nameXYZ:
      - ./src/scripts/script-3.sh

ready_wait

  • Defines the maximum waiting period (in seconds) for a successful deployment before routing to the VM’s application is established.
  • Mandatory field: No
  • Data Type: Integer
  • Default value: 180

run_options

  • Additional options that will be added to either the docker run or docker-compose up commands. Usage of “-d” or “-p” options IS NOT recommended as it will break the standard Squash’s log output and potentially make the deployments unstable.
  • Mandatory field: No
  • Data Type: String
  • Default value: null

subdomains

This is where you can list multiple pre-defined subdomains to appear in Pull Request (PR) Comments. Note that this only affects the display on PR comments, you can still use any subdomains with any deployments by manually adding a double dash (--) in a deployment URL.

See details on how to use subdomains with Squash.

Example yml file:

deployments:
  AppName1:
        filename:
          ./src/module1/DockerfileABC
        default_pr_comment:
          False
        subdomains:
          Customers:
                 - drugstore
                 - bookstore

PR comment output:

../_images/pr-comment-subdomains.png

You may also specify pre-made URL paths and arguments that will be used by default in the PR URLs. For example, if you want some deployment links to use the path /login/ you can do so by adding a comma after the subdomain name and adding the desired URL path afterwards. This is how it looks like in the .squash.yml file:

subdomains:
  Customers:
         - bookstore,/login/
         - drugstore,/login/?uid=1234

And Squash will display the automatic PR comment as follows:

https://bookstore--cartv2-zh1cw.squash.io/login/

and

https://drugstore--cartv2-zh1cw.squash.io/login/?uid=1234

  • Mandatory field: No
  • Data Type: List of subdomains in text format
  • Default value: null

subdomain_port_mapping

  • Use this option to assign a subdomain to an specific port associated to a docker container/service. This is useful when you are deploying micro services using docker-compose, with multiple containers within the same deployment.
  • Format for this field: <subdomain>:<port>.
  • Only one port mapping per subdomain is allowed.
  • Mandatory field: No
  • Data Type: List of strings
  • Default value: null

Example:

deployments:
  MyAppName:
    filename:
      ./myapp/docker-compose.yml
    subdomain_port_mapping:
      - api:8080

vm_size

This is the VM size to use for a given deployment. By default Squash will use the repository VM Size as defined in Settings -> Repositories.

You may override this on a per branch basis by using the vm_size option in the .squash.yml file.

Available choices:

  • 1GB
  • 2GB
  • 4GB
  • 8GB
  • 16GB

See our pricing page for more information on the specs of each VM.

  • Mandatory field: No
  • Data Type: List of VM sizes in text format
  • Default value: null

wait_post_launch

By default Squash will run the commands defined in post-launch after the docker build process is done and at the beginning of the docker run command, without waiting for a successful HTTP response. When wait_post_launch is set to True, Squash will only run the post-launch command after it receives a successful HTTP response from the docker container.

  • Mandatory field: No
  • Data Type: Boolean
  • Default value: False