Using the Flightcontrol.json Configuration File

Flightcontrol supports two ways to configure your project:

• Dashboard
• Infrastructure as Code (IaC)

In this section of the docs, we’ll cover how to configure your project using Infrastructure as Code (IaC) with the flightcontrol.json file. If you would like to use the dashboard instead, please see Configuring with the Dashboard.

Flightcontrol supports both configuration options, and it is possible to switch between them by asking Flightcontrol support to migrate your project.

Understanding the flightcontrol.json file

Using a flightcontrol.json file allows you to version control your project’s configuration. This makes it easy to collaborate with your team using pull requests and keep track of changes to your project’s configuration over time.

We recommend placing the flightcontrol.json file in the root of your project, but you can also place it in a subdirectory if you are using a monorepo.

If you would like to have multiple configuration files in one Git repo, that is also possible. When you create your Flightcontrol project, you can choose which configuration file to use - for instance, flightcontrol-web-api.json.

Example flightcontrol.json files

We have collected a set of Flightcontrol configuration files that you can use as a starting point for your project.

You’ll find examples for many different types of projects, including:

• Next.js
• Vite
• Remix
• Docker

You can use these examples as a starting point for your project, or you can use them as a reference to see how to configure a specific type of project. Want more examples? Let us know, and we’ll add them for you!

Simplify Large Config by Using CUE Instead of JSON

Flightcontrol also supports using CUE lang as an alternative to JSON for your configuration. It unlocks the ability to reduce duplication through composition.

To use CUE, simply create a flightcontrol.cue file instead of flightcontrol.json. The configuration structure remains the same, but you get all the benefits of CUE’s features.

For a detailed guide on using CUE with Flightcontrol, including examples of how to share service configurations and reduce duplication, see our Using CUE with Flightcontrol guide.

Configuration File Specification

We recommend using our JSON schema for autocompletion: https://app.flightcontrol.dev/schema.json - in combination with an editor that autocompletes JSON (such as Visual Studio Code).

{
  "$schema": "https://app.flightcontrol.dev/schema.json"
}

Each flightcontrol.json file corresponds to a single Flightcontrol project (as shown in the Flightcontrol dashboard). Each project in Flightcontrol can have one or more environments.

A Flightcontrol environment is typically something like production or staging. Each of those usually contains multiple services, such as:

• Web frontend
• API backend
• Database
• Worker

Let’s take a look at how to configure your Flightcontrol project using the flightcontrol.json file.

Top level Project options

The following properties are available at the top level of the flightcontrol.json file:

environments: Environment[]

• Each Flightcontrol project can have one or more environments.
• Typically you’ll have a production environment and a staging environment.

envVariables: EnvVariables

• Environment variables configured at the top level of the file for the project will be automatically inherited by all environments and services in the file.
• You can override a specific environment variable inside any environment or service

See the Environment Variables page for the details of how to set these up.

Environment - Contains one or more services

Each environment contains one or more services. An environment is typically something similar to production or staging.

Flightcontrol also supports preview environments. To learn more about preview environments, see Preview Environments.

id: string

• Example: "id": "production"
• This is a string id that you create. We use it on each git push to match your config to your existing environment in AWS
• This should never be changed

name: string

• Example: "name": "Production"
• This is the name we use to display your environment in the Flightcontrol web dashboard

region: string

• Example: "region": "us-west-2"
• Supported values: any valid aws region
• This is the AWS region that all your services within this environment will be located
• Typically you want this to be close to your users.

source: object

• branch: string

  • Example: "source": {"branch": "main"}
  • The GitHub branch you want deployed to this environment.
  • Every git push to this branch will be automatically deployed
  • If you want to deploy manually, you can change the trigger to "manual" (see below)

• trigger: string

  • Example: "trigger": "manual"
  • Supported values: "manual", "push"
  • Optional, defaults to "push"
  • Leaving the trigger as "push" will result in an automatic deployment of any git push to the branch. Changing the trigger to "manual" will prevent automatic deployments and require manually deploying the environment with one of the deployment options in the dashboard :

• pr: true | undefined

  • Optional, for configuring Preview Environments

• filter.toBranches: string[] | undefined

  • Optional, for configuring Preview Environments
  • Example: "toBranches": ["main"]
    • Supports globs. We use micromatch
  • If set, only pull or merge requests to the specified branch(es) will be deployed as preview environments. If omitted, all to branches will pass the filter.

• filter.fromBranches: string[] | undefined

  • Optional, for configuring Preview Environments
  • Example: "fromBranches": ["feature/**"]
    • Supports globs. We use micromatch
  • If set, only pull or merge requests from the specified branch(es) will be deployed as preview environments. If omitted, all from branches will pass the filter.

• filter.labels: string[] | undefined

  • Optional, for configuring Preview Environments
  • Example: "labels": ["deploy-preview"]
  • If set, only pull or merge requests with at least one of the specified labels will be deployed. It will be deployed when the label is added, whether that’s during PR creation or some time after the PR is opened.

• filter.watchPaths?: string[] | undefined

  • Example: "watchPaths": ["apps/backend/**"]
  • Optional, for configuring Preview Environments
  • If set, only pull or merge requests with a file change since the last successful deploy that matches the given glob pattern(s) will be deployed.
  • Uses glob patterns

