Deployment Guide

This guide shows you how to deploy a production-ready indexer (“squid”) to SQD Cloud.

Prerequisites

Before you begin, ensure you have:

Docker - Download here (for local development)
Squid CLI - Installation guide
Working squid - A locally tested indexer ready for deployment

Prepare the squid for deployment

Ensure your squid is ready for production deployment:

Test locally - Verify the squid works as expected in your local environment
Performance check - Ensure no major performance issues. See Best practices for guidance
Update configuration - Update the squid.yaml file with correct values for your use case
Set up secrets - Configure SQD Cloud secrets if your squid requires sensitive data

Production deployments should be thoroughly tested locally to avoid issues in the cloud environment.

Your squid is tested and ready for cloud deployment.

Create your SQD Cloud account:

Visit the SQD Cloud console
Click Create an account and fill in the required information
Or sign in with your GitHub or Google account

You’ll receive a confirmation email to verify your account.

Create a professional organization

Set up your organization for production use:

Create a new organization in SQD Cloud
Upgrade to professional by attaching a valid credit card in the “Billing” tab

You can skip this step, but you’ll only be able to deploy to your account’s playground. Playground squids are trial/development solutions with limited functionality and are not suitable for production use.

Your professional organization is ready for production deployments.

Edit the squid.yaml file

Configure your deployment manifest for SQD Cloud:

Basic Configuration

First, set squid name, description, and other metadata in the header section of the squid.yaml file.If necessary, configure your build options next. If the defaults (NodeJS v20 and npm for package manager) work for you, just create an empty build section.Finally, edit the deploy section to specify the deployment options.Example configuration:

squid.yaml

manifest_version: subsquid.io/v0.1
name: sample-squid

build:

deploy:
  processor:
    cmd: ["sqd", "process:prod"]
  api:
    cmd: ["sqd", "serve:prod"]

The processor and api commands are commands.json-based. This is optional but recommended for complex deployments.

Configure Addons

SQD Cloud addons enable extra services for your squid. Enable them in the deploy.addons section based on your requirements.

RPC Addon

Use the rpc addon for real-time data access:Steps to configure:

Open the RPC endpoints tab in the SQD Cloud sidebar
Copy the URL of your chosen endpoint
Add it to your .env file:

.env

RPC_ARBITRUM_ONE_HTTP=<endpoint-url>

Enable the addon in your squid.yaml:

squid.yaml

deploy:
  addons:
    rpc:
      - arbitrum-one.http

Configure your processor to use the RPC endpoint:

src/main.ts

import { assertNotNull } from "@subsquid/util-internal";

export const processor = new EvmBatchProcessor().setRpcEndpoint(
  assertNotNull(
    process.env.RPC_ARBITRUM_ONE_HTTP,
    "Required env variable RPC_ARBITRUM_ONE_HTTP is missing"
  )
);
// ...the rest of the processor configuration

The RPC addon provides reliable access to blockchain nodes for real-time data queries and state access.

PostgreSQL Addon

For squids that write their data to PostgreSQL, use the postgres addon:Basic configuration:

squid.yaml

deploy:
  addons:
    postgres:

Production scaling:

Always configure the scale section for the addon when deploying to production.

squid.yaml

scale:
  addons:
    postgres:
      storage: 100G
      profile: medium

PostgreSQL addon automatically provides database connection credentials through environment variables.

Hasura Addon

If your squid uses a dedicated Hasura instance, configure the hasura addon to provision it.

squid.yaml

deploy:
  addons:
    hasura:

Use Hasura when you need advanced GraphQL features like subscriptions, permissions, or complex query capabilities beyond the default OpenReader.

Scale Settings

Configure resource allocation for your squid components to ensure optimal performance.

API Service Configuration

Squids include a GraphQL service by default. You can enable or disable it by adding or removing the deploy.api section. Use the scale.api section to configure resources and replicas.

squid.yaml

