A newer release of the API3 Technical documentation is available.

📂 Reference > Packages

# Deployer

Table of Contents

The airnode-deployer (opens new window) package is used primarily by the Docker Images. This CLI tool provides the underlying commands used by the Docker images when deploying an Airnode.

Deploying an Airnode

API providers are strongly encouraged to use the Docker Images when deploying an Airnode and not the deployer CLI commands.

# Usage

The deployer's commands can be run using npx (opens new window), installing a global npm package or by manually building the airnode-deployer package. Using npx is the simplest method to interact with the deployer manually if you do not wish to use the Docker images.

# Using npx

The airnode-deployer package can be run as an npm package using npx. This allows you to run deployer commands without installing the deployer npm package or having to manually build the airnode-deployer package yourself.

npx @api3/airnode-deployer deploy --config config/config.json --secrets config/secrets.env --receipt config/receipt.json --logs config/logs/

# Global Package

The airnode-deployer package can be installed globally with yarn or npm. If installed using yarn make sure yarn bin is added to PATH.

yarn global add @api3/airnode-deployer
# OR
npm install @api3/airnode-deployer -g
# Executing the deployer.
airnode-deployer deploy --config config/config.json --secrets config/secrets.env --receipt config/receipt.json --logs config/logs/

1
2
3
4
5
6

# Commands

# Airnode Deployment

When creating or updating an Airnode the config.json and secrets.env files are needed. You can use the provided example config.json (opens new window) and secrets.env (opens new window) templates to get started quickly, but you will need to edit these with your own API details and secrets.

Warning about simultaneous deployments

Avoid running multiple deployments simultaneously as doing so might result in a broken deployment. If this occurs, the standard removal approach may not succeed and Manual Removal may be required.

Make sure config.json and secrets.env are available in the path for the --configuration argument.

# deploy

When executed, the deploy command defaults to creating a receipt.json file in the config/ directory, although a different path can be specified using the path and name with the --receipt argument. The receipt contains metadata about the deployment and can be used to remove the Airnode.

By default the deployer will save logs into the config/logs/ directory, but this can be changed with the --logs argument.

If the deployment isn't successful, the command will try to automatically remove deployed resources. You can disable this by running the deploy command with a --no-auto-remove argument.

# Deploys an Airnode instance using the `config.json` and `secrets.env` files.
# This can be used for a new deployment or to update an existing deployment.
Options:
      --version                          Show version number                                                   [boolean]
      --debug                            Run in debug mode                                    [boolean] [default: false]
      --help                             Show help                                                             [boolean]
  -c, --configuration, --config, --conf  Path to configuration file             [string] [default: "config/config.json"]
  -s, --secrets                          Path to secrets file                   [string] [default: "config/secrets.env"]
  -r, --receipt                          Output path for receipt file          [string] [default: "config/receipt.json"]
  -l, --logs                             Output path for log files                    [string] [default: "config/logs/"]
      --auto-remove                      Enable automatic removal of deployed resources for failed deployments
                                                                                               [boolean] [default: true]
# Basic example
airnode-deployer deploy
# Advanced example
airnode-deployer deploy --config config/config.json --secrets config/secrets.env --receipt config/receipt.json --logs config/logs/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Listing Airnodes

Once you've already deployed one or more Airnode, you can list your currently deployed instances using the list command.

# list

By default, the deployer will attempt to list Airnode instances from all the supported cloud providers. You can use the --cloud-providers option to select just the cloud providers you want the deployer to list from.

# Lists deployed Airnode instances
Options:
      --version          Show version number                                                                   [boolean]
      --debug            Run in debug mode                                                    [boolean] [default: false]
      --help             Show help                                                                             [boolean]
  -c, --cloud-providers  Cloud providers to list Airnodes from  [array] [choices: "aws", "gcp"] [default: ["aws","gcp"]]
  -l, --logs             Output path for log files                                    [string] [default: "config/logs/"]
