Documentation
Production
Deploy

Deploy

You can deploy your Ponder app to any cloud environment that supports Node.js.

Railway

Railway's general-purpose cloud platform is a great starting point for most Ponder apps.

Log in to Railway

Connect your GitHub account, and make sure that your Ponder app has been pushed to remote.

Create a Ponder app service

From the Railway console:

  1. Click New Project → Deploy from GitHub repo and select your repo from the list
  2. Click Add variables, then add RPC URLs (e.g. PONDER_RPC_URL_1) and other environment variables
  3. Create a public domain. In Settings → Networking, click Generate Domain
  4. Update the start command. In Settings → Deploy, set the Custom Start Command to include the --schema option. This is required to enable zero-downtime deployments. Read more.
Start command
pnpm start --schema $RAILWAY_DEPLOYMENT_ID
  1. Set the healthcheck path and timeout. In Settings → Deploy, set the Healthcheck Path to /ready and the Healthcheck Timeout to 86400 seconds (1 day)

Monorepo users: Use the Root Directory and/or Start Command options to run ponder start at the Ponder project root, e.g. set the root directory to packages/ponder or set the start command to cd packages/ponder && pnpm start.

Create a Postgres database

From the new project dashboard:

  1. Click Create → Database → Add PostgreSQL
  2. Open the Variables tab for the Ponder app service, click New Variable → Add Reference → select DATABASE_URL and click Add

After a moment, the service running ponder start should redeploy successfully. Check the Build Logs and Deploy Logs tabs to debug any issues.

Self hosting

In general, hosting a Ponder app is similar to hosting a normal Node.js web server. This section describes the key Ponder-specific quirks to consider when self-hosting.

Database connection

Your app will run into performance issues if the roundtrip database latency exceeds ~20 milliseconds. This is common when using a database in different private network or cloud region.

In production, Ponder works best with a Postgres database in the same private network. Set the DATABASE_URL environment variable to the connection string of your Postgres database, or manually override the database.connectionString option in ponder.config.ts.

ponder.config.ts
import { createConfig } from "ponder";
 
export default createConfig({
  database: {
    kind: "postgres",
    connectionString: "postgres://user:password@mycloud.internal:5432/database",
  },
  // ... more config
});

Database schema

Each deployment must use a different database schema. Use the DATABASE_SCHEMA environment variable or the --schema CLI argument passed to ponder start to specify which database schema each deployment should use. Read more about database schema selection rules.

The best choice depends on your deployment strategy – here are a few common options.

  • Kubernetes pod name
  • Railway deployment ID
  • Git branch name or commit hash

Health checks & probes

Use the /health and /ready endpoints to configure health checks or probes.

  • /health: Returns an HTTP 200 response immediately after the process starts.
  • /ready: Returns an HTTP 200 response once indexing progress has reached realtime across all chains. During the historical backfill, the endpoint returns an HTTP 503 response.

Crash recovery

If a Ponder app running ponder start crashes and restarts using the same database schema, it will attempt to resume indexing where it left off. Read more about the instance lifecycle and crash recovery mechanism.

Advanced

Scale the HTTP server

If a ponder start instance receives a large volume of HTTP traffic (e.g. GraphQL requests), the HTTP server will contend with the indexing engine for CPU and memory resources. This can lead to degraded indexing performance and might ultimately crash the instance.

To solve this problem, you can use ponder serve to run additional instances of the HTTP server without the indexing engine. Here are a few things to keep in mind.

  • The ponder serve instance should use the same database schema as the ponder start instance that you'd like to scale.
  • If one ponder serve instance is not enough, you can safely run multiple replicas behind a proxy using an architecture like this.

Database maintenance

The ponder db CLI entrypoint offers a set of commands useful for observing and maintaining your database. Read more.

Direct SQLTransports