Skip to main content

​
Quickstart

This guide will help you set up Forge and create your first customized dashboard with widgets in just a few minutes.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js v18 or later installed on your system
  • PostgreSQL database (local or hosted)
  • Redis instance (we recommend Upstash for easy setup)
  • Blob storage (Vercel Blob or compatible alternative)
If you’re just getting started, we recommend using Vercel Postgres and Upstash Redis for quick setup.

​
Installation

1

Clone the repository

First, clone the Forge repository and navigate into the directory:
git clone https://github.com/mvriu5/forge.git
cd forge
2

Install dependencies

Install all required npm packages:
npm install
This will install Next.js 16, React 19, Drizzle ORM, BetterAuth, and all other dependencies.
3

Set up environment variables

Create a .env file in the root directory with your configuration:
# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=your-random-secret-key-here

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

# Redis (Upstash)
UPSTASH_REDIS_REST_URL=https://your-redis.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

Run database migrations

Set up the database schema using Drizzle:
npx drizzle-kit push
This creates the necessary tables for users, sessions, dashboards, widgets, and settings.
5

Start the development server

Launch Forge in development mode:
npm run dev
Open http://localhost:3000 in your browser to see Forge running.

​
Create Your First Dashboard

Now that Forge is running, let’s set up your first dashboard:
1

Create an account

  1. Navigate to http://localhost:3000
  2. Click Sign Up to create a new account
  3. Enter your name, email, and password
  4. You’ll be automatically logged in after registration
2

Complete onboarding

After signing up, you’ll see the onboarding dialog:
  1. Enter a name for your first dashboard (e.g., “Work Dashboard” or “Personal”)
  2. Choose a theme preference (Light or Dark mode)
  3. Click Get Started to complete the setup
Forge will automatically create your first empty dashboard.
3

Add your first widget

Now let’s add a widget to your dashboard:
  1. Click the + Add Widget button in the top-right corner
  2. Browse the available widgets (Clock, Weather, Todo, etc.)
  3. Select a widget type - let’s start with Clock since it requires no setup
  4. The widget will appear on your dashboard
Some widgets like Clock, Countdown, and Bookmarks work immediately. Others like Meetings and Inbox require OAuth integration with Google.
4

Customize the layout

Forge uses a drag-and-drop grid system:
  1. Click Edit Mode in the top-right to enable editing
  2. Drag the widget to reposition it on the grid
  3. Resize by dragging the corners (each widget has min/max size constraints)
  4. Add more widgets to build your perfect layout
  5. Click Save when you’re done
Changes are automatically saved to your account.

​
Add More Widgets

Now that you have your first widget, let’s add a few more useful ones:
These widgets work immediately without any integrations:
  • Clock - Display current time with timezone support
  • Weather - Get local weather using geolocation (Open-Meteo API)
  • Todo - Manage tasks with checkboxes and reminders
  • Bookmarks - Save and organize favorite links
  • Countdown - Track time until important events
  • Kanban - Organize tasks in a visual board
  • Markdown Editor - Draft notes with rich text formatting

​
Next Steps

Congratulations! You’ve successfully set up Forge and created your first dashboard. Here’s what to explore next:

Connect Integrations

Link Google, GitHub, or Notion to unlock powerful widgets

Explore Widgets

Learn about all 13 available widgets and their features

Multiple Dashboards

Organize widgets across different dashboards for different contexts

Customize Themes

Personalize colors and layout to match your workflow

​
Troubleshooting

Make sure your PostgreSQL database is running and the DATABASE_URI in your .env file is correct. Test the connection:
psql $DATABASE_URI -c "SELECT 1"
Verify your Upstash Redis credentials are correct. You can test the connection using the Upstash dashboard or with:
curl -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" $UPSTASH_REDIS_REST_URL/ping
Try clearing your cache and reinstalling:
rm -rf node_modules package-lock.json
npm install
Check the browser console for errors. Make sure all required environment variables are set and the API endpoints are responding. Test by visiting http://localhost:3000/api/dashboards - you should see a JSON response.
Need more help? Check out the Self-Hosting Guide for detailed deployment instructions or visit the GitHub Issues page.

Build docs developers (and LLMs) love

Get started for freeTalk to us