Developer Guide

Installation

Setup instructions and requirements

Installation

Complete setup instructions for Prompt Stack. Choose between our automated setup wizard or manual configuration.

Prerequisites

Required Software

  • ✅ Docker Desktop (latest version)
  • ✅ Node.js 18+ and npm
  • ✅ Git
  • ✅ Code editor (VS Code recommended)

System Requirements

  • 💻 macOS, Linux, or Windows with WSL2
  • 💾 8GB RAM minimum (16GB recommended)
  • 💿 10GB free disk space
  • 🌐 Internet connection for Docker images

Option 1: Automated Setup (Recommended)

Our setup wizard guides you through the entire process:

# Clone the repository
git clone https://github.com/your-org/prompt-stack.git
cd prompt-stack

# Run the interactive setup wizard
./setup.sh

What the Setup Wizard Does

The setup script automates everything:

  • ✅ Checks system requirements
  • ✅ Creates necessary directories
  • ✅ Generates .env files from templates
  • ✅ Configures Docker containers
  • ✅ Starts the development environment
  • ✅ Runs initial health checks

Setup Wizard Options

🚀 Quick Start (Demo Mode)

Get up and running immediately with mock services

./setup.sh
# Choose option 1: Quick Start

🔧 Custom Configuration

Add real services step by step

./setup.sh configure
# Follow prompts to add:
# - Supabase (auth/database)
# - AI providers
# - Payment providers

📊 Check Status

See what's configured and running

./setup.sh status

Option 2: Manual Setup

If you prefer manual configuration or the setup script isn't working:

1. Clone and Navigate

git clone https://github.com/your-org/prompt-stack.git
cd prompt-stack

2. Create Environment Files

# Copy environment templates
cp .env.master .env.master.local
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env.local

3. Configure Environment Variables

Backend (.env)

# Core settings
ENVIRONMENT=development
DEMO_MODE=true
CORS_ORIGINS=["http://localhost:3000"]
FRONTEND_URL=http://localhost:3000

# Leave empty for demo mode
OPENAI_API_KEY=
SUPABASE_URL=
# ... etc

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=

4. Start Docker Containers

# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# Or use Make command
make dev

5. Verify Installation

# Check if containers are running
docker ps

# View logs
docker-compose logs -f

# Test API
curl http://localhost:8000/health

Platform-Specific Instructions

macOS

macOS Setup Details

Install Docker Desktop

# Using Homebrew
brew install --cask docker

# Or download from Docker website
open https://www.docker.com/products/docker-desktop

Install Node.js

# Using Homebrew
brew install node

# Or using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Linux

Linux Setup Details

Install Docker

# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose
sudo usermod -aG docker $USER
# Log out and back in

# Fedora
sudo dnf install docker docker-compose
sudo systemctl start docker
sudo systemctl enable docker

Install Node.js

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows (WSL2)

Windows Setup Details

Enable WSL2

# Run in PowerShell as Administrator
wsl --install
# Restart computer

# Set WSL2 as default
wsl --set-default-version 2

Install Docker Desktop

Download Docker Desktop for Windows and ensure WSL2 backend is enabled in settings

Install in WSL2

# Open WSL2 terminal
cd ~
git clone https://github.com/your-org/prompt-stack.git
cd prompt-stack
./setup.sh

Post-Installation

Access Your Application

Frontend

http://localhost:3000

Backend API

http://localhost:8000

API Docs

http://localhost:8000/docs

Verify Everything Works

  1. ✅ Homepage loads at localhost:3000
  2. ✅ Can create account (demo mode)
  3. ✅ API docs load at localhost:8000/docs
  4. ✅ No errors in Docker logs

Common Installation Issues

⚠️ Port Conflicts

If ports 3000 or 8000 are in use:

# Find what's using the port
lsof -i :3000

# Change ports in docker-compose.dev.yml
ports:
  - "3001:3000"  # Use 3001 instead

⚠️ Docker Not Starting

Ensure Docker Desktop is running and you have enough resources allocated in Docker settings (at least 4GB RAM)

Next Steps

🎉 Installation Complete!

Your Prompt Stack development environment is ready. Here's what to do next:

  1. 📖 Read the Quick Start Guide
  2. 🏗️ Explore the Project Structure
  3. 🚀 Build your first feature
  4. 🔧 Add real services when ready
Back to overview →