Using Flightcontrol.json to Configure your Project

For many projects, using your own flightcontrol.json file is the best way to configure your project. This allows you to version control your project configuration.

You will need to create a compatible JSON file and add it to the path you indicated in the configuration - this is typically going to be flightcontrol.json in the root of the project. If you are using a monorepo, you can add multiple flightcontrol.json files in different directories.

It can be useful to use our JSON schema for autocompletion: https://app.flightcontrol.dev/schema.json (opens in a new tab).

• Each git repo can have multiple flightcontrol.json files
• Each flightcontrol.json corresponds to a single Project (as shown in the Flightcontrol dashboard)
• Each Project can have multiple Environment's
• Each Environment can have multiple Service's

Example flightcontrol.json files

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

Top level Project Options

environments: Environment[]

• One or more environments in this project.
• Typically you’ll have a production environment and a staging environment

envVariables: EnvVariables

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

EnvVariables

Environment variables can be configured two ways

1. In the Flightcontrol dashboard under an environment’s settings

2. Via flightcontrol.json (values defined here will override ones set in the dashboard)

   • object, with one or more of the following types

     • Static

       • Format: "NAME": "<value>"
       • Example: "APP_ENV": "production"
       • Static, hard coded value in flightcontrol.json

     • From another service:

       • Format: "NAME": {"fromService": {"id": "<serviceId>", value: "<value>"}}

       • Example: "NAME": {"fromService": {"id": "db", value: "dbConnectionString"}}

       • Supported values for type: "rds" services: dbConnectionString, username, password, host, port In preview environment we also include dbName and dbEngine.

       • Supported values for type: "fargate" and type: "static" services:

         host will include the service URL without protocol: www.example.com

         origin will include the service URL with protocol: https://www.example.com

     • From Parameter Store:

       • Format: "NAME": {"fromParameterStore": "<parameterStoreItemName>"}
       • Example: "STRIPE_API_KEY": {"fromParameterStore": "ACME_STRIPE_API_KEY"}
       • Securely retrieve the value from AWS Parameter Store (opens in a new tab). Parameter Store is a free AWS service for securely storing secrets.
       • Important: Your parameter store item must be in the same region as your service
       • Screenshot of parameter store

     • From Secrets Manager:

       • Format: "NAME": {"fromSecretsManager": "<arn:your-secret-arn>"}
       • Example: "STRIPE_API_KEY": {"fromSecretsManager": "arn:aws:secretsmanager:us-west-1:832786265645:secret:/stripe-y6uINZ"}
       • Securely retrieve the value from AWS Secrets Manager (opens in a new tab). Secrets Manager is a paid AWS service for securely storing secrets. It costs $0.40/secret/month

• We automatically provide you with the following environment variables:
  • CI=true
  • PORT=<your service.port value>
  • FORCE_COLOR=0
  • FC_URL=<current full url of the service>
  • FC_GIT_COMMIT_SHA=<git commit sha of the deployment>
  • FC_GIT_BRANCH=<git branch of the deployment>
  • FC_AWS_REGION=<aws region of the environment>

Environment

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 (opens in a new tab)
• 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
• trigger: string
  • Example: "trigger": "manual"
  • Supported values: "manual", "push"
  • Optional with default 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 in the hamburger menu in the environment show page:
• 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 (opens in a new tab)
  • 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 (opens in a new tab)
  • 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 (opens in a new tab)

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.

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 env variable inside a specific service

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

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/ (opens in a new tab)
  • You can customize native packages and such with nixpacks.toml (opens in a new tab)
• Node.js:
  • Behind the scenes, this uses a Flightcontrol provided Dockerfile.
  • This will be deprecated in favor of Nixpacks
• Docker:
  • Bring your own Dockerfile for full control
  • This is only supported for container based services like fargate and fargate-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 fargate and fargate-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 fargate and fargate-worker

watchPaths?: string[]

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

envVariables: EnvVariables

Service-Specific Configuration

Besides the common properties above, each service will have specific properties, specified below:

Web Server

type: 'fargate'

Private Server / Worker

type: 'fargate-worker'

Static Website

type: 'static'

Database

type: 'rds'

Redis

type: 'elasticache'