Installation Guide

This guide will walk you through setting up Midday locally for development or self-hosting. Midday is a monorepo built with modern tools and requires several services to run.

This installation guide is for developers and self-hosters. If you just want to use Midday, sign up at midday.ai instead.

Prerequisites

Before you begin, ensure you have the following installed:

Required Tools

Bun

Version 1.3.10 or higher

curl -fsSL https://bun.sh/install | bash

Node.js

Version 20 or higher (for some dependencies)

# via nvm
nvm install 20

Git

For cloning the repository

git --version

Docker

For running Supabase locally

docker --version

System Requirements

RAM: 8GB minimum, 16GB recommended
Storage: 10GB free space
OS: macOS, Linux, or Windows (with WSL2)

Clone the Repository

Clone from GitHub

git clone https://github.com/midday-ai/midday.git
cd midday

Install Dependencies

Midday uses Bun for package management:

bun install

This will install all dependencies across the monorepo, including:

Next.js 16 with React 19
Supabase client libraries
tRPC for type-safe APIs
Tauri for desktop apps
All shared packages

The monorepo uses Bun workspaces. Dependencies in apps/* and packages/* are automatically linked.

Set Up Environment Variables

Midday requires several environment variables for different services.

Dashboard Environment Variables

Copy the example environment file for the dashboard:

cd apps/dashboard
cp .env-example .env

The .env file contains configuration for:

# Supabase - Database, Auth, Storage, Realtime
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key_here
NEXT_PUBLIC_SUPABASE_ID=your_project_id
SUPABASE_SERVICE_KEY=your_service_key_here

# Application URLs
NEXT_PUBLIC_URL=http://localhost:3001
NEXT_PUBLIC_API_URL=http://localhost:3003

For local development, you only need Supabase variables. Banking providers, AI, and other services can be added later.

Generate Encryption Keys

Generate secure keys for your environment:

# Server Actions Encryption Key (32 bytes, base64)
openssl rand -base64 32

# Invoice JWT Secret (any random string)
openssl rand -hex 32

# File Encryption Secret (any random string)
openssl rand -hex 32

# Webhook Secret (UUID format)
uuidgen

Add these to your .env file.

API Environment Variables

Set up the API service:

cd ../api
cp .env-template .env

The API requires:

Supabase credentials
Banking provider credentials
Redis URL

Set Up Supabase

Midday uses Supabase for database, authentication, storage, and real-time features.

Option 1: Use Supabase Cloud (Recommended for Development)

Sign up at supabase.com
Create a new project
Go to Settings → API to get your keys:
- Project URL
- Anon (public) key
- Service role key
Add these to your .env file

Supabase Cloud has a generous free tier perfect for development.

Option 2: Run Supabase Locally

Install Supabase CLI and run locally:

# Install Supabase CLI
brew install supabase/tap/supabase

# Start Supabase (requires Docker)
supabase start

This will start:

PostgreSQL database (port 54322)
PostgREST API (port 54321)
Auth server (port 54324)
Storage server (port 54325)
Realtime server (port 54326)
Supabase Studio (port 54323)

The CLI will output connection details. Add them to your .env:

NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon_key_from_output>
SUPABASE_SERVICE_KEY=<service_key_from_output>

Run Database Migrations

Apply the database schema:

# If using Supabase Cloud
supabase link --project-ref your-project-ref
supabase db push

# If using Supabase locally
# Migrations are auto-applied on start

This creates all necessary tables:

users - User accounts
teams - Team/business information
bank_accounts - Connected bank accounts
transactions - Financial transactions
invoices - Invoice data
customers - Client information
And many more…

Set Up Banking Providers (Optional)

To enable bank connections, you need credentials from banking providers.

Plaid (US & Canada)

Sign up at plaid.com
Create an application in sandbox mode
Get your Client ID and Secret
Add to .env:

PLAID_CLIENT_ID=your_client_id
PLAID_SECRET=your_sandbox_secret
NEXT_PUBLIC_PLAID_ENVIRONMENT=sandbox

Plaid’s sandbox mode allows testing with fake bank credentials without connecting real banks.

Teller (US)

Sign up at teller.io
Generate a certificate for authentication
Base64 encode your certificate and private key
Add to .env:

TELLER_CERTIFICATE=base64_encoded_certificate
TELLER_CERTIFICATE_PRIVATE_KEY=base64_encoded_key
NEXT_PUBLIC_TELLER_APPLICATION_ID=your_app_id
NEXT_PUBLIC_TELLER_ENVIRONMENT=sandbox

GoCardLess (Europe)

Sign up at gocardless.com
Access the Bank Account Data product
Get your Secret ID and Secret Key
Configure in Supabase (stored encrypted in database)

GoCardLess credentials are stored in the database, not environment variables, for security.

Run the Development Servers

Now you’re ready to run Midday locally!

Start All Services

From the root directory, start all services:

bun run dev

This starts:

Dashboard - http://localhost:3001 (Main app)
API - http://localhost:3003 (Backend)
Worker - Background job processor
Website - http://localhost:3000 (Marketing site)

Or Start Individual Services

You can also start services individually:

# Dashboard only (most common for development)
bun run dev:dashboard

# API only
bun run dev:api

# Desktop app (Tauri)
bun run dev:desktop

# Website
bun run dev:website

Access the Application

Open your browser and navigate to:

Dashboard: http://localhost:3001
Supabase Studio: http://localhost:54323 (if running locally)

Create an account to get started!

Verify Installation

Check Service Health

Verify all services are running:

# Check dashboard
curl http://localhost:3001

# Check API
curl http://localhost:3003/health

# Check Supabase
curl http://localhost:54321/rest/v1/

Create Test Account

Navigate to http://localhost:3001
Click “Sign Up”
Enter your email and password
Complete the onboarding flow

In development, email verification is disabled by default. Check your Supabase project settings to enable it.

Test Key Features

Verify the installation by testing:

✅ Sign up and login
✅ Complete onboarding
✅ Navigate between pages
✅ Create a draft invoice
✅ Upload a file to vault

Troubleshooting

Port already in use

If ports 3001 or 3003 are already in use:

# Find process using port
lsof -i :3001

# Kill the process
kill -9 <PID>

# Or change the port in package.json
"dev": "next dev -p 3002"

Supabase connection error

If you can’t connect to Supabase:

Verify Docker is running: docker ps
Check Supabase is started: supabase status
Verify environment variables are correct
Check firewall isn’t blocking ports 54321-54326

Banking provider errors

If bank connections aren’t working:

Verify you’re using sandbox/test credentials
Check provider status pages:
- Plaid Status
- Teller Status
Ensure environment variables are properly set
Check API logs for detailed errors

Build errors

If you encounter build errors:

# Clean all build artifacts
bun run clean:workspaces

# Remove node_modules
bun run clean

# Reinstall dependencies
bun install

# Try building again
bun run build

TypeScript errors

If you see TypeScript errors:

# Run type checking
bun run typecheck

# Fix common issues
bun run lint:fix

# Regenerate Supabase types
supabase gen types typescript --local > packages/supabase/src/types.ts

Build for Production

To build Midday for production:

# Build all apps and packages
bun run build

Next Steps

Now that Midday is running locally:

Architecture

Learn about the monorepo structure and how packages work together

API Reference

Explore the tRPC API and learn how to add new endpoints

Database Schema

Understand the Supabase database schema and relationships

Contributing

Learn how to contribute to Midday

Self-Hosting License: Midday is AGPL-3.0 for non-commercial use. If you’re deploying for commercial purposes, contact [email protected] for a commercial license.

Development Tips

Useful Commands

# Run tests
bun test

# Lint code
bun run lint

# Format code
bun run format

# Type check
bun run typecheck

# Clean everything
bun run clean && bun run clean:workspaces

Monorepo Structure

// Import from workspace packages
import { Provider } from "@midday/banking";
import { createClient } from "@midday/supabase/client";
import { Button } from "@midday/ui/button";

// All packages are linked automatically via Bun workspaces

Hot Reload

Next.js and Turbopack provide instant hot reload:

Edit any file in apps/dashboard/src
Changes appear immediately in the browser
No manual restart needed

Need help? Join our community or open an issue on GitHub.

Get Started

Core Features

Integrations

Development

Installation

Installation Guide

Prerequisites

Required Tools

Bun

Node.js

Git

Docker

System Requirements

Clone the Repository

Set Up Environment Variables

Set Up Supabase

Set Up Banking Providers (Optional)

Run the Development Servers

Verify Installation

Troubleshooting

Build for Production

Next Steps

Architecture

API Reference

Database Schema

Contributing

Development Tips

Useful Commands

Monorepo Structure

Hot Reload

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Development

​Installation Guide

​Prerequisites

​Required Tools

Bun

Node.js

Git

Docker

​System Requirements

​Clone the Repository

​Set Up Environment Variables

​Set Up Supabase

​Set Up Banking Providers (Optional)

​Run the Development Servers

​Verify Installation

​Troubleshooting

​Build for Production

​Next Steps

Architecture

API Reference

Database Schema

Contributing

​Development Tips

​Useful Commands

​Monorepo Structure

​Hot Reload

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Required Tools

System Requirements

Clone the Repository

Set Up Environment Variables

Set Up Supabase

Set Up Banking Providers (Optional)

Run the Development Servers

Verify Installation

Troubleshooting

Build for Production

Next Steps

Development Tips

Useful Commands

Monorepo Structure

Hot Reload