deploy:
  api:
    cmd: ["sqd", "serve:prod"]
scale:
  api:
    profile: large
    # load-balance across three replicas
    replicas: 3

This configuration works with OpenReader (default) and PostGraphile. For Hasura, see the hasura addon documentation.

Processor Configuration

Configure the indexer processor resources based on your data processing requirements. See the processor scale reference for all available options.

squid.yaml

scale:
  processor:
    profile: medium

Choose a processor profile based on your indexing workload. Start with small for testing and scale up to medium or large for production workloads.

Dedicated Deployment

Dedicated deployment ensures your squid runs on dedicated resources for optimal performance and reliability. This is the default for professional organizations.

If your squid.yaml contains dedicated: false (from previous playground deployments), you must remove it or set it to true for production use. Collocated squids are not recommended for production environments.

To explicitly enable dedicated deployment:

squid.yaml

scale:
  dedicated: true

Dedicated deployment is enabled by default for all professional organization deployments.

Complete Configuration Example

Here’s a complete squid.yaml file with all deployment options configured:

squid.yaml

manifest_version: subsquid.io/v0.1
name: sample-squid

build:

deploy:
  addons:
    postgres:
    rpc:
      - arbitrum-one.http
  processor:
    cmd: ["sqd", "process:prod"]
  api:
    cmd: ["sqd", "serve:prod"]

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

Your squid.yaml is now configured for production deployment on SQD Cloud.

For detailed information on all available deployment options, see the deployment manifest reference.

Set any required secrets

If your squid uses any sensitive data such as a private URL or an access key, store it securely in a SQD Cloud secret.You can add secrets using either method:

Via SQD Cloud Console: Navigate to the Secrets tab in the sidebar and add your values
Via CLI: Use the sqd secrets command

Never commit secrets or API keys directly to your code repository. Always use SQD Cloud secrets for sensitive data.

Deploy the squid

Deploy your squid to SQD Cloud using the Squid CLI:

Open the Squids tab in the SQD Cloud sidebar
Click the Deploy a squid button
Follow the prompts to install the Squid CLI if needed
Set up your authentication key as shown in the console
Ensure your squid name matches the one in squid.yaml

Run the deployment command from your project root:

sqd deploy .

The deployment process will build your squid, upload it to SQD Cloud, and start the processor and API services according to your squid.yaml configuration.

Once deployed, your squid will appear in the Squids list with status information.

Monitor the squid

After deployment, monitor your squid’s performance and health through the SQD Cloud dashboard:What you can monitor:

Logs: View real-time logs from your processor and API services
Metrics: Track memory usage, CPU usage, and processing speed
Status: Check the health status of your squid components
Sync progress: Monitor blockchain indexing progress

To access monitoring:

Navigate to the Squids tab in the SQD Cloud sidebar
Select your deployed squid from the list
View the monitoring dashboard with metrics and logs

Visit the logging documentation for tips on emitting structured logs and using log filters effectively.

Your squid is now running and processing blockchain data on SQD Cloud.

Use the squid

Your deployed squid is now accessible and ready to use:Access your data:

Database access: If your squid uses PostgreSQL, access credentials are available in the DB access tab of your squid’s card
GraphQL API: Access your squid’s GraphQL endpoint from the deployment details
Direct queries: Connect to your database using the provided credentials

Production workflows:Squid deployments use slots and tags for flexible deployment management. This enables:

Zero downtime updates: Deploy new versions without interrupting service
Version management: Maintain multiple versions simultaneously
Traffic routing: Control which deployment serves production traffic

We strongly recommend using the zero downtime update workflow for all production squids.

What’s Next?

Continue optimizing and managing your deployment:

Pricing

Understand SQD Cloud costs and resource allocation

Organizations

Manage teams and billing settings

Slots and Tags

Master zero downtime deployments

Squid CLI

Learn CLI commands for deployment management

Managed

Self-Hosting

Deployment Guide