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 singleProject
(as shown in the Flightcontrol dashboard) - Each
Project
can have multipleEnvironment
's - Each
Environment
can have multipleService
's
💡 Tip: For autocompletion, you'll need to add $schema
as a top-level property with our schema
as the value: "https://app.flightcontrol.dev/schema.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.
Top level Project
Options
environments: Environment[]
- One or more environments in this project.
- Typically you’ll have a
production
environment and astaging
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
-
In the Flightcontrol dashboard under an environment’s settings
-
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
- Format:
-
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 includedbName
anddbEngine
. -
Supported values for
type: "fargate"
andtype: "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
- Format:
-
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
- Format:
-
-
- 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
- Example:
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:
- Example:
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)
- Example:
💡 Note: The optional filters work with an AND
logic. If both filters are enabled, it will only
deploy a PR that matches both the target branch(es) (toBranches
) and one of the labels
configured (labels
).
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
- Example:
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.
- Example:
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)
- If you're using a monorepo, you'll likely want to pay attention to
- 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
andfargate-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
andfargate-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
andfargate-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'
Fargate service options
Private Server / Worker
type: 'fargate-worker'
Fargate worker service options
Static Website
type: 'static'
Static service options
Database
type: 'rds'
RDS service options
Redis
type: 'elasticache'
Elasticache service options