Skip to main content
Version: Firesquid

Deploy a Squid

This section goes through deploying a squid to Aquarium -- a cloud API service provided by Subsquid. The following steps are performed by the Aquarium deployment service under the hood:

  • Checkout the squid from a remote URL
  • Build Docker images for the substrate-processor and the API server -- same as when built locally
  • Set up a Postgres database
  • Set the DB_XXX variables and start containers for the squid processor and the squid API server
  • Wait until the squid processor Prometheus metrics are available and the squid API server is online

0. Install Squid CLI

First, install the latest version of Subsquid CLI. The recommended way for macOS and Linux is to use Homebrew:

brew tap subsquid/cli
brew install sqd

Otherwise, install as a global npm package:

npm i -g @subsquid/cli@latest

and check the version with

sqd --version

Navigate to the squid folder and make sure you have the subsquid packages updated. Use the following templates as a reference:

Note, that the local .env file is ignored by Aquarium. The environment variables DB_NAME, DB_PASS, DB_PORT are automatically set by Aquarium. The support for user-defined environment variables and secrets is currently in private beta and will be available soon.

1. Obtain an Aquarium deployment key

Sign in to Aquarium, and obtain (or refresh) the deployment key on the account page by clicking at the profile picture at the bottom:

Aquarium homepage

2. Authenticate Squid CLI

Open a terminal window and run

sqd auth -k <DEPLOYMENT_KEY>

3. Create a new squid project in Aquarium

sqd squid create my-new-squid

Once the squid project is created, it will appear in My Squids Aquarium section and can also be inspected with

sqd squid ls

The command has optional attributes --description, --logo, --website to populate the corresponding fields. One can edit them later in Aquarium.

4. Release the kraken a squid version


If there are other deployed squid versions, consider updating the existing versions instead of releasing a new one.

Every instance of a squid API is identified by the squid project name and the version name, with a shortcut <squid name>@<version name>. A version name can be any alphanumeric string. One can also add a description to a squid version either with the --description flag or in Aquarium.

Option 1. Auto-detect the remote URL

Before releasing, make sure that local changes are committed and pushed to a remote git repo. Let's release my-new-squid@v0 version:

sqd squid release my-new-squid@v0

If there are multiple remotes for your local repo, it will prompt which git remote to choose.

Option 2. Explicitly set the source URL

It is also possible to release a squid from a remote repo using a full git link with the --source option. Note that a fully qualified git URL is either of the form https://my-git-repo.git#my-branch or https://my-git-repo.git#<commit-hash>. We recommend using fully qualified git URLs with a commit hash, like below:

sqd squid release my-new-squid@v0 --source

To deploy a squid from a private repo create a GitHub access token and provide the source URL in the form

sqd squid release my-new-squid@v0 --source https://<token><username>/<your-private-repo>.git#<branch> -v

Once the squid is deployed, the token can be deleted.

Both options will provide deployment logs.


For additional logs to troubleshoot deploy or update issues, set API_DEBUG env variable to true:

API_DEBUG=true sqd squid release my-new-squid@v0

5. Monitor Squid logs

Once the squid is deployed, the GraphQL endpoint is available straight away. Normally one should wait until the squid has processed all historical blocks and is fully in sync.

To inspect the squid logs run

sqd squid logs my-new-squid@v0 -f 

or navigate to the squid page in Aquarium.

What's next?