Installation Guide

Overview

RestAI can be installed in multiple ways depending on your use case:

Local Development

Best for development and testing

Docker Compose

Simplified deployment with containers

Production

Scalable production deployment

System Requirements

Local Development

Bun

required

Version 1.3 or higher - JavaScript runtime and package managerInstall: curl -fsSL https://bun.sh/install | bash

PostgreSQL

required

Version 17 - Relational databaseInstall via:

macOS: brew install postgresql@17
Ubuntu: apt install postgresql-17
Windows: Download from postgresql.org

Docker

required

For running Redis and optional full containerizationInstall: docker.com/get-started

Node.js

optional

Bun can replace Node.js, but some tools may require it

Production

CPU: 2+ cores recommended
RAM: 2GB minimum, 4GB+ recommended
Storage: 10GB+ for database and logs
OS: Linux (Ubuntu 22.04 LTS recommended)

Local Development Installation

1. Clone Repository

git clone [email protected]:yourusername/restai.git
cd restai

2. Install Dependencies

Install all workspace dependencies with Bun:

bun install

Bun’s package manager is significantly faster than npm or yarn, and it supports workspaces natively.

3. Environment Configuration

RestAI uses environment variables for configuration. Create your .env file:

cp .env.example .env

Core Environment Variables

# ── PostgreSQL ────────────────────────────────────────────────────────
POSTGRES_USER=restai
POSTGRES_PASSWORD=change-me-in-production
DATABASE_URL=postgresql://restai:change-me-in-production@localhost:5432/restai

# ── API Server ────────────────────────────────────────────────────────
API_PORT=3001
JWT_SECRET=change-me-in-production
JWT_REFRESH_SECRET=change-me-in-production
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:3000

# ── Redis ─────────────────────────────────────────────────────────────
REDIS_URL=redis://localhost:6379

# ── Web App (build-time) ──────────────────────────────────────────────
NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_WS_URL=ws://localhost:3001

# ── Cloudflare R2 Storage (optional) ──────────────────────────────────
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=restai
R2_PUBLIC_URL=

Security Best Practices:

Generate strong random secrets: openssl rand -base64 32
Never commit .env files to version control
Use different secrets for each environment
Rotate secrets regularly in production

Copy to Individual Apps

Environment variables need to be copied to specific apps:

# API and database package
cp .env apps/api/.env
cp .env packages/db/.env

# Web app (only needs public variables)
echo "NEXT_PUBLIC_API_URL=http://localhost:3001" > apps/web/.env
echo "NEXT_PUBLIC_WS_URL=ws://localhost:3001" >> apps/web/.env

4. Start PostgreSQL

Ensure PostgreSQL is running:

brew services start postgresql@17

# Verify it's running
pg_isready

5. Create Database

Create the RestAI database:

createdb restai

Or using psql:

psql -U postgres
CREATE DATABASE restai;
\q

Make sure the database name matches the one in your DATABASE_URL environment variable.

6. Start Redis

Use Docker Compose to start Redis:

docker compose up -d

This starts only the Redis service. Verify it’s running:

docker ps | grep redis

7. Database Setup

Apply the Drizzle schema to create all tables:

bun run db:push

What this does:

Creates all tables (organizations, users, branches, menu items, orders, etc.)
Sets up foreign key relationships
Creates indexes for performance
Applies enum types

Seed Demo Data (Optional)

Load sample data for testing:

bun run db:seed

The seed script creates:

Demo organization: “RestAI Demo”
Default branch: “Sede Principal”
Admin user: [email protected] / admin12345
Sample menu categories and items
Tables with QR codes

8. Start Development Servers

Launch both API and web app:

bun run dev

Turborepo will start both applications in parallel with hot reload:

Web Dashboard

Next.js

http://localhost:3000Admin dashboard and customer QR flow

API Server

Hono

http://localhost:3001REST API + WebSocket endpoint at /ws

Success! RestAI is now running locally. Open http://localhost:3000 to access the dashboard.

Docker Compose Installation

For a fully containerized setup, use Docker Compose to run all services:

1. Configure Environment

Create .env file with your configuration:

cp .env.example .env

Edit the file with your settings (see environment variables above).

2. Build and Start Services

docker compose up -d

This starts:

postgres - PostgreSQL 17 database
redis - Redis 7 for caching
migrate - One-time migration service
api - Hono API server on port 3001
web - Next.js app on port 3100

The web app runs on port 3100 when using Docker Compose (not 3000) to avoid conflicts.

3. View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api

4. Access Services

Service	URL	Description
Web	http://localhost:3100	Dashboard
API	http://localhost:3001	REST API
PostgreSQL	localhost:5432	Database
Redis	localhost:6379	Cache

