Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:This guide provides comprehensive instructions for deploying the various components of the OnChain Sage application. The project's modular architecture necessitates distinct deployment strategies for the frontend, backend, and the Starknet smart contracts (Dojo). This document covers the prerequisites, configuration, and step-by-step processes for each service.
The overall deployment strategy involves containerization with Docker for local development and production environments, with specific hosting solutions like Vercel for the frontend and cloud providers (AWS/GCP) for the backend and database infrastructure. The smart contracts are deployed directly to the Starknet network.
Sources: ARCHITECTURE.md
High-Level Deployment Architecture
The OnChain Sage application consists of three main deployable components, each with its own target environment.
This diagram illustrates the deployment targets for each major component of the OnChain Sage system.
Sources: ARCHITECTURE.md, apps/frontend/README.md:40-44, apps/backend/README.md:14-15, apps/dojo/README.md:83-91
Frontend Deployment
The frontend is a Next.js application designed for easy deployment on Vercel.
Vercel Deployment
The application is pre-configured for deployment on Vercel, which provides several benefits:
- Automatic Deployments: Code merged into the
mainbranch is automatically deployed to production. - Preview Deployments: Every pull request generates a unique preview deployment, allowing for review before merging.
- Edge Network Distribution: Vercel's edge network ensures fast delivery to users globally.
The deployment process is managed by Vercel by linking the GitHub repository. No manual steps are typically required after the initial setup.
Sources: apps/frontend/README.md:40-44
Backend Deployment
The backend is a NestJS application that requires a PostgreSQL database. It can be deployed using Docker on a cloud provider like AWS or GCP.
Sources: ARCHITECTURE.md, apps/backend/README.md
Prerequisites
- Node.js (v16 or higher)
- A running PostgreSQL instance
Sources: apps/backend/README.md:27-28
Database Setup
Before deploying the backend, you must create a dedicated database.
- Connect to your PostgreSQL server:
psql -U postgres - Create the database:
CREATE DATABASE onchainsage;
Sources: apps/backend/README.md:35-41
Environment Configuration
The backend uses environment variables for configuration. Create a .env.development (or a corresponding file for your environment) and populate it with the necessary values.
| Variable | Description | Example Value |
|---|---|---|
DATABASE_HOST | Database server host | localhost |
DATABASE_PORT | Database server port | 5432 |
DATABASE_USER | Database username | your_user |
DATABASE_PASSWORD | Database user password | your_password |
DATABASE_NAME | Name of the database | onchainsage |
JWT_SECRET | Secret key for JWT signing | your_jwt_secret |
JWT_EXPIRATION | JWT token expiration time | 24h |
PORT | Port for the backend server to run on | 3000 |
NODE_ENV | Application environment | development |
Sources: apps/backend/README.md:43-51, apps/backend/README.md:68-80
Production Build and Run
To deploy the backend for production:
- Build the application:
npm run build - Start the production server:
npm run start:prod
These commands are executed from the apps/backend directory. For a containerized deployment, these steps would be part of a Dockerfile.
Sources: apps/backend/README.md:58-59
Dojo (Smart Contracts) Deployment
The OnChain Sage smart contracts are built with the Dojo framework and deployed to the Starknet network. The repository includes scripts for deploying to both testnet and mainnet.
Sources: apps/dojo/README.md
Prerequisites
- Install Dojo:
curl -L https://install.dojoengine.org | bash dojoup
Sources: apps/dojo/README.md:27-30
Environment Setup
Create an environment file for the target network (e.g., .env.mainnet) by copying the template.
cp config/env.template .env.mainnet
Fill in the following variables in the .env.mainnet file:
STARKNET_RPC_URL: RPC endpoint for the Starknet mainnet.ACCOUNT_ADDRESS: The address of the account that will pay for the deployment.PRIVATE_KEY: The private key for the deployment account.
The dojo_release.toml file specifies the default mainnet RPC URL.
# apps/dojo/dojo_release.toml
[env]
rpc_url = "https://starknet-mainnet.infura.io/v3/"
Sources: apps/dojo/README.md:47-55, apps/dojo/scripts/deploy-mainnet.sh:18-24, apps/dojo/dojo_release.toml:15-16
Mainnet Deployment
The mainnet deployment is handled by the deploy-mainnet.sh script, which includes several safety checks.
To start the deployment, run:
./scripts/deploy-mainnet.sh
Sources: apps/dojo/README.md:89-91
The script follows this process:
This flowchart shows the step-by-step execution flow of the mainnet deployment script, including all safety checks and confirmations.
Sources: apps/dojo/scripts/deploy-mainnet.sh
CI/CD Deployment
The project is configured with GitHub Actions for automated deployments. For this to function, the following secrets must be configured in the GitHub repository settings.
| Secret Name | Description |
|---|---|
TESTNET_RPC_URL | RPC URL for the Starknet testnet. |
TESTNET_ACCOUNT_ADDRESS | Account address for testnet deployments. |
TESTNET_PRIVATE_KEY | Private key for the testnet account. |
MAINNET_RPC_URL | RPC URL for the Starknet mainnet. |
MAINNET_ACCOUNT_ADDRESS | Account address for mainnet deployments. |
MAINNET_PRIVATE_KEY | Private key for the mainnet account. |
Deployment to testnet is automatic on pushes to the develop branch, while mainnet deployment is a manual action on the main branch.
Sources: apps/dojo/README.md:112-126