How to Deploy a Self-hosted thirdweb Engine On Railway In Less Than 3 Minutes

Waren GonzagaWaren Gonzaga
6 min read

Are you looking for a production-grade HTTP server to interact with any smart contract on any EVM? That's the thirdweb Engine!

Engine is a backend HTTP server that reads, writes, and deploys contracts on a large scale. It allows you to create and interact with backend developer wallets, supporting high throughput with automatic nonce and gas management. Think of this as your rail transport vehicle or train Engine for your Railway. 🚂

Railway is a deployment platform created to simplify the software development lifecycle. It starts with instant deployments and easy scaling and includes CI/CD integrations and built-in observability. Let's say this is the Railway track for your train Engine. 🛤️

In this tutorial blog, you'll learn how to deploy your self-hosted thirdweb Engine on the Railway platform in less than 3 minutes using our community-contributed Railway template. This is the official community Railway template maintained by the thirdweb community team.

Without further ado, let's deploy your Engine to its Railway. 🚂🛤️ (you get it?)

ℹ
Are you looking for a managed thirdweb Engine? Try Cloud-Hosted!

Requirements

Steps

  1. Go to your Railway dashboard and create a "New Project."

    Railway platform showing options to create a new project, with a highlighted button for "New Project" on the top right. The Railway interface includes a sidebar with user information and a central area displaying project creation options such as deploying a GitHub repository or provisioning a database.

  2. On the new project page, search for "thirdweb" or "thirdweb Engine," and you will find the template we created.

    Railway deployment interface displaying a "New Project" screen with an option to deploy a web3 app using the "thirdweb Engine," described as an open-source server for scalable web3 apps. The background is dark with a subtle starry pattern.

  3. You will be redirected to the deploy page. First, click the "Configure" button for the Postgres service. Lastly, save the configuration and return to this page.

    A screenshot of Railway deployment interface titled "Deploy Thirdweb Engine," featuring options to configure Postgres and Engine services, set against a dark background with a starry pattern.

    Screenshot of Railway deployment interface titled "Deploy Thirdweb Engine," showing configuration options for a Postgres service including Docker image details, volume, and environment variables with a "Save Config" button at the bottom.

  4. Let's set up the thirdweb Engine service. Enter your wallet address into the ADMIN_WALLET_ADDRESS field, and then enter your "thirdweb API secret key" into the THIRDWEB_API_SECRET_KEY key input field. After that, save the configuration and return to the template deployment page.

    A screenshot of Railway interface for the thirdweb Engine, showing options to configure PostgreSQL and the Thirdweb Engine, with a dark background and a "Deploy" button at the bottom.

    A screenshot of Railway configuration interface for deploying a Docker image, specifically "thirdweb/engine:latest". The interface displays fields for Docker image details, environment variables including 'ADMIN_WALLET_ADDRESS' and 'THIRDWEB_API_SECRET_KEY', and a 'Save Config' button.

  5. All you have to do is click the "Deploy" button and wait.

    Screenshot of Railway deployment interface for "Thirdweb Engine" with options to configure and deploy services including "Postgres" and "Engine," both marked as "Ready to be deployed." The background is dark with a subtle star pattern.

  6. In less than 3 minutes, your thirdweb Engine will be ready for use. Go to your Engine service > Settings > Networking > Public Networking to find your endpoint URL.

    Screenshot of Railway web application interface showing settings for networking in a deployment environment, highlighting the public endpoint URL for an application named "engine-production".

  7. Open this endpoint URL in your browser, and you'll receive an API message response. This indicates a successful Engine installation. Be sure to save this; you will need it to import into your thirdweb Engine dashboard.

    A screenshot of a Railway interface showing a JSON response message stating "Engine is set up successfully. Manage your Engine from https://thirdweb.com/dashboard/engine." in a web browser.

Manage Ending from the Dashboard

  1. Now, let's import your endpoint URL to your thirdweb dashboard. Navigate to your Engine dashboard and select the "Import" button.

    A screenshot of a thirdweb user interface for a blockchain-related service called "Engine," featuring navigation tabs, account information, and sections for managing backend wallets and transactions. The interface includes options to import or create an instance of an Engine.

  2. Name your self-hosted thirdweb Engine, enter the endpoint URL from your Railway project, and click the import button. Follow the example provided below.

    A screenshot of thirdweb interface for importing an engine instance, featuring fields for name and URL, and buttons for "Cancel" and "Import".

  3. After you import it, it should look like this. Go ahead and view and manage your self-hosted thirdweb Engine from your account dashboard.

    Screenshot of thirdweb web interface titled "Engine," describing it as an HTTP server for smart contracts, with options to manage instances and a link to an instance named "Engine on Railway."

  4. Don't forget to create your backend wallet to execute write transactions and generate your access token. This will allow you to interact with your Engine API.

    Screenshot of thirdweb user interface for "Engine on Railway" showing sections for backend wallets and transactions with no data found, and tabs for Overview, Explorer, Relayers, Admins, Access Tokens, Webhooks, and Configuration.

    Screenshot of thirdweb web interface for "Engine on Railway" showing a section for creating and managing API access tokens, with a button highlighted for creating a new access token.

Testing

In this section, let's test your engine to see if it works. The simplest method is to make a direct request using curl in your terminal. Just replace the <xxxx> with your Railway endpoint URL and provide your access token from your thirdweb Engine dashboard.

We will send a GET request to read the contract information for name on the base-sepolia-testnet chain. Let's use 0xD1042CC90244beeE8E30e1655f1935C3e8BFB86a as our test contract address.

curl -X 'GET' \
  'https://engine-production-<xxxx>.up.railway.app/contract/base-sepolia-testnet/0xD1042CC90244beeE8E30e1655f1935C3e8BFB86a/read?functionName=name' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your access token here>'

Copy and paste this command into your terminal and press enter. It should return a response with the name of our test contract. The name should be Mata NFT.

A screenshot of a terminal window displaying a command line interface where a curl command is executed to fetch data from an API, with the output showing JSON formatted response containing the result "Mata NFT".

You can also use the Insomnia software to test your Engine. We performed a similar request using its graphical user interface (GUI). Enter your access token in the Bearer field as your authentication method, and then input your GET request URL. After that, click "Send." You should receive a 200 response code and the test contract's name.

A screenshot of the Insomnia API client interface showing a GET request to a URL and the response displayed on the right side with the result "Mata NFT".

This is it. If you see a similar result, you're good to go! 🚂🛤️

Update

You need to update the version manually from the Railway dashboard. To do this, navigate to your Engine service and redeploy the source.

Screenshot of Railway deployment interface showing options for managing a Docker image deployment, including logs, restart, redeploy, and remove actions.

ℹ
Are you looking for an effortless version update? Try Cloud-Hosted!

Enjoy, and keep building! 🫶

0
Subscribe to my newsletter

Read articles from Waren Gonzaga directly inside your inbox. Subscribe to the newsletter, and don't miss out.

Web3BlockchainREST APIAPIsTutorialthirdwebrailwayrailway-appself-hosted

Written by

Waren Gonzaga
Waren Gonzaga

A Filipino self-taught software engineer, open-source maintainer, cybersecurity researcher, tech community builder, Web3 enthusiast, and technopreneur from the Philippines. 💻💖☕