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

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

Environment variables

VariableDescription
ENCRYPTION_PASSWORD*Provide a string to encrypt sensitive data stored in DB. Do not change this value or encrypted data will be inaccessible.
THIRDWEB_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)

* Required

Your server is running when this log line appears:

Server listening on: https://0.0.0.0:3005

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 Production Checklist for best practices using Engine in a production environment.