Environment

Introduction

When Torch initiates a new build, it boots the container and prepares the environment to run the application. This consists of configuring the database, injecting environment variables, pulling down the Composer cache, cloning the repository, etc.

Due to the fact that Torch is fine-tuned for Laravel, and that Laravel Forge (opens new window) manages more than 400,000 servers, we decided to replicate the environment that Forge provisions. Our containers run Ubuntu 20.04 with most of the software that comes by default with a Forge server.

Sudo access

You are free to use sudo to gain root access to install any other software that you may need to build the application.

Build Dependencies

All build dependencies are configured before your CI pipeline runs, so make sure to properly configure the environment beforehand.

Roadmap for Torch

To keep up with the latest features in Torch, read the blog (opens new window) and our roadmap (opens new window) for future.

Composer Version

You may configure the Composer version by specifying the composer key in your project's torchci.yml file or via the project settings. If this value is not specified, Torch uses the configuration from the project's settings as default.

Key Description
1 Latest Composer 1.x version
2 Composer 2.0.8
composer: 2
build:
    - 'composer install'
    - 'npm install'
    - 'npm run production'
    - 'phpunit'

PHP Version

You may configure the PHP version by specifying the php key in your project's torchci.yml file or via the project settings. If this value is not specified, Torch uses the configuration from the project's settings as default.

Key Description
7.3 PHP 7.3
7.4 PHP 7.4
8.0 PHP 8.0
php: 7.4
build:
    - 'composer install'
    - 'npm install'
    - 'npm run production'
    - 'phpunit'

Node & NPM Version

You may configure the Node.js and NPM versions by specifying the node key in your project's torchci.yml file or via the project settings. If this value is not specified, Torch uses the configuration from the project's settings as default.

Key Description
12 Node v12
14 Node v14
15 Node v15
node: 14
build:
    - 'composer install'
    - 'npm install'
    - 'npm run production'
    - 'phpunit'

Database

Unlike Composer, PHP and Node dependencies, database runs as a separate container next to the container that runs the build. By default, no database container is configured to run and the SQLite database is used as a default. To configure the database, you may specify the database key in your project's torchci.yml file.

Key Description
mysql:5.6 MySQL 5.6
mysql:5.7 MySQL 5.7
mysql:8 MySQL 8
mariadb:10.3 MariaDB 10.3
postgres:11 PostgreSQL 11
database: mysql:8
build:
    - 'composer install'
    - 'npm install'
    - 'npm run production'
    - 'phpunit'

Environment Variables

Torch will automatically inject all necessary database environment variables in the container.

Cache

Unlike Composer, PHP and Node dependencies, cache runs as a separate container next to the container that runs the build. By default, no cache container is configured to run and the array cache driver is used as a default. To configure the cache, you may specify the cache key in your project's torchci.yml file.

Key Description
redis Latest redis version
cache: redis
build:
    - 'composer install'
    - 'npm install'
    - 'npm run production'
    - 'phpunit'

Environment Variables

Torch will automatically inject all necessary cache environment variables in the container.

Environment Variables

To make things easier for you, Torch automatically injects several environment variables. However, all environment variables that you inject will override variables that Torch injects.

To define which environment variables will be pulled into the container, specify the environment key in your project's torchci.yml file or by adding them right from the project settings.

environment:
    APP_ENV: testing
build:
    - 'composer install'
    - 'npm install'
    - 'npm run production'
    - 'phpunit'

Security

We avoid adding sensitive information through the YAML configuration for security reasons. Also, all environment variables specified in the project settings are encrypted using secure two-way encryption and are never stored in a raw, unencrypted format.

List of core environment variables that Torch injects:

Key Value
APP_ENV testing
APP_KEY Randomly generated encryption key
APP_DEBUG true
DB_CONNECTION sqlite if no database is used, mysql/pgsql otherwise
DB_DATABASE torchci.sqlite if no database, laravel otherwise
DB_HOST 127.0.0.1
DB_PORT 3306 or 5432
DB_USERNAME torchci
DB_PASSWORD secret
CACHE_DRIVER redis or array
REDIS_CLIENT predis
REDIS_HOST 127.0.0.1
REDIS_PASSWORD null
REDIS_PORT 6379

Common Issues

As Torch injects database and cache environment variables, the most common issue for CI builds failing is developers manually setting these variables, or some part of your codebase is overriding these variables, such as phpunit.xml file. You don't need to manually set DB_* variables in your phpunit.xml file. Also, in the recent PHPUnit versions, if your variables are defined using <server> block instead of the <env> block in the phpunit.xml file, in some cases Torch will not be able to override these defined variables during the build.

For example, the following snippet from the phpunit.xml file will correctly use the in-memory SQLite database when running tests locally, but it will use an actual MySQL / PostgreSQL engine in the Torch build:

<env name="APP_ENV" value="testing"/>
<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>

Reserved Variables

Other than environment variables that Torch automatically injects, you may also find useful some additional environment variables that Torch provides:

Key Description
CI_COMMIT_SHA Hash of the commit being built
CI_COMMIT_SHA_SHORT Short version of the hash of the commit being built
CI_COMMIT_BRANCH Branch being built
CI_COMMIT_MESSAGE Commit message
TORCH_BUILD_ID ID of the build
TORCH_DIR Base path in the Torch container
TORCH_REPO_DIR Path to the repository in the Torch container

Use these environment variables just like you would use all other shell environment variables, e.g. vapor deploy production --message="${CI_COMMIT_MESSAGE}"

Reserved

These environment variables are reserved and cannot be overwritten.

Application Logs

When project is created, Torch tries to determine the appropriate type of the project (Laravel, Symfony, PHP) and uses that information to know where to scan for log files. After a build ends, Torch recursively finds all *.log files in a codebase, archives them and stores securely. In a build detail page you may review the last 200 lines of each log file as well as find the URL for downloading a log artifact containing all application log files.

To override the path where Torch will recursively look for *.log files, specify the logs key in your project's torchci.yml file, or right from the project's settings.

logs: storage/logs
build:
    - 'composer install'
    - 'npm install'
    - 'npm run production'
    - 'phpunit'

We recommend avoiding scanning all directories (logs: /root) in a container to avoid log files from vendor or any other non-relevant directories from scanning.