vpc: object

• This allows you to connect this environment to an existing VPC instead of creating a new one
• Caveat: This only works with new Environment deployments, if you have an existing environment deployed already, we cannot change the VPC, you will need to deploy a brand new environment, route your application traffic, then delete the old environment.
• Make sure you set this environment’s region to match the region of your VPC
• id: string
  • Example: "id": "vpc-1234"
  • Your VPC ID (not the VPC name)
  • Make sure to use a VPC in the region you defined
• cidr: string
  • Example: "cidr": "10.10.1.0/24"
  • Optional: If you have a single CIDR attached to the VPC, you do not need to define a CIDR, as Flightcontrol will automatically use the default CIDR.
  • If the VPC has multiple CIDR attached, you can select the CIDR you want to use to deploy the application, using this parameter.
• private: boolean
  • Example: "private": true
  • Optional, defaults to false
  • Provision NAT gateway if one doesn’t exist
  • Most users don’t need to worry about this setting. We will automatically provision a NAT gateway if any of your services require it.

envVariables: EnvVariables

• Environment variables configured at the environment level will be automatically inherited by all the services within this environment
• You can override a specific environment variable inside a specific service
• Documentation for Configuring Environment Variables

services: Service[]

• These services will be deployed and updated together.
• These services exist inside the same VPC (each environment has it’s own VPC)

Service Configuration

The following properties are common for all service types:

id: string

• Example: "id": "production-web"
• This is a string id that you create. We use it on each git push to match your config to your existing service in AWS
• This cannot be changed. If you change it, it will create a new service.

name: string

• Example: "name": "Production Web"
• This is the name we use to display your service in the Flightcontrol web dashboard

buildType: 'nixpacks' | 'nodejs' | 'docker' | 'fromService' | 'fromRepository'

• Example: "buildType": "nixpacks"
• Default: 'nodejs' (deprecated)
• nixpacks:
  • If you’re using a monorepo, you’ll likely want to pay attention to basePath and read the guidance on monorepos
  • Deploy almost any language without writing a Dockerfile!
  • Docs: https://nixpacks.com/
  • You can customize native packages and such with nixpacks.toml
• nodejs:
  • Behind the scenes, this uses a Flightcontrol provided Dockerfile.
  • This is deprecated in favor of Nixpacks
• docker:
  • Bring your own Dockerfile for full control
  • This is only supported for container based services like web and worker
• fromRepository:
  • Allows you to use a pre-built image from a repository
  • Requires you to create an image registry and add the containerImage parameter to your service config
  • This is only supported for container based services like web and worker
• fromService:
  • Used for single-tenant architectures where you want to build once but deploy to many services
  • Requires adding a fromService: [serviceId] parameter to your service config
  • This is only supported for container based services like web and worker

CI

ci: object

• Determines which build runner to use

• Applicable only for services with a build step

• The recommended builder is ec2, which is the builder built by Flightcontrol

  type: 'ec2' | 'codebuild'

  Optional ec2 only properties with defaults:

  • instanceSize: string (default to 16 vCPU and 32 GB of memory) - The instance type to use for the build
  • instanceStorage: number (default: 30) - Size in GB of the volume attached to the instance
  • storageThroughput: number (default: 125) - The provisioned throughput of the storage in MB/s, only valid for GP3 storage
  • storageIops: number (default: 3000) - The amount of IOPS provisioned to the storage
  • storageType: 'gp2' | 'gp3' | 'io1' | 'io2' (default: 'gp3') - The attached EBS storage volume type

Examples:

• "ci": { "type": "ec2", "instanceStorage": 80 }
• "ci": { "type": "codebuild" }

Pre-deploy Command

preDeployCommand: Array<string>

• Example: "preDeployCommand": ["bundle", "exec", "rails", "db:prepare"],
• Optional
• A command that runs after successful build and before starting the deploy (more information).
• If configured, a dedicated container is started to run the command and shuts down on completion.
• The command must be split into array parts because this is used to override the Docker CMD, and if passed as a single string runc counts it as a single command instead of a command + arguments.
• Note: using this for database migrations will add 2-3 minutes to your deploy time because of the time it takes this temporary container to boot and run.

Post-deploy Command

postDeployCommand: Array<string>

• Example: "postDeployCommand": ["node", "script.js"]
• Optional
• A command that runs after successful deploy (more information).
• If configured, a dedicated container is started to run the command and shuts down on completion.
• The command must be split into array parts because this is used to override the Docker CMD, and if passed as a single string runc counts it as a single command instead of a command + arguments.

Watch Paths

watchPaths?: string[]

• Optional array of glob patterns
• This service will only build & deploy if there is a file change since the last successful deploy that matches the given glob pattern(s)
• Example: "watchPaths": ["apps/frontend/**"]
• Uses glob patterns

Service Level Environment Variables

envVariables: EnvVariables

• See the Environment Variables page for full documentation

Service-Specific Configuration

Besides the common properties above, each service will have specific properties, specified on the following pages:

• Web
• Private Web
• Worker
• Scheduler
• Lambda Function
• Static Site
• S3 Bucket
• Database
• Redis