Self-Host Instructions

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

• Docker
• A thirdweb secret key from your Team > Project > Settings page.
• PostgresDB (version 14+)
• Redis (version 7.2.4+)

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

* Required

Your server is running when this log line appears:

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

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.

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.

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.

• 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.

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"

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

If you have engine running on a server behind a reverse proxy, you can set the TRUST_PROXY environment variable to true to trust the X-Forwarded-For header. Reverse proxies like Nginx or Apache will add this header to the request with the original client IP address, and setting this variable will allow Engine to use the correct IP address for the IP Allowlist. For more details on IP Allowlisting, refer to the Security Features page.