5. Seed Database (Optional)

Run the seed script inside the API container:

docker compose exec api bun run --filter @restai/db seed

Database Management

RestAI uses Drizzle ORM for type-safe database operations.

Available Commands

# Push schema changes to database (no migrations)
bun run db:push

Use db:push for development and db:generate + db:migrate for production to track schema changes.

Database Schema Highlights

Key tables in the RestAI schema:

Multi-Tenancy

organizations - Top-level tenant isolation
branches - Physical locations per organization
users - User accounts with role-based access
user_branches - Many-to-many user-branch assignments

Menu Management

Orders & Tables

tables - Physical tables with QR codes
table_sessions - Active customer sessions
orders - Customer orders with status tracking
order_items - Line items with modifiers

Payments & Loyalty

payments - Transaction records
invoices - Tax receipts
loyalty_points - Customer reward points
coupons - Discount codes

Production Deployment

Using Docker

For production deployments, use the provided Dockerfiles:

# Build API image
docker build -f Dockerfile.api -t restai-api .

# Build Web image  
docker build -f Dockerfile.web -t restai-web \
  --build-arg NEXT_PUBLIC_API_URL=https://api.yourdomain.com .

Production Checklist:

Use strong, unique secrets for JWT tokens
Enable SSL/TLS for all connections
Set LOG_LEVEL=warn or error
Configure proper CORS origins
Set up database backups
Use a managed PostgreSQL service (AWS RDS, Supabase, etc.)
Use a managed Redis service (Upstash, Redis Cloud, etc.)
Configure Cloudflare R2 for image storage
Set up monitoring and error tracking

Platform-Specific Guides

Docker Deployment

Deploy with Docker Compose

Environment Variables

Configure your deployment

Database Setup

Set up and manage your database

Security Best Practices

Secure your production deployment

Troubleshooting

Migration fails with 'relation already exists'

This happens if you ran db:push before db:migrate.Solution:

# Reset database (WARNING: deletes all data)
dropdb restai
createdb restai
bun run db:migrate

WebSocket connection refused

Error: WebSocket connection to ws://localhost:3001/ws failedSolutions:

Verify API is running: curl http://localhost:3001/health
Check NEXT_PUBLIC_WS_URL matches API host
Ensure no firewall blocking port 3001

Image uploads fail

Error: Failed to upload image or R2 errorSolutions:

Verify R2 credentials in .env
Check bucket name and permissions
For local dev, image uploads are optional
Images are stored as URLs if R2 is not configured

Bun workspace resolution errors

Error: Cannot find module ‘@restai/…’Solutions:

# Clean and reinstall
rm -rf node_modules
find . -name 'node_modules' -type d -prune -exec rm -rf '{}' +
bun install

Next Steps

Configure Your Organization

Set up organization details, branding, and business hours

Set Up Users & Permissions

Create staff accounts with appropriate role-based access

Build Your Menu

Add categories, items, modifiers, and pricing

Create Tables

Generate QR codes for table-based ordering

Configure Payments

Set up payment methods and tax rates

Test the Flow

Place test orders through the customer interface

API Reference

Explore all available endpoints and authentication

Core Features

Learn how to use all features of the dashboard

Get Started

Core Features

Deployment

Architecture

​Overview

Local Development

Docker Compose

Production

​System Requirements

​Local Development

​Production

​Local Development Installation

​1. Clone Repository

​2. Install Dependencies

​3. Environment Configuration

​Core Environment Variables

​Copy to Individual Apps

​4. Start PostgreSQL

​5. Create Database

​6. Start Redis

​7. Database Setup

​Seed Demo Data (Optional)

​8. Start Development Servers

​Docker Compose Installation

​1. Configure Environment

​2. Build and Start Services

​3. View Logs

​4. Access Services

​5. Seed Database (Optional)

​Database Management

​Available Commands

​Database Schema Highlights

​Production Deployment

​Using Docker

​Platform-Specific Guides

Docker Deployment

Environment Variables

Database Setup

Security Best Practices

​Troubleshooting

​Next Steps

API Reference

Core Features

Build docs developers (and LLMs) love

Overview

System Requirements

Local Development

Production

Local Development Installation

1. Clone Repository

2. Install Dependencies

3. Environment Configuration

Core Environment Variables

Copy to Individual Apps

4. Start PostgreSQL

5. Create Database

6. Start Redis

7. Database Setup

Seed Demo Data (Optional)

8. Start Development Servers

Docker Compose Installation

1. Configure Environment

2. Build and Start Services

3. View Logs

4. Access Services

5. Seed Database (Optional)

Database Management

Available Commands

Database Schema Highlights

Production Deployment

Using Docker

Platform-Specific Guides

Troubleshooting

Next Steps