Environment Variables

Flightcontrol lets you set environment variables in two ways - in the dashboard, or in your flightcontrol.json file. When you use the flightcontrol.json file, you can override those values in the dashboard, if needed.

In addition to environment variables you provide, Flightcontrol also sets a few environment variables for you automatically. These are described below, in the Built-in Environment Variables section.

Setting Environment Variables in the Dashboard

To set environment variables in the dashboard, find the Environment Variables section for an individual environment in a project.

Existing environment variables will be listed by name, but their values will not be shown.

Flightcontrol has two options for storing environment variables:

AWS Parameter Store - limited to one region
AWS Secrets Manager - globally available, but has a fee associated with it (from AWS)

We generally suggest using the AWS Parameter Store, unless you need to access the environment variable from multiple regions.

Many environment variables are somewhat sensitive, so Flightcontrol does not store them itself. If you need to access the value of an environment variable that you set in the dashboard, you can use the AWS Parameter Store to inspect and retrieve that value. The Flightcontrol dashboard has a direct link to the AWS Parameter Store for the region your application is deployed in.

Setting Environment Variables in `flightcontrol.json`

To set environment variables in your flightcontrol.json file, add an envVariables object to an individual service configuration. The keys of the envVariables object are the environment variable names, and the values are the environment variable values.

There is a special case where you want to pull an environment variable from another service, instead of setting it directly. In this case, you can use the fromService object, which has two keys:

id - the id of the service to pull the environment variable from
value - the name of the environment variable to pull from the other service

In the following example, we set two environment variables on the web-server service - one for the app environment, and one as the database connection URL, pulled in from the db service.

flightcontrol.json

    "services": [
        {
            "id": "web-server",
            "name": "Web Server",
            "type": "web",
            "target": {"type": "fargate"},
            "buildType": "nixpacks",
            "ci": {
              "type": "ec2"
            },
            "cpu": 0.5,
            "memory": 1,
            "minInstances": 1,
            "maxInstances": 1,
            "envVariables": {
                "APP_ENV": "production",
                "DATABASE_URL": {
                    "fromService": {
                        "id": "db",
                        "value": "dbConnectionString"
                    }
                }
            }
        },
        {
          "id": "db",
          "name": "Database",
          "type": "rds",
          "engine": "postgres",
          "engineVersion": "15",
          "instanceSize": "db.t4g.micro",
          "storage": 20,
          "private": false
        }
    ]

Viewing Environment Variables

Once you set environment variables in the dashboard, and save them, you will not be able to view them again in the Dashboard. This is because Flightcontrol does not store the values of environment variables. These values get saved in the AWS Parameter Store or the AWS Secrets Manager.

In the Flightcontrol dashboard, you will find a link to the AWS Parameter Store for the region your application is deployed in. You can use this link to view the environment variables for your application in the AWS Console.

Runtime-only Environment Variables

When Flightcontrol builds your application using Nixpacks or Dockerfile builds, it makes all of the environment variables available to the build process. Normally, the environment variables become part of the Docker image, and then are available to your application at runtime.

For some scenarios, you may want to make an environment variable available to your application at runtime, but not have it become part of the Docker image. For example, you may want to set an environment variable that contains a secret, but you don’t want that secret to be part of the Docker image.

Runtime-only Environment Variables in the Dashboard

This runtime-only behavior is supported in the dashboard on a per-service basis. For each service, you can choose whether or not to include environment variables in the build environment. The checkbox is labeled Include environment variables in build environment, and is available in the Config tab for each service.

Runtime-only Environment Variables in `flightcontrol.json`

For each service in your flightcontrol.json file, you can set the includeEnvVariablesInBuild property to true or false. This property is true by default. To enable runtime-only behavior, set this property to false.

{
  "services": [
    {
      "id": "webapp",
      "name": "Web App",
      "type": "web",
      "target": {"type": "fargate"},
      "buildType": "nixpacks",
      "ci": {
        "type": "ec2"
      },
      "cpu": 0.5,
      "memory": 1,
      "minInstances": 1,
      "maxInstances": 2,
      "envVariables": {
        "SECRET_API_KEY": "ABC-123"
      },
      "includeEnvVariablesInBuild": false
    }
  ]
}

Built-in Environment Variables

Flightcontrol provides you with a set of built-in environment variables during the build and after a deployment.

Your code can use these environment variables just like any others you may set yourself.

The most useful variables are:

FC_URL - the public URL of your application
FC_GIT_COMMIT_SHA - the git commit SHA of the code that was deployed
FC_GIT_BRANCH - the git branch of the code that was deployed
FC_GIT_PR_NUMBER - the git pull request number, this is only available for preview environments only
FC_AWS_REGION - the AWS region your application is deployed in
FLIGHTCONTROL=true - set for both build and runtime
PORT - the port your application should listen on
NODE_OPTIONS - dynamically sets --max-old-space-size based on the builder size. It’s set as large as possible with only 1 GB or 80%, whichever is smaller, will be reserved for the operating system (only available in EC2 builder)

Example environment variables from a Flask/Redis deployment:

REDIS_URL=rediss://:password@master.fc-ec-redis-something.something.usw2.cache.amazonaws.com:6379
AWS_EXECUTION_ENV=AWS_ECS_FARGATE
HOSTNAME=ip-10-192-11-11.us-west-2.compute.internal
FC_AWS_REGION=us-west-2
AWS_DEFAULT_REGION=us-west-2
AWS_REGION=us-west-2
PORT=3000
HOME=/root
NIXPACKS_VERSION=1.6.0
NIXPACKS_METADATA=python
FC_GIT_BRANCH=main
USER=root
FC_GIT_COMMIT_SHA=d124dbe7097b884115ae59270dacf2876293f5b5
CI=true
FC_URL=https://d22crk9l67sk4m.cloudfront.net

Empty Environment Variables - Not Supported

An empty environment variable is not supported. If you set an environment variable to an empty string, it will not validate in the dashboard, and you will be unable to save your changes.

Setting an environment variable to an empty string in your flightcontrol.json file is also not supported.

Excluded Environment Variables

Flightcontrol does not set the following environment variables:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY

We recommend not setting these environment variables yourself, either. If you need to configure AWS access control for your application, consider using an IAM role instead.

Config with Dashboard Custom Domains