Skip to main content

Configuration

The code repository for a Thermostat application must contain a thermostat.yml file, which serves as the core configuration mechanism for the application. See an example of this configuration below:

version: '0.0.3'

services:
  nginx:
    conf: config/nginx/development.conf
  php-8.1:
    enabled: true
  mariadb:
    database: example
    file: example
    password:
      envfile: .env:DB_PASSWORD
  redis:
    password:
      envfile: .env:REDIS_PASSWORD

data_links:
  .env: .env
  uploads: app/files/uploads

develop:
  watch:
    restart_on:
      - src/*
      - assets/*
  compare:
    project_token:
      envfile: .env:PERCY_TOKEN
    entrypoints:
      - example.com
    exclude:
      - /posts/*
      - ~/posts/first-post

scripts:
  build:
    image: node:19.8.1-alpine3.17
    script:
      - yarn
      - yarn build

  example:
    image:
      context: config/docker/example
      dockerfile: Dockerfile
    script:
      - docker compose run example
    dockerAccess: true
    privileged: true
    skipSetup: true
    user: root

environments:
  production:
    services:
      certbot:
        domains:
          - example.com
    scripts:
      build:
        image: node:19.8.1-alpine3.17
        script:
          - yarn
          - yarn production_build

These configuration values are broken down in detail below:

version​

This is the version number of the thermostat.yml configuration file format being used. If you use an old version of the configuration file format with a newer version of Thermostat it will tell you that your configuration file needs to be updated. The latest version of the configuration file format is 0.0.3.

services​

This object contains values for configuring the behaviour of the various Thermostat services.

services.nginx​

This object contains values for configuring the behaviour of the Nginx Thermostat service. Note that the Nginx service cannot be enabled at the same time as the Caddy service because they both need to bind the same ports.

services.nginx.conf​

This is the path to the Nginx configuration file for the application. This path can contain environment variables, and the configuration file itself can contain environment variables.

services.nginx.enabled​

This is a boolean that can be set to false to disable the Nginx service. This is primarily useful if the service is on by default but should be disabled in a particular environment.

services.caddy​

This object contains values for configuring the behaviour of the Caddy Thermostat service. Note that the Caddy service cannot be enabled at the same time as the Nginx service because they both need to bind the same ports.

services.caddy.conf​

This is the path to the Caddy configuration file for the application. This path can contain environment variables, and the configuration file itself can contain environment variables.

services.caddy.enabled​

This is a boolean that can be set to false to disable the Caddy service. This is primarily useful if the service is on by default but should be disabled in a particular environment.

services.php-7.3​

This object contains values for configuring the behaviour of the PHP 7.3 Thermostat service.

services.php-7.3.enabled​

This is a boolean that can be set to true to enable the PHP 7.3 service or false to disable it. It is false by default.

services.php-7.4​

This object contains values for configuring the behaviour of the PHP 7.4 Thermostat service.

services.php-7.4.enabled​

This is a boolean that can be set to true to enable the PHP 7.4 service or false to disable it. It is false by default.

services.php-8.0​

This object contains values for configuring the behaviour of the PHP 8.0 Thermostat service.

services.php-8.0.enabled​

This is a boolean that can be set to true to enable the PHP 8.0 service or false to disable it. It is false by default.

services.php-8.1​

This object contains values for configuring the behaviour of the PHP 8.1 Thermostat service.

services.php-8.1.enabled​

This is a boolean that can be set to true to enable the PHP 8.1 service or false to disable it. It is false by default.

services.php-8.2​

This object contains values for configuring the behaviour of the PHP 8.2 Thermostat service.

services.php-8.2.enabled​

This is a boolean that can be set to true to enable the PHP 8.2 service or false to disable it. It is false by default.

services.mariadb​

This object contains values for configuring the behaviour of the MariaDB Thermostat service.

services.mariadb.database​

This value is the database name of the MariaDB database used by the project.

services.mariadb.file​

This value is the filename to use for the SQL backup file stored in the application data folder in the mariadb directory to import or export the database contents.

services.mariadb.password.envfile​

This value indicates where Thermostat should look for the MariaDB password value. The value format should be ${file}:${name}, where file is the filename (relative to the project root) of the dotenv file with the environment variable containing the password, and name is the name of the environment variable in the dotenv file that contains the MariaDB password value.

services.mariadb.enabled​

This is a boolean that can be set to false to disable the MariaDB service. This is primarily useful if the service is on by default but should be disabled in a particular environment.

services.redis​

This object contains values for configuring the behaviour of the Redis Thermostat service.

services.redis.password.envfile​

This value indicates where Thermostat should look for the Redis password value. The value format should be ${file}:${name}, where file is the filename (relative to the project root) of the dotenv file with the environment variable containing the password, and name is the name of the environment variable in the dotenv file that contains the Redis password value.

services.redis.enabled​

This is a boolean that can be set to false to disable the Redis service. This is primarily useful if the service is on by default but should be disabled in a particular environment.

services.certbot​

This object contains values for configuring the behaviour of the Certbot Thermostat service.

services.certbot.domains​

This is an array of domains that Certbot should provision SSL certificates for.

services.certbot.enabled​

This is a boolean that can be set to false to disable the Certbot service. This is primarily useful if the service is on by default but should be disabled in a particular environment.

This is an object that specifies symlinks that will be created by Thermostat to link files from the data folder into the code folder. The object key value is the path of the file that exists in the data folder, and the object value associated with each key is the path of the associated file that will be created in the code folder.

develop​

This object contains values for configuring the behaviour of the thermostat develop command.

develop.watch​

This object contains values for configuring the behaviour of the thermostat develop watch command.

develop.watch.restart_on​

This is an array of rules that indicate which paths will be watched for changes when the watch command is running. If any files matching these rules are modified the watch command will automatically run the start script.

develop.compare​

This object contains values for configuring the behaviour of the thermostat develop compare command.

develop.compare.project_token.envfile​

This value indicates where Thermostat should look for the Percy project token value. The value format should be ${file}:${name}, where file is the filename (relative to the project root) of the dotenv file with the environment variable containing the token, and name is the name of the environment variable in the dotenv file that contains the Percy project token value.

develop.compare.entrypoints​

This is an array of URLs that indicate where the crawler should start crawling the website from. The crawler will recursively find all links referenced on these pages and crawl those URLs as well, in order to automatically build up a full sitemap of the website for comparison.

develop.compare.exclude​

This is an array of rules that indicate which paths should be excluded from the sitemap. These rules should contain just the path part of the URL, not including the domain. The rules have full glob support as described by man 7 glob. If the rule begins with a ~ character, then the rule acts as an include rule instead of an exclude rule. These include rules are used to create specific exceptions to more general exclude rules, for example if there is an exclude rule that excludes all the blog posts of a website such as /posts/*, you can also add an include rule of ~/posts/first-post to have it still include that single blog post in the sitemap. The rules are evaluated in the order they are listed in the array, so include rules should be listed after the exclude rules that they override.

scripts​

This is an array of objects, each of which represents a single script that can be run using the thermostat run command.

scripts.*.image​

This value indicates what Docker image to use to run the script. This can either be a string which contains the Docker image registry identifier, or if can be an object with details on how to build the Docker image.

scripts.*.image.context​

This is the context folder that will be used for building the image for the script, it works the same way as the Docker compose build specification.

scripts.*.image.dockerfile​

This is the path to the Dockerfile (relative to the context folder) that will be used for building the image for the script, it works the same way as the Docker compose build specification.

scripts.*.script​

This is an array of strings that will be merged into a single Bash script that will be executed in the specified Docker image.

scripts.*.dockerAccess​

This is a boolean that indicates whether or not the Docker daemon socket file should be mounted into the Docker container that runs the script. This should only be enabled if you need to run Docker commands in your script. This value is false by default.

scripts.*.privileged​

This is a boolean that indicates whether or not the Docker container that runs the script should be run in privileged mode. This should generally not be used, but it is useful in certain exceptional circumstances. This value is false by default.

scripts.*.skipSetup​

This is a boolean that indicates whether or not to skip the setup script that Thermostat normally runs in the Docker container prior to running the application Bash script. This setup script sets up the appropriate users, permissions, and configuration files in the container to allow it to run in a predictable fashion across a wide variety of different docker containers. You can see the code for the setup script here. It is very rare that you need to disable this script, but it is useful in certain exceptional circumstances. This value is false by default.

scripts.*.user​

This is a string value that can be used to override the user ID and group ID of the user that executes this script in the Docker container. If you do not specify this value, then the user ID and group ID of the user that executes the script in the container will be the same as the user ID and group ID of the user that executes the thermostat run command on the host machine. The valid values are:

  • root: Run as the root user.
  • nginx: Run with the same user ID/group ID that the Thermostat Nginx service runs as.
  • php: Run with the same user ID/group ID that all Thermostat PHP services run as.
  • mariadb: Run with the same user ID/group ID that the Thermostat MariaDB service runs as.
  • redis: Run with the same user ID/group ID that the Thermostat Redis service runs as.
  • certbot: Run with the same user ID/group ID that the Thermostat Certbot service runs as.

environments​

This object contains values for configuring the behaviour of different environments for the application. It can contain any of the configuration values listed above, and it will override those values on the specified environment. For example, if there is a start script specified at the root of the thermostat.yml file and there is a different start script specified in the production environment configuration under "environments.production.scripts", then if you run the start script on any environment except production it will run the script defined at the root, but if you run the start script on a production environment it will run the start script defined in "environments.production.scripts".

environments.development​

This object contains values for configuring the behaviour of development environments for the application.

environments.staging​

This object contains values for configuring the behaviour of staging environments for the application.

environments.production​

This object contains values for configuring the behaviour of production environments for the application.

Environment Variables​

Some Thermostat configuration values and files can contain environment variables that are replaced with the values appropriate to the environment when the configuration values are read. The environment variables that can be used are listed below:

  • THERMOSTAT_VERSION: This is the version of Thermostat that is running.
  • THERMOSTAT_USER: This is the Thermostat user identifier of the user that is running Thermostat.
  • THERMOSTAT_APPLICATION_ID: This is the full Thermostat deployment identifier for this deployment of the application.
  • THERMOSTAT_APPLICATION_DIRECTORY: This is the path of the directory where Thermostat services will find the application files on disk when they run.
  • THERMOSTAT_APPLICATION_HOST_DIRECTORY: This is the path of the directory where the application files live on disk on the host machine. This is generally only used when working directly with Docker.
  • THERMOSTAT_APPLICATION_CLIENT: This is the Thermostat client identifier of the client that owns this application.
  • THERMOSTAT_APPLICATION_NAME: This is the Thermostat application identifier for this application.
  • THERMOSTAT_APPLICATION_STAGE: This is the Thermostat stage name for the stage used by this deployment of the application.
  • THERMOSTAT_APPLICATION_SUBSTAGE: This is the Thermostat substage identifier for the stage used by this deployment of the application.
  • THERMOSTAT_APPLICATION_STAGE_ID: This is the full Thermostat stage identifier for this deployment of the application which includes both the stage and substage information.
  • THERMOSTAT_APPLICATION_REPO: This is the Git remote URL of the repository used to store the code for the application.
  • THERMOSTAT_CERTBOT_DIRECTORY: This is the path of the directory where Thermostat services will find the Certbot SSL certificate files for this deployment of the application. This value is only available for use in Nginx configuration files.