Docs

Self-Host Instructions

Self-host Engine on your own infrastructure for free and manage your self-hosted Engine from the thirdweb dashboard.

Requirements

Development

Bring your own Postgres-compatible database, or run Postgres locally:

docker run -p 5432:5432 -e POSTGRES_PASSWORD=postgres -d postgres

Run Engine locally:

docker run \
  -e ENCRYPTION_PASSWORD="<encryption_password>" \
  -e THIRDWEB_API_SECRET_KEY="<thirdweb_secret_key>" \
  -e ADMIN_WALLET_ADDRESS="<admin_wallet_address>" \
  -e POSTGRES_CONNECTION_URL="postgresql://postgres:postgres@host.docker.internal:5432/postgres?sslmode=disable" \
  -e ENABLE_HTTPS=true \
  -p 3005:3005 \
  --pull=always \
  --cpus="0.5" \
  thirdweb/engine:latest

Note: Replace POSTGRES_CONNECTION_URL with your database URL.

Environment variables

Variable (* = Required)Description
ENCRYPTION_PASSWORD*Provide a string to encrypt sensitive data stored in DB. Do not change this value or encrypted data will be inaccessible.
THIRDWEB_API_SECRET_KEY*A thirdweb secret key created on the API Keys page.
ADMIN_WALLET_ADDRESS*The wallet address that will configure Engine from the thirdweb dashboard. You will be able to add other admins later.
POSTGRES_CONNECTION_URL*Postgres connection string: postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]
ENABLE_HTTPSSelf-sign a certificate to serve API requests on HTTPS. Set to true if running Engine locally only. (Default: false)
LOG_LEVELDetermines the logging severity level. Adjust for finer control over logged information. (Default: debug)
PRUNE_TRANSACTIONSWhen false, Engine prevents the pruning/deletion of processed transaction data. (Default: true)
ENABLE_KEYPAIR_AUTHEnables Keypair Authentication.

Your server is running when this log line appears:

Listening on https://localhost:3005. Manage your Engine from https://thirdweb.com/dashboard/engine.

Manage Engine from the dashboard

To manage your Engine instance from the dashboard:

  • Navigate to https://localhost:3005/json

    • The "Your connection is not private" page will appear.
    • Select Show advanced and select Proceed to localhost (unsafe) to render the JSON file.
    • This one-time step allows your browser to connect to your local Engine instance.

  • Navigate to the Engine dashboard page.

  • Sign in with the <admin_wallet_address> wallet.

  • Select Import

  • Add your publicly accessible Engine URL.

    • If Engine is running locally, provide the URL https://localhost:3005.

Production

See the Production Checklist for best practices using Engine in a production environment.

Self-hosting recommendations

  • Do not set the environment variable ENABLE_HTTPS=true.
  • Host Engine Docker on a cloud provider.
    • Minimum specs: 1 vCPU, 2 GB memory (AWS equivalent: t2.small)
    • Auto-scale the instance count to increase inbound throughput and queuing capacity.
  • Host Postgres DB on a cloud provider.
    • Examples: AWS RDS, Google Cloud SQL, Heroku, Supabase
    • Minimum specs: 2 vCPU, 2 GB memory (AWS equivalent: t4g.small)
    • Set the connection_limit parameter within your POSTGRES_CONNECTION_URL environment variable to 10.

FAQ

How do I filter logs in Engine?

Configure log verbosity via the LOG_LEVEL environment variable. The severity levels ordered from highest to lowest are:

  • fatal : Terminates the program due to critical errors.
  • error : Highlights serious issues needing immediate action.
  • warn : Suggests caution due to potential issues.
  • info : Shares routine operational insights.
  • debug : Provides detailed debugging information.
  • trace : Offers in-depth tracing details.

Engine by default captures logs at debug severity and higher. Setting LOG_LEVEL to error limits logging to only error and fatal severities.

LOG_LEVEL="error"

How to prevent SIGSEGV errors with the Engine docker image?

Ensure the Engine docker image's stability by allocating a minimum of 0.5 vCPU & 1 GB memory to the container, mitigating SIGSEGV (Segmentation Fault) errors due to inadequate resources or memory access issues.

Engine recommends a minimum DB connections limit of 8 PER HOST. Please set the connection_limit parameter within your POSTGRES_CONNECTION_URL environment variable, to allow a connection limit between (8, # conns supported by your DB / # hosts). In practice, 10-20 is a suitable connection limit.

DB Error:

ERROR: [Worker] Failed to update mined transactions - Transaction API error: Unable to start a transaction in the given time.
ERROR: [Worker] Failed to update receipts - Transaction API error: Unable to start a transaction in the given time.
ERROR: [Worker] Failed to process batch of transactions -
Invalid `prisma.configuration.findUnique()` invocation in
/app/dist/src/db/configuration/getConfiguration.ts:164:43
 
  161 };
  162
  163 export const getConfiguration = async (): Promise<Config> => {
  164   let config = await prisma.configuration.findUnique(
Timed out fetching a new connection from the connection pool. More info: http://pris.ly/d/connection-pool (Current connection pool timeout: 10, connection limit: 3)

Example configuration:

POSTGRES_CONNECTION_URL=postgres://postgres:postgres@localhost:5432/postgres?connection_limit=10