Deployment manifest

The deployment manifest is named squid.yaml by convention. The manifest defines how the squid should be built, customized and scaled during the deployment to Aquarium. It is used together with sqd deploy to deploy or update an existing squid version.

With the introduction of the deployment manifest the addons (postgres) and the API services (api) become optional. This allows flexible deployment configuration for analytic use-cases (e.g. transform and write to s3 or BigQuery).

Header

The manifest header defines the squid metadata

Field	Archive endpoint
manifestVersion	Only subsquid.io/v0.1 is currently supported
name	A globally unique squid name. Can only contain lowercase Latin letters (a-z) and a dash (-).
version	Squid version. Must be an integer. A squid deployment is canonically identified as ${name}@${version}.
description	(Optional) A short description of the squid

build:

Specifies the way the squid is built into a docker image. Only an empty build: section is supported, and the squid must adhere to the default folder structure.

In particular, the following files and folders must be present in the root folder of the squid:

• /db
• /src
• /assets
• schema.graphql
• tsconfig.json
• package-lock.json
• package.json

Under the hood, Aquarium builds a Docker image and runs a docker container for each service (api, processor, migrate) using the same image. See Troubleshooting for instructions on how to build and run the image locally.

All the squid services (api, processor, migrate) use the same container image but with different commands.

deploy:

The deploy section may define:

• addons Additional services deployed for the squid.
  • postgres Deploys a Postgres 14 instance and injects DB_NAME, DB_USER, DB_PASSWORD, DB_PORT env. variables to the squid services.
• secrets A list of secret names that must be provided by Aquarium. If any of the secrets is not defined, the deployment will fail
• processor The processor service of the squid.
  • cmd Required The command to be used by the container.
• api The API service of the squid.
  • cmd Required The command to be used by the container. In particular, for the GraphQL API service, provide here additional flags to define subscriptions or caching
• migrate: (Optional) The command to be run on squid init. If not defined, migrate is executed with the default command.
  • cmd (Optional) The command to be executed by the init container. Default: ['npx', 'squid-typorem-migration', 'apply'].

The migrate, processor and api services may additionally define

• env (Optional) An key-value list of environment vairables to be added to the container runtime

scale:

See the Scale the deployment section.

Examples

A minimal example of manifest is below:

squid.yaml

manifestVersion: subsquid.io/v0.1
name: sample-squid
version: 1
description: |-
  My sample squid  

build: 

deploy:
  addons:
    postgres: 
  processor:
    cmd: [ "node", "lib/processor" ] 
  api:
    cmd: [ "npx", "squid-graphql-server"]

An extended version:

squid.yaml

manifestVersion: subsquid.io/v0.1
name: sample-squid
version: 1
description: |-
  My advanced squid 

build: 

deploy:
  addons:
    postgres: 
  # the set of secrets that must be set and provided by Aquarium
  secrets:
    - ACALA_RPC_ENDPOINT
    - COINGECKO_API_KEY 
  migrate:
    env:
      FOO: 
        bar
    cmd: ["echo", "skip migrations!"]
  processor:
    # additional env variables
    env:
      SQD_DEBUG: 
        sqd:mapping
    cmd: [ "node", "lib/processor" ] 
  api:
    env:
      SQD_DEBUG: 
        '*'
    # custom run command for the GraphQL server
    cmd: [ "npx", "squid-graphql-server", "--subscriptions", "--max-root-fields", "10", "--sql-statement-timeout", "1000" ] 

scale:
  addons:
     postgres:
         storage: 100G
         profile: medium
  processor:
     profile: medium
  api:
     profile: large
     # load-balance three replicas
     replicas: 3