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!

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
  • Determines whether Flightcontrol deploys the application into the private subnets of the VPC.

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 should never be changed

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'

• 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

• Node.js:

  • 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:

  storageType?: string

  • Example: storageType: "io2"
  • Optional with default: gp3
  • This is the attached EBS storage volume type, supported values gp2, gp3, io1 and io2.
  • See the available options in AWS’s documentation

  instanceSize?: string

  • Example: instanceSize: "c7g.16xlarge"
  • Optional with default: *.4xlarge
  • This is the AWS instance type, which will determine the size of instance.
  • See the available types in AWS’s documentation

  instanceStorage?: number

  • Example: instanceStorage: 100
  • Optional with default: 30
  • Size in GB of the volume attached to the instance
  • Range: 1 - 2000

  storageIops?: number

  • Example: storageIops: 4000
  • Optional with default: 3000
  • The amount of IOPS provisioned to the storage
  • Range depends on storage type and the selected storage capacity

  storageThroughput?: number

  • Example: storageThroughput: 500
  • Optional with default: 125
  • The provisioned throughput of the storage, size in MB/s, only valid for GP3 storage
  • Range depends on storage type and the selected storage capacity

Examples:

• "ci": { "type": "ec2", instanceSize: "c7g.16xlarge", "instanceStorage": 250 }
• "ci": { "type": "codebuild" }

Watch Paths

watchPaths?: string[]

• 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/**"]
• Optional with no default
• Uses glob patterns

envVariables: EnvVariables

Service-Specific Configuration

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

• Web
• Worker
• Scheduler
• Static Site
• Database
• Redis