From c2d53a4c44b054653e27bef62f242707d75e5cea Mon Sep 17 00:00:00 2001 From: Phillip Ho Date: Mon, 6 Nov 2023 16:02:00 -0800 Subject: [PATCH] feat: add production checklist for engine --- docs/onboarding/17 Engine/0 Overview.mdx | 12 +++---- .../17 Engine/1 Getting Started.mdx | 34 ++++++------------- .../17 Engine/2 Production Checklist.mdx | 30 ++++++++++++++++ docs/onboarding/17 Engine/3 Security.mdx | 9 ----- 4 files changed, 46 insertions(+), 39 deletions(-) create mode 100644 docs/onboarding/17 Engine/2 Production Checklist.mdx diff --git a/docs/onboarding/17 Engine/0 Overview.mdx b/docs/onboarding/17 Engine/0 Overview.mdx index f56984e6d..d550a1045 100644 --- a/docs/onboarding/17 Engine/0 Overview.mdx +++ b/docs/onboarding/17 Engine/0 Overview.mdx @@ -7,7 +7,7 @@ import QuickstartCard from "@components/QuickstartCard"; Engine is a backend HTTP server that calls smart contracts using your managed backend wallets. -- Create & manage funded backend wallets to send blockchain transactions +- Create & manage funded backend wallets to send blockchain transactions via authenticated APIs. - Build scalable blockchain apps with transaction retries, wallet nonce management, and gas estimation. @@ -33,14 +33,14 @@ Engine is fully [open-sourced](https://github.com/thirdweb-dev/engine) and [self ## Features -- Manage & transact with backend walets - Create wallets backed - up locally or with AWS KMS / Google KMS. -- Interact with any contract on any EVM chain - Engine supports - all 1000+ EVM blockchains and private +- Managed backend wallets - Create company wallets backed up locally + or with AWS KMS / Google KMS. +- Any contract on any EVM chain - Engine supports contract calls + on all 1000+ EVM blockchains and private subnets. - High transaction throughput - Blockchain transactions are processed in parallel with nonce management, and stuck transactions are automatically retried. -- Deploy smart contracts - Deploy any +- Smart contracts - Deploy any published smart contract including tokens, NFTs, marketplaces, and smart accounts. - Account abstraction & smart wallets - Deploy and manage smart diff --git a/docs/onboarding/17 Engine/1 Getting Started.mdx b/docs/onboarding/17 Engine/1 Getting Started.mdx index dc0821a64..8574b143a 100644 --- a/docs/onboarding/17 Engine/1 Getting Started.mdx +++ b/docs/onboarding/17 Engine/1 Getting Started.mdx @@ -24,6 +24,7 @@ Run Engine locally: ```bash docker run \ + -e ENCRYPTION_PASSWORD="" \ -e THIRDWEB_API_SECRET_KEY="" \ -e ADMIN_WALLET_ADDRESS="" \ -e POSTGRES_CONNECTION_URL="postgresql://postgres:postgres@host.docker.internal:5432/postgres?sslmode=disable" \ @@ -36,14 +37,13 @@ docker run \ #### Environment variables -| Variable | Description | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `THIRDWEB_SECRET_KEY` | A thirdweb secret key created on the [API Keys page](https://thirdweb.com/dashboard/settings/api-keys). | -| `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`) | - -**\*** Required +| Variable | 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_SECRET_KEY` | A thirdweb secret key created on the [API Keys page](https://thirdweb.com/dashboard/settings/api-keys). | +| `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.
Optional, default: `false` | Your server is running when this log line appears: @@ -53,6 +53,8 @@ Server listening on: https://0.0.0.0:3005 ### Production +See [Production Checklist](/engine/production-checklist#cloud-hosting) for self-hosting best practices. + :::tip Looking for a managed solution? @@ -60,22 +62,6 @@ Looking for a managed solution? ::: -- Deploy a cloud-hosted Postgres instance with [AWS RDS](https://aws.amazon.com/rds/postgresql) or [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres). -- Deploy a Engine to the cloud: - - ```bash - docker run \ - -e THIRDWEB_API_SECRET_KEY="" \ - -e ADMIN_WALLET_ADDRESS="" \ - -e POSTGRES_CONNECTION_URL="" \ - -p 3005:3005 \ - --pull=always \ - --cpus="0.5" \ - thirdweb/engine:latest - ``` - -- Minimum recommended specs: 1 vCPU, 2 GB memory - ## Use the dashboard ### Sign in diff --git a/docs/onboarding/17 Engine/2 Production Checklist.mdx b/docs/onboarding/17 Engine/2 Production Checklist.mdx new file mode 100644 index 000000000..f1019aeba --- /dev/null +++ b/docs/onboarding/17 Engine/2 Production Checklist.mdx @@ -0,0 +1,30 @@ +--- +slug: /engine/production-checklist +title: Production Checklist +--- + +Follow best practices when using Engine in a production environment. + +### Security + +- Do _not_ set the environment variable `ENABLE_HTTPS=true`. +- Do _not_ change `ENCRYPTION_PASSWORD` once it's set up. It is used to decrypt sensitive data stored encrypted in DB. +- Securely store access tokens and the thirdweb secret key. Rotate these credentials if they are compromised. +- Use labels to keep track of your wallets, admins, and access tokens. +- Use access token with expirations to grant time-bound access. +- Regularly review the admins list to remove inactive and former team members. + +### Cloud hosting + +- Host Engine Docker on a cloud provider. + - Minimum specs: 1 vCPU, 2 GB memory (AWS equivalent: t2.small) + - Autoscale the instance count to increase inbound throughput and queuing capacity. +- Host Postgres DB on a cloud provider. + - Examples: [AWS RDS](https://aws.amazon.com/rds/postgresql/), [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres), [Heroku](https://www.heroku.com/postgres), [Supabase](https://supabase.com/docs/guides/database/overview) + - Minimum specs: 2 vCPU, 2 GB memory (AWS equivalent: t4g.small) + +### Backend wallets + +- Recommended: Use a wallet backed by AWS KMS or Google KMS. Wallet access is always recoverable and private keys are never exposed. +- If using a local wallet: **back up the private key**. Engine cannot recover private keys if the encrypted stored data is lost or corrupted. +- Ensure your backend wallets have sufficient funds. Consider using [wallet webhooks](/engine/webhooks) to alert when your native coin balance is low. diff --git a/docs/onboarding/17 Engine/3 Security.mdx b/docs/onboarding/17 Engine/3 Security.mdx index 07a6a5cb7..db9d16146 100644 --- a/docs/onboarding/17 Engine/3 Security.mdx +++ b/docs/onboarding/17 Engine/3 Security.mdx @@ -3,15 +3,6 @@ slug: /engine/security title: Security --- -## Best practices - -Engine reconstructs signers for your backend wallets to sign and send transactions. Follow these best practices to secure access to your wallets and data: - -- Securely store **access tokens** and **thirdweb secret keys**. Rotate these credentials if they are compromised. -- Use **labels** to keep track of your wallets, admins, and access tokens. -- Use access token with expirations to grant time-bound access. -- Regularly review the **admins** list to remove inactive and former team members. - ## Data handling - Since Engine is self-hosted, you (the developer) maintain control over the server, database, logging, and observability.