Skip to main content
Forge is designed to be fully self-hostable, giving you complete control over your data and infrastructure. This guide will walk you through setting up your own Forge instance.

​
Prerequisites

Before you begin, ensure you have the following:
  • Node.js v18 or later (recommended: v20+)
  • PostgreSQL database (v14 or later recommended)
  • Redis instance - Upstash Redis or compatible Redis service
  • Blob storage - Vercel Blob or S3-compatible storage for file uploads
  • Git for cloning the repository
Forge uses Next.js 16, Drizzle ORM for database management, and BetterAuth for authentication. Make sure your infrastructure supports these technologies.

​
Installation

1

Clone the repository

Clone the Forge repository from GitHub:
git clone https://github.com/mvriu5/forge.git
cd forge
2

Install dependencies

Install all required Node.js packages using npm:
npm install
This will install all dependencies including:
  • Next.js (v16.1.6+)
  • Drizzle ORM for database operations
  • BetterAuth for authentication
  • Upstash Redis client
  • React Query for data fetching
  • And all other required packages
3

Configure environment variables

Create a .env file in the root of the project:
touch .env
Add the required environment variables to your .env file. See the Environment Variables page for a complete reference.At minimum, you’ll need:
# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000

# Authentication
BETTER_AUTH_SECRET=your-secret-key-here

# Database
DATABASE_URI=postgresql://user:password@localhost:5432/forge

# Redis
UPSTASH_REDIS_REST_URL=https://your-redis-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-redis-token

# Blob Storage
BLOB_READ_WRITE_TOKEN=your-blob-token
Generate a strong, random string for BETTER_AUTH_SECRET. You can use:
openssl rand -base64 32
4

Set up the database

Run database migrations using Drizzle Kit to create all necessary tables:
npx drizzle-kit push
This will create the following tables in your PostgreSQL database:
  • user - User accounts
  • account - OAuth provider connections
  • session - User sessions
  • dashboard - User dashboards
  • widget - Dashboard widgets
  • settings - User settings
Drizzle Kit will connect to your database using the DATABASE_URI from your .env file. Make sure your PostgreSQL instance is running and accessible.
5

Start the development server

Start Forge in development mode:
npm run dev
The application will be available at http://localhost:3000 (or the URL you specified in NEXT_PUBLIC_APP_URL).
6

Create your first account

Open your browser and navigate to your Forge instance. You can create an account using:
  • Email and password (enabled by default)
  • GitHub OAuth (if configured)
  • Google OAuth (if configured)
Once logged in, you can start creating dashboards and adding widgets.

​
Building for Production

To build Forge for production deployment: 
npm run build
The build process will:
  1. Compile TypeScript code
  2. Optimize React components (using React Compiler)
  3. Generate optimized static assets
  4. Create production-ready server bundles
For production deployments, see the Deployment guide for platform-specific instructions.

​
Verifying Your Installation

After setup, verify everything is working:
  1. Authentication: Try logging in with email/password
  2. Database: Create a dashboard - it should persist after refresh
  3. Redis: Real-time notifications should work (test with widget updates)
  4. Blob Storage: Upload a profile picture in settings

​
Next Steps

Environment Variables

Configure all environment variables for full functionality

Deployment

Deploy Forge to production platforms

​
Troubleshooting

​
Database Connection Issues

If you see database connection errors:
  • Verify your DATABASE_URI is correct
  • Ensure PostgreSQL is running and accessible
  • Check firewall rules allow connections to PostgreSQL port (default: 5432)
  • Verify the database user has proper permissions

​
Redis Connection Issues

If Redis connection fails:
  • Verify your Upstash Redis URL and token are correct
  • Check if your Redis instance is active in the Upstash dashboard
  • Ensure your network allows outbound connections to Upstash

​
Build Errors

If you encounter build errors:
  • Ensure you’re using Node.js v18 or later
  • Delete node_modules and .next folders, then run npm install again
  • Check that all environment variables are properly set
If you’re missing required environment variables, the build may fail or certain features may not work. Always check the console for specific error messages.

Build docs developers (and LLMs) love

Get started for freeTalk to us