# Basic example
airnode-deployer list
# Advanced example with cloud provider selection
airnode-deployer list --cloud-providers gcp

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Fetching deployment information

You can use the info command to retrieve information about one of your deployments. The retrieved information include deployment's Airnode address, stage, Airnode version and the update history.

# info

# Displays info about deployed Airnode
Positionals:
  deployment-id  ID of the deployment to show info for (from 'list' command)                         [string] [required]
Options:
  --version    Show version number                                                                             [boolean]
  --debug      Run in debug mode                                                              [boolean] [default: false]
  --help       Show help                                                                                       [boolean]
  -l, --logs   Output path for log files                                              [string] [default: "config/logs/"]
# Example
airnode-deployer info aws2c6ef2b3

1
2
3
4
5
6
7
8
9
10
11
12
13

# Reverting to a previous version

In case you want to revert to one of the previous versions of your deployment, you can do so with the rollback command.

# rollback

# Deploy one of the previous Airnode deployment versions
Positionals:
  deployment-id  ID of the deployment to rollback (from 'list' command)                              [string] [required]
  version-id     ID of the deployment version to rollback to (from 'info' command)                   [string] [required]
Options:
      --version      Show version number                                                                       [boolean]
      --debug        Run in debug mode                                                        [boolean] [default: false]
      --help         Show help                                                                                 [boolean]
  -r, --receipt      Output path for receipt file                              [string] [default: "config/receipt.json"]
  -l, --logs         Output path for log files                                        [string] [default: "config/logs/"]
      --auto-remove  Enable automatic removal of deployed resources for failed deployments     [boolean] [default: true]
# Example
airnode-deployer rollback aws808e2a22 5bbcd317

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Fetching deployment files

During the Airnode deployment, your config.json and secrets.env are uploaded to the cloud provider of your choosing. You can use the fetch-files command to retrieve them.

# fetch-files

# Fetch deployment files for the deployed Airnode
Positionals:
  deployment-id  ID of the deployment to fetch files for (from 'list' command)                       [string] [required]
  version-id     ID of the deployment version to fetch files for (from 'info' command)                          [string]
Options:
      --version     Show version number                                                                        [boolean]
      --debug       Run in debug mode                                                         [boolean] [default: false]
      --help        Show help                                                                                  [boolean]
  -o, --output-dir  Where to store fetched files                                           [string] [default: "config/"]
  -l, --logs        Output path for log files                                         [string] [default: "config/logs/"]
# Example
airnode-deployer fetch-files aws2c6ef2b3

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Airnode Removal

An Airnode can be removed in two different ways:

Best: With remove, which uses the deployment ID found either in the deployment receipt file or via the list command.
Alternate: With remove-with-receipt, which uses the deployment receipt created when the Airnode was deployed.

# remove

# Removes a deployed Airnode instance
Positionals:
  deployment-id  ID of the deployment to remove (from 'list' command)                                [string] [required]
Options:
  --version     Show version number                                                                            [boolean]
  --debug       Run in debug mode                                                             [boolean] [default: false]
  --help        Show help                                                                                      [boolean]
  -l, --logs    Output path for log files                                             [string] [default: "config/logs/"]
# Example
airnode-deployer remove aws2c6ef2b3

1
2
3
4
5
6
7
8
9
10
11
12
13

# remove-with-receipt

# Removes a deployed Airnode instance.
Options:
      --version                Show version number                                                             [boolean]
      --debug                  Run in debug mode                                              [boolean] [default: false]
      --help                   Show help                                                                       [boolean]
  -r, --receipt                Path to receipt file                            [string] [default: "config/receipt.json"]
  -l, --logs                   Output path for log files                              [string] [default: "config/logs/"]
# Basic example
airnode-deployer remove-with-receipt
# Advanced example specifying the receipt file and logs location
airnode-deployer remove-with-receipt --receipt config/receipt.json --logs config/logs/

1
2
3
4
5
6
7
8
9
10
11
12
13
14

← ABI Validator →