Instances and Environments

CAP provides two powerful ways to manage variations of your application's configuration: Instances and Environments. Understanding the difference between them is key to effectively structuring your config.cap.yaml.

Overview

• Instances: Use instances when you need to deploy completely separate, parallel "copies" of the same application. A common use case is for regional deployments, where you might have one copy of your application for the Netherlands (nl) and another for Belgium (be), each with its own database, domain, and specific settings.

• Environments: Use environments to define variations for different stages of the development lifecycle, such as staging and production. An environment typically shares the same codebase but has different settings for things like replicas, resources, or connections to external services.

Note

To learn how these different configuration levels are merged together, please see the Configuration Hierarchy documentation.

Using instances

The instances block allows you to define multiple, named copies of your application. Each instance is a self-contained configuration that inherits from the top level.

Example Use Case: Deploying a webshop to both the Netherlands and Belgium.

# Top-level defaults
type: php
http:
  port: 8080

services:
  db:
    type: mariadb
    version: "10.6"

connections:
  - service: "db"

instances:
  # Netherlands instance
  nl:
    hostname: "my-shop.nl"
    env:
      APP_COUNTRY: "NL"

    environments:
      production:
        hostname: "www.my-shop.nl"
        http:
          replicas: 5

  # Belgium instance
  be:
    hostname: "my-shop.be"
    env:
      APP_COUNTRY: "BE"

    environments:
      production:
        hostname: "www.my-shop.be"
        http:
          replicas: 3

In this example:

• We have two instances, nl and be.
• Each instance gets its own hostname and a specific APP_COUNTRY environment variable.
• By default services are instance-scoped, so each instance gets its own db service. Even though they have the same definition, CAP will provision two completely separate databases, one for each instance.
• Each instance also has a production environment that overrides the hostname and replicas for that specific instance's production deployment.

Using environments

The environments block can be used either at the top level (if you don't use instances) or nested inside an instance. It allows you to tailor your configuration for different deployment stages.

Example Use Case: A single application with staging and production environments.

# config.cap.yaml
type: laravel
hostname: "my-app.dev" # Default hostname for non-production

http:
  replicas: 1 # Default replicas for non-production

services:
  db:
    type: mariadb
    version: "10.6"

environments:
  staging:
    hostname: "staging.my-app.com"
    # Inherits replicas: 1

  production:
    hostname: "www.my-app.com"
    http:
      replicas: 10 # Overrides the default
    env:
      APP_DEBUG: false

In this example:

• The top-level configuration provides a baseline for a development-like setup.
• The staging environment gets its own hostname but otherwise uses the top-level defaults.
• The production environment overrides the hostname, increases the number of replicas, and sets a production-specific environment variable.