Self-Host Instructions

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

Want to avoid setup and maintenance?

Requirements

Docker
A thirdweb secret key from the API Keys page
PostgresDB (version 14+)
Redis (version 7.2.4+)

Running Engine locally

Start Postgres:


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

Start Redis:


docker run -p 6379:6379 -d redis:7.2.4

Start Engine server:


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 \
  -e REDIS_URL="redis://host.docker.internal:6379/0" \
  -p 3005:3005 \
  --pull=always \
  --cpus="0.5" \
  thirdweb/engine:latest

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_HTTPS`	Self-sign a certificate to serve API requests on HTTPS. Set to `true` if running Engine locally only. (Default: `false`)
`LOG_LEVEL`	Determines the logging severity level. Adjust for finer control over logged information. (Default: `debug`)
`PRUNE_TRANSACTIONS`	When `false`, Engine prevents the pruning/deletion of processed transaction data. (Default: `true`)
`ENABLE_KEYPAIR_AUTH`	Enables Keypair Authentication.
`REDIS_URL`	Redis connection string: `redis://[user:password@]host:port[/db-number]`

* Required

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.

Running Engine in production

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

Pin Engine Docker to a version to control when changes are introduced.
- latest may include major version changes which can introduce breaking changes.
Host Engine DB on any Postgres-compatible database.
- Remember to update POSTGRES_CONNECTION_URL.
- Examples: AWS RDS, Google Cloud SQL, Heroku, Supabase
- Minimum specs: 2 vCPU, 2 GB memory (AWS equivalent: t4g.small)
- Minimum version: 14
- Add the ?connection_limit=10 param to your POSTGRES_CONNECTION_URL to increase the connection limit.
Host Engine server on any 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.
Remove the ENABLE_HTTPS env var.

FAQ

Why is my Docker image unable to reach my Postgres database?

Here are common troubleshooting tips:

Ensure the Postgres DB is running in Docker. POSTGRES_CONNECTION_URL should be set to localhost (if in the same container) or host.docker.internal (if in a different container).
Ensure the Postgres DB connection URL and credentials are correct.
Ensure the database name exists on the Postgres DB.

See 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:


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