Global YAML fields

Back to the Squash YAML file page.

The YAML fields below are supported on any application type (Docker or non-Docker based).

allow_public_ports

This will open in the firewall one or more ports for external access. Squash by default restricts external access to all ports running on deployment VMs except the SSH port and ports used by the actual deployment endpoints (443).

  • Mandatory field: No
  • Data Type: List of integers
  • Default value: None

Example:

deployments:
  CRM:
    filename:
      ./src/Dockerfile
    allow_public_ports: 5050,8080

allow_private_ports

This will open in the firewall one or more ports for internal access only. Ports defined in this field will be open for private IP addresses and within the Squash’s proxy servers only.

  • Mandatory field: No
  • Data Type: List of integers
  • Default value: None

Example:

deployments:
  CRM:
    filename:
      ./src/Dockerfile
    allow_private_ports: 5030,8060

auto_deploy_on_commits

This will enable the Automatic Checks feature.

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

auto_deploy_path

This is used together with the Automatic Checks feature. Use this field to change the default URL path displayed on each check. This is the actual URL Squash will use to check for a success response. For example, you might want Squash to check for a success response within an specific subdomain or URL path like “/app/?pid=1223”.

  • Mandatory field: No
  • Data Type: String
  • Default value: null

Example YAML file. For this example we are using a subdomain named “calendar” and a URL path “/search”. Squash will check for a success response on a URL such as https://calendar--67e35f0-ablql1r.squash.io/search

deployments:
  CRM:
    filename:
      ./src/docker-compose.yml
    context_path:
      ./src
    vm_size:
      2GB
    auto_deploy_on_commits:
      true
    auto_deploy_path:
      calendar,/search

On this second example Squash will look for a success response on a URL such as (note that we are not using a subdomain this time): https://67e35f0-ablql1r.squash.io/?que=99764QQ

deployments:
  CRM:
    filename:
      ./src/docker-compose.yml
    context_path:
      ./src
    vm_size:
      2GB
    auto_deploy_on_commits:
      true
    auto_deploy_path:
      /?que=99764QQ

auto_deploy_ttl

This is used together with the Automatic Checks feature.

This field controls the default time to live of each automatic check. With the default value (None) Squash will automatically decommission the deployment once it receives a success response. We recommend using the default settings in order to efficiently use the concurrency and resources in your account.

  • Mandatory field: No
  • Data Type: String
  • Default value: None

Available choices:

  • repo_settings: Squash will use the same default settings as defined in the repository settings page (Squash dashboard: Settings -> Repository)
  • 30m
  • 1h
  • 2h
  • 3h
  • 4h
  • 5h
  • 6h

auto_deploy_disable_cache

This is used together with the Automatic Checks feature.

This will turn off the Deployment Cache feature for all checks. This is helpful if you need to ensure all these builds are completely build from scratch. Checks may take longer to complete when this field is set to “true”.

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

auto_deploy_post_launch_commands

This is used together with the Automatic Checks feature.

Defines a list of commands to run right after a Squash deployment is commissioned. Each command can be executed for specific containers or on a global fashion affecting all containers.

You can use one of the multiple default Squash environment variables to grab the URL/endpoint of the current application running within this check. For instance, your tests might read from the environment variable “SQUASH_DOMAIN”, which will give you an end point such as “cartv3-i3xg7.squash.io”.

The overall format is:

auto_deploy_post_launch_commands:
  command name ABC:
     container-name123:
        - ./src/scripts/script-1.sh
     container-name987:
        - ./src/scripts/script-2.sh
  command name XYZ:
    - ./src/scripts/script-3.sh
    - ./src/scripts/script-4.sh

where “command name ABC” and “command name XYZ” are just labels used for logging purposes.

  • Mandatory field: No
  • Data Type: Dict with a list of commands
  • Default value: None

Example without container specific commands, these commands will run on all containers:

deployments:
  CRM:
    filename:
      ./src/docker-compose.yml
    auto_deploy_on_commits: true
    auto_deploy_post_launch_commands:
      Selenium tests:
        - echo true
        - python ./selenium_test.py

Container specific commands:

deployments:
  CRM:
    filename:
      ./src/docker-compose.yml
    auto_deploy_on_commits: true
    auto_deploy_post_launch_commands:
      My custom label:
        app_container:
          - /usr/src/app/node_modules/.bin/cypress run
        api_container:
          - python ./selenium_test.py

auto_deploy_command_success_codes

This is used together with the Automatic Checks feature.

Accepts an additional list of success codes. Squash by default will always accept “0” (zero) as the default success code. This list allows you to add custom success codes for specific scripts.

  • Mandatory field: No
  • Data Type: List of integers, comma separated
  • Default value: None

Example:

deployments:
  CRM:
    filename:
      ./src/CRM/docker-compose.yml
    context_path:
      ./src
    auto_deploy_on_commits: true
    auto_deploy_command_success_codes: 3
    auto_deploy_post_launch_commands:
      cypress cmd:
        default:
          - /usr/src/app/node_modules/.bin/cypress run

auto_shutdown_by_merge

Squash YAML file sample:

deployments:
  MyAppName:
  filename:
    ./myapp/Dockerfile
  auto_shutdown_by_merge:
      enabled: true
      base_branch: master

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_policy

  • This field works with the Automated Checks feature and allows controlling when the automated checks should run. By default the checks will run for all branches and will be triggered by pushing new commits or by creating a new Pull Request (GitHub/Bitbucket/GitLab).
  • Mandatory field: No
  • Data Type: dict
  • Default value: null

Options available for this field:

  • triggers: accepts either “pr”, “commit” or both options, comma separated.
    • pr: this will trigger a new check execution when a new Pull Request is created (GitHub/Bitbucket/GitLab).
      • You may also restrict the destination branch of the Pull Request as follows:
        • pr[master]
        • For this example above the Automated check will only run when the destination branch of the PR is branch “master”
      • You may also use multiple branches separated by semicolon (;):
        • pr[branchA;branchB;branchC]
    • commit: starts a new check by pushing a new commit to a branch.
    • Default value: pr, commit
  • restrict_branches: comma separated list of branches that will not trigger automated checks.
    • Default value: null
    • No branches are restricted by default.
  • allow_branches: comma separated list of branches that will accept the automated checks. The asterisk (*) value is also accepted to indicate all branches are accepted.
    • Default value: *
    • All branches are accepted by default.
  • auto_cancel: when new commits are pushed to a given branch, any existing automated checks that might be running will be automatically canceled.
    • Available choices: true, false
    • Default value: false
  • wait_time: this allows Squash to wait for a pre-defined amount of time before starting the automated check execution. This is useful for branches receiving commits very often and helps to reduce multiple concurrent checks for the same branch. When a developer pushes a new commit Squash will wait for a given amount of time, if new commits are pushed to that same branch and within the wait time then squash will only execute the check for the last commit after the wait time has expired.
    • Default value: null. By default Squash always executes a new automated check for each commit.
    • Available choices (“m” = minutes, “h” = hours): 5m, 15m, 30m, 1h, 2h, 3h, 4h, 5h, 6h

Squash YAML file sample:

deployments:
  MyApp:
    filename:
      ./Dockerfile
     build_policy:
      # available options: pr, commit. Default value is
      # "pr, commit", either a new PR or commit will
      # start a new build
      triggers: pr 
      # by default this is empty -
      # no restrictions
      restrict_branches: branchA, branchB 
      # default value is "*" which means all branches
      allow_branches: staging, production

copy_files

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

Example:

deployments:
  MyApp:
    filename:
      ./src/Dockerfile
    copy_files:
      - /assets/photos/ ~/code/myapp/photos/
      - /assets/product-pictures/ ~/code/myapp/product-pictures/

copy_files_build_process

  • Defines files that should be copied only before build process, specified in <source> <destination>format. This step is skipped when either Deployment Cache or Persistent Storage are being used.
  • Mandatory field: No
  • Data Type: List
  • Default value: null

Example:

deployments:
  MyApp:
    filename:
      ./src/Dockerfile
    copy_files_build_process:
      - /assets/dev-db.zip ~/code/myapp/dev-db.zip
      - /code/config/.profile ~/.profile

check_service_ports

Used by non-HTTP based deployments only. When this field is defined for a given application Squash will no longer check for HTTP success responses. Instead, Squash will ping one or more port numbers defined in this field in order to detect if the deployment is up.

By default, Squash will automatically open in the firewall all ports specified in this field, for the private IP only. You can customize this behavior by using the allow_traffic_ports field.

  • Defines one or more comma separated port numbers. These are port numbers of one or more services you might be running within this specific deployment.
  • Mandatory field: No
  • Data Type: Integer, comma separated
  • Default value: null

Example:

deployments:
  DatabaseService:
    dockerimage: postgres:9.4
    run_options: -e POSTGRES_PASSWORD=passwd -e POSTGRES_USER=user
    check_service_ports: 5432
    port_forwarding: 5432:5432

In this example above we are deploying a PostgreSQL database, named “DatabaseService” based on a given Docker image. For more information please check the non-HTTP based deployments page.

default_pr_comment

  • See: customizing PR comments.
  • Display the root endpoint URL without any query strings or subdomains
  • Mandatory field: No
  • Data Type: Boolean
  • Default value: True

The default PR comment looks like this and it’s included by default for every application within the Squash YAML file:

depends_on

This will enable the Deployment Dependencies feature.

  • Defines one or more dependencies. Dependency items can trigger separate Squash deployments.
  • Mandatory field: No
  • Data Type: list of dictionaries. The format for each dict item is
  • Default value: null

Example using one single dependency. PRODUCTS_API is the actual environment variable name that will be set in the CRM app deployment with the endpoint of this dependency as the env variable value. “api-products” is a repository name. Because we are not specifying any branch names Squash will attempt to use a branch names that matches the same branch name in the parent, otherwise it will fall back to the default branch (usually master) in the “api-products” repo.

deployments:
  CRM:
    filename:
      ./src/Dockerfile
    depends_on:
      - PRODUCTS_API:
          app: api-products

Three dependencies:

  • The first dependency only accepts branch “master” within the api-products repository.
  • The 2nd dependency requires an exact application within the api-search repository. Since we are not defining a specific branch name Squash will look for the exact same branch name as defined in the parent. If a matching branch name doesn’t exist on repository “api-search” then squash will use the default branch in the repo (most of the times it will be branch “master”).
  • The 3rd dependency requires branch “master” and the exact application named “App1”.
deployments:
  CRM:
    filename:
      ./src/Dockerfile
    depends_on:
      - PRODUCTS_API:
          app: api-products/master
      - SEARCH_API:
          app: api-search:App2
      - ENTITIES_API:
          app: api-entities/master:App1

More information on using dependencies with Squash.

deployment_page_commands

  • See: Custom Deployment Actions.
  • Defines additional commands that might be executed for a running deployment from Squash Dashboard page.
  • Mandatory field: No
  • Data Type: Dictionary
  • Default value: null

Field structure:

deployment_page_commands:
  <command name to be displayed>:
    - <listed scripts to be executed for all containers>
  <command name to be displayed>:
    <target container name>:
      - <listed scripts to be executed for specified container>

.squash.yml sample:

deployments:
  CRM:
    filename:
      ./src/crm/Dockerfile
    deployment_page_commands:
      command ABC:
        container-name123:
          - ./src/script-1.sh
        container-name987:
          - ./src/script-2.sh
      command XYZ:
        - ./src/script-3.sh
        - ./src/script-4.sh

domain

  • See: Custom Domains & Custom SSL.
  • 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

  • See: Environment Variables.
  • List of environment variables that applies to a single application.
  • Mandatory field: No
  • Data Type: List of key: value pairs
  • Default value: null

Example:

deployments:
  CRM:
    filename:
      ./src/Dockerfile
    environment:
      - TEST_VAL=42
      - CLIENT_API_ID=7612

Example using an API key defined in the Squash interface:

deployments:
  MyApp:
    filename:
      ./src/Dockerfile
    environment:
      - CLIENT_API_KEY=$API_KEY

install

This field provides great flexibility allowing you to fully control the deployment sequence.

  • List of supported commands: git, docker, docker-compose, kubectl, helm and minikube
  • Mandatory field: No
  • Data Type: List of commands
  • Default value: null

Please note that because this field is considered a low-level feature, many Squash YAML fields are skipped/ignored  when the “install” field is used:

  • copy_files
  • build_options
  • build_steps
  • context_path
  • copy_files
  • copy_files_build_process
  • dc_skip_docker_build
  • docker_registry
  • dockerfileonly
  • dockerimage
  • filename
  • kubernetes_build_image
  • kubernetes_default_pod
  • kubernetes_forwarding_wait
  • kubernetes_helm_chart
  • kubernetes_helm_parameters
  • kubernetes_helm_repository
  • kubernetes_kustomization
  • kubernetes_manifest
  • kubernetes_namespace
  • kubernetes_port_mapping
  • kubernetes_registry_secret
  • kubernetes_secrets
  • kubernetes_service
  • launch_steps
  • post_build_steps
  • pre_launch
  • run_options
  • use_kubernetes_registry

Example for a Kubernetes based deployment:

deployments:
  MyApp:
    install:
      - kubectl label namespace default istio-injection=enabled
      - kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml
      - kubectl apply -f samples/bookinfo/networking/bookinfo-gateway.yaml
      - export INGRESS_HOST=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
      - export INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="http2")].port}')
      - export SECURE_INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].port}')
      - export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT
      - kubectl apply -f samples/bookinfo/networking/destination-rule-all.yaml
      - kubectl create ns foo
      - kubectl apply -f <(istioctl kube-inject -f samples/httpbin/httpbin.yaml) -n foo
      - kubectl apply -f <(istioctl kube-inject -f samples/sleep/sleep.yaml) -n foo

Docker example:

deployments:
  MyApp:
    install:
      - docker-compose build
      - docker-compose up -d
      - docker-compose exec app bash -c 'python manage.py makemigrations && python manage.py migrate'

port_forwarding

  • Used for Docker and docker-compose 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
    • For docker-compose please always use the format docker_container_port:docker_container_port. Example:
      • 3000:3000
      • Assuming your main application is listening on port 3000.
  • 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

Example:

deployments:
  CRM:
    filename:
      ./src/crm/Dockerfile
    context_path:
      ./src
    post_launch:
      - target: app
        command: exec
        options: "{target} bash -c 'python manage.py makemigrations && python manage.py migrate'"

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: 1200

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

Example:

deployments:
  CRM:
    filename:
      ./src/crm/Dockerfile
    context_path:
      ./src
    vm_size:
      1GB
    run_options: --hostname ${SQUASH_BRANCH_WITH_ID} --env SQUASH_BRANCH=${SQUASH_BRANCH}

squash_pr_comments

Note: turning off the automatic PR comment is only available for paid accounts. On free accounts this field will be ignored and always set to true.

  • Controls the appearance of the automatic PR comments. The default value (true) will make the comment automatically appear on each new Pull/Merge request.
  • Data Type: Boolean
  • Default value: true

subdomains

See: Customizing PR Comments.

This is where you can list multiple pre-defined subdomains to appear in a Squash PR comment. 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.

Example yml file:

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

PR comment output:

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

  • See: 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

success_response_check

Defines custom logic for the success response check before Squash routes the deployment.

By default squash will first check for a success response on the original URL that triggered the deployment, then it will check for URLs (if any) defined within the “subdomains” field in the Squash YAML file. This default logic can be overwritten by using this “success_response_check” field allowing developers to fully customize what URLs to check before the deployment is routed.

This field expects a list of fields according to this basic structure:

success_response_check:
  fallback: true/false # default is "true" 
  url_check_behaviour: first_success/check_all # default is "first_success"
  urls: # one ore more URLs are expected
      - <URL 1>
      - <URL 2>
  • fallback: choices field accepting either true or false. The default value is true. When this field is set to true Squash will use any URLs defined under success_response_check as a fallback after checking for a success response within the URL that triggered the deployment + any subdomains (if any) defined in the YAML file. if this field is False Squash will only check for the URLs defined within the “urls” field of the success_response_check field.
  • url_check_behaviour: choices field accepting either first_success or check_all. The default value is first_success. This controls how Squash will handle the routing for any URLs defined in the “urls” field below.
    • first_success: Squash will immediately route the deployment when it receives a success response from any of the URLs defined, checking each URL in the exact order defined.
    • check_all: Squash will only route the deployment after all URLs are returning a success response.
  • urls: here you can list one or more URLs for a success response check.  This field accepts arguments and/or subdomains, for instance:
    • Plain URL with or without arguments: "/home" or "/home?abc=1"
    • Subdomain with or without arguments: "api--" or "api--,/?abc=1". Subdomains here are defined with Squash’s subdomain port mapping feature

Full example:

deployments:
  MyApp:
    filename:
      ./docker-compose.yml
    success_response_check:
      fallback: false 
      url_check_behaviour: check_all
      urls:
          - /home
          - /calendar,/?que=99764QQ
          - /acme-books,/search

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

vm_storage_gb

This is a custom storage size in GB to use for a given deployment. By default Squash will use the standard storage sizes as defined in the pricing page. This provides extra flexibility by using smaller VM sizes with more storage as needed.

  • Mandatory field: No
  • Data Type: Integer
  • 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