Background Processes

Mint supports background processes for running commands alongside the defined run command for task. The most common use case is running docker compose to run services necessary for your application. See Mint's docker documentation for more information on using Docker with background processes.

Example using Redis

tasks:
  - key: packages
    run: |
      sudo apt-get update
      sudo apt-get install redis-server
      sudo apt-get clean

  - key: test-redis
    use: [packages]
    background-processes:
      - key: redis
        run: redis-server
        ready-check: redis-cli ping
    run: |
      redis-cli SET mykey "Hello, Redis!"
      redis-cli GET mykey

Ready Checks

The ready-check script is optional.

If it is not specified, the run script for the task will start running immediately after all of the background processes have been started. If your run script needs a background service to be ready, such as a database process actively listening for connections, not having a ready-check script could result in a race condition where the run script could execute before the background service is ready. To prevent this problem, add a ready-check script to your background processes. Once the ready check for all background processes has passed, the run script will execute.

See the Mint docker documentation for considerations when specifying ready checks when running docker containers.

Sequencing Background Processes

Mint will start all background processes in parallel. If some of your background processes need to be started after others, you can use the after: declaration to specify the dependencies.

For example, if you need a database to start before starting a web app, you could do this:

background-processes:
  - key: database
    run: ...
    ready-check: ...

  - key: web-server
    after: [database]
    run: ...
    ready-check: ...

Checking for Ports

If you want to make sure a processes is up and listening on a port, you can install the netcat package and then use nc to check for it. For example, checking for redis to be listening on port 6379:

tasks:
  - key: packages
    run: |
      sudo apt-get update
      sudo apt-get install netcat redis-server
      sudo apt-get clean

  - key: test-redis
    use: [packages]
    background-processes:
      - key: redis
        run: redis-server --port 6379
        ready-check: nc -z localhost 6379
    run: |
      redis-cli SET mykey "Hello, Redis!"
      redis-cli GET mykey

However, many servers will start listening on a port before it's actually ready to be used. For example, postgres will start listening on its default port of 5432 before it's actually ready to handle queries. When possible, use service specific tools to check for for the server being ready, such as redis-cli ping for Redis and pg_isready for Postgres.

Ready Check Timeouts

You can configure a timeout for the ready check to pass like this:

background-processes:
  - key: redis
    docker: true
    run: docker run -p 6379:6379 index.docker.io/library/redis:latest
    ready-check:
      run: nc -z localhost 6379
      timeout-seconds: 20

If a timeout is not specified, the default timeout is 60 seconds. In practice, it's uncommon to lower the timeout. The ability to override the default timeout mostly exists for scenarios where a background process may need more than the default of 60 seconds to start. The overall task timeout (configured via timeout-minutes on the task definition, default of 10 minutes) will still apply, and is inclusive of the background processes.

Graceful Termination

Background processes are sent a SIGTERM signal and given time to clean up before being stopped with SIGKILL. For more information, see the graceful termination documentation.