Environment Variables

Custom Environment Variables

You can define custom environment variables from the Squash admin interface.

Go to Settings -> Repositories

and then click on “Settings” for a given repository.

Each environment variable defined on this page will become available within the deployment host. They can also become available within docker containers with a few configuration steps (see below).

Using environment variables defined in the web interface within the YAML file

You can use environment variables defined in the Squash web interface anywhere within the Squash YAML file.

You just need to prefix the variable name with a dollar ("$") symbol to indicate to Squash that this is an environment variable.

For this example below we have previously defined a REGISTRY_PASSWORD in the Squash web interface:

deployments:
  MyApp:
    dockerimage:
      example.io/bobkane/bobkane/myapp-repo:master
    docker_registry:
      server: example.io
      username: bobkane
      password: $REGISTRY_PASSWORD

You may also use the format ${VAR_NAME} to concatenate multiple environment variables. Example: ${ENV1}${ENV2}

Defining environment variables in the YAML file

You may also define custom environment variables within the .squash.yml file.

Passing environment variables to containers: Dockerfile

If you are using a Dockerfile then you need to specify what environment variables should become available inside containers. You can do this by defining a "run_options" field as follows:

deployments:
  MyApp:
    filename: Dockerfile
    run_options: --env MY_CUSTOM_VAR1=${CUSTOM_VAR1}

for the example above, "CUSTOM_VAR1" is the name of an environment variable defined in the Squash web interface.

You may pass multiple env variables as follows:

run_options: --env MY_VAR1=${VAR1} --env MY_VAR2=${VAR2} --env MY_VAR3=${VAR3}

Passing environment variables to containers: docker-compose

Docker-compose deployments require that you define the env variable names in the docker-compose file itself so Docker can properly map the values from the env variables in the host machine.

Example:

version: '3.1'
services:
  api-service:
    build: ./my-app
    ports:
      - 80:80
    environment:
      - SERVICE_API_KEY=123
      - SQUASH_CUSTOM_VAR1

For the example above, SQUASH_CUSTOM_VAR1 is an environment variable defined in the Squash web interface. When you run the container above docker will properly bring the value of this env variable as defined in Squash.

Passing environment variables to containers: Squash YAML based apps (no Docker)

For a Squash YAML deployment (no Docker), the process is the same as using a Dockerfile. You need to define a "run_options" field as follows:

deployments:
  MyWebApp:
    dockerimage: ubuntu:14.04
    build_steps:
      - apt-get update && apt-get install -y libssl-dev libpq-dev git \
        python python-dev python-pip python-virtualenv
      - pip install setuptools pip
      - pip install /code
    launch_steps:
      - cd /myproject/mysite
      - python manage.py runserver 0.0.0.0:80
    run_options: --env CUSTOM_VAR1=${SQUASH_CUSTOM_VAR1}

Escaping of environment variables

You might need to wrap an environment variable with quotes if you have any special characters within it. You can do it as follows:

run_options: --env SQUASH_CUSTOM_VAR1="${SQUASH_CUSTOM_VAR1}"

Visibility of Environment Variables

All environment variables defined in the Squash interface above will be displayed in the beginning of the log output on the deployment loading page.

By default the actual value of each environment variable will be hidden in the log output, as long as the "Show in the deployment logs" field above is unchecked. Squash will still properly set the variable and its content/value in the application environment within the deployment.

This is a typical output of a custom environment variable with its value hidden ("Show in the deployment logs" field is unchecked):

Default Environment Variables

Squash automatically sets a number of environment variables during each deployment. These environment variables are made available on the deployment host server. You can easily pass each of these env variables to docker containers by using the instructions in the sections above.

Squash will set these variables right before the docker build or docker-compose build process.

SQUASH_DOMAIN

The full Squash deployment URL including the actual squash.io domain or the custom domain being used (if applicable) for the current deployment.

Example:

cartv3-i3xg7.squash.io

Or when using a custom domain:

cartv3-i3xg7.example.com

SQUASH_BRANCH

This is the original branch name in GitHub including any special characters. Note that the original branch name will not always match the branch name that appears in the URL since Squash removes special characters that don’t fit within the URL schema.

SQUASH_COMMIT_SHA

This is the commit SHA-1 hash for the last commit retrieved in the current Squash deployment. Please note that when a deployment is retrieved with Persistent Storage Squash doesn't automatically fetch the latest code, hence this information might not represent the actual last commit in the branch. See the Squash build process for more details.

Example:

ce7500129926e754fa37abd505134c88ecc6a392

SQUASH_BRANCH_WITH_ID

This is the remaining component of all Squash deployment URLs excluding the domain name.

For this given deployment URL:

cartv3-i3xg7.squash.io

The value of SQUASH_BRANCH_WITH_ID will be:

cartv3-i3xg7

SQUASH_MASTER_DEPLOYMENT

Used by the deployment dependencies feature. This holds a reference of a parent deployment within a deployment chain.

More details here.

SQUASH_CHILD_DEPLOYMENT_X

Used by the deployment dependencies feature. This holds a reference of a child deployment within a deployment chain. The "X part is a unique integer representing a child deployment.

More details here.

Can I use Docker secrets with Squash?

Yes, see Docker build secrets.