Creating an Environment

Before you Begin

This article assumes you've read Intro to Architect for a fundamental understanding of Architect's Service, Environment, and Platform constructs.

You may create an Environment through the web UI or the CLI. As always, we recommend getting comfortable with the CLI.

What is an Architect Environment?

We use the word 'environment' colloquially- probably similar to the way you've used it in the past. Informally, it's that "place" where you run your software services. Formally, the Environment is Architect's primary abstraction for a stack of services and their runtime context.

The Environment specifies the state among which a set of Services will run. And just as the Service declares the parameters that it will require for execution, it is up to the Environment to set values for those parameters at execution time. Thus, the Environment Definition carries two essential pieces of information:

  • the set of services that are intended to be run ("in that environment")
  • the values to the parameters that each of those services require ("specific to that environment")

Beyond that, the Environment Definition also gives us an opportunity to define other information relevant to a running stack, such as:

  • ingress/egress policies
  • networking and monitoring plugins

Creating an Empty Environment from the CLI

The most basic Environment configuration is one which declares no services. You can create an empty environment (call it stage) by running architect env:create stage. The prompts you receive will give you a pretty good idea about the minimal pieces of information that the environment requires. Notably, you will have to choose your Platform. If you've not set one up previously, it will prompt you to connect one. We'd recommend digging into that flow now if this is your first Environment.

If you navigate to https://app.architect.io/users/me, then select the account that you created the environment under, you will see the new environment you just created under the Environments tab. This environment is ready to go; you should be able to deploy services to it out of the box.

Specifying an Environment Definition File

The Environment Definition file allows the user to specify the contents of an environment as a static JSON file. We encourage our users to commit these to a private git repository just as you would with any other infrastructure-as-code solution.

The most basic Environment Definition contains a services block with a single service. Create a file called stage.env.json with the following contents:

{
  "services": {
    "architect/my-frontend-service:latest": { // <-- use `account/service:tag` as the key to the service block
      "parameters": {  // <-- these are the parameters required by the Service. This Environment Definition sets values for each one.
        "LOG_LEVEL": "debug",
        "PROD": "false",
        "ACCESS_TOKEN": "file:~/.some/secret.txt"
      }
    }
  }
}

Running architect deploy stage.env.json -e stage will deploy this environment definition to the stage environment.

If the service has requested that a datastore be provided, the Environment Definition will also need to specify the values for the datastore parameters:

{
  "services": {
    "architect/my-frontend-service:latest": {
      "parameters": {
        "LOG_LEVEL": "debug",
        "PROD": "false",
        "ACCESS_TOKEN": "file:~/.some/secret.txt"
      },
      "datastores": { // <-- these are the datastores required by the Service. This Environment Definition sets values for each parameter.
        "primary": {
          "host": "172.17.0.1"
        }
      }
    }
  }
}

If the environment is some local developer's machine, users can optionally set a debug key to define the relative path of the service code. Create a file called local.env.json with contents that look like this:

{
  "services": {
    "architect/my-frontend-service:latest": {
      "debug": { // <-- optionally providing a debug block allows the user to override the service definition for local development
        "path": "../my-backend-service",
        "dockerfile": "debug.Dockerfile",
        "volumes": [
          ".:/hack",
          "modules:/usr/src/app/modules",
          "config:/usr/src/app/config",
          "utils:/usr/src/app/utils"
        ]
      },
      "parameters": {
        "LOG_LEVEL": "debug",
        "PROD": "false",
        "ACCESS_TOKEN": "file:~/.some/secret.txt"
      },
      "datastores": {
        "primary": {
          "host": "172.17.0.1"
        }
      }
    }
  }
}

Now you can run architect deploy local.env.json --local to deploy the Environment Definition to your local machine. Rather than pulling the service from the architect registry, Architect will substitute it with the service located at the path you specified and mount that directory in place of the service.

Full Example Environment Definition

A full example Environment Definition including common options is below.

{
  "services": {
    "architect/my-frontend-service:latest": {
      "debug": {
        "path": "../my-frontend-service"
      },
      "parameters": {
        "AN_ENV_PARAMETER": "local",
        }
      },
      "datastores": {
        "primary": {
          "host": "172.17.0.1"
        }
      }
    },
    "architect/my-backend-service:latest": {
      "debug": {
        "path": "../my-backend-service",
        "dockerfile": "debug.Dockerfile",
        "volumes": [
          ".:/hack",
          "modules:/usr/src/app/modules",
          "config:/usr/src/app/config",
          "utils:/usr/src/app/utils"
        ]
      },
      "parameters": {
        "AN_ENV_PARAMETER": "local"
      }
    }
  }
}