Environment Setup

Complete guide for setting up both Backend and Frontend environments for local development.

Table of Contents

Prerequisites

Backend Requirements:

  • Docker & Docker Compose
  • Rust (if building manually)
  • PostgreSQL access

Frontend Requirements:

  • Node.js 18.20.0 or higher
  • pnpm (auto-installed by setup)
  • Modern browser

Backend Setup

Environment Configuration

Generate your active .env file using the interactive script:

cd appflowy-backend
./script/generate_env.sh

Environment Files:

  • dev.env - Development template with safe defaults
  • deploy.env - Production template
  • .env - Active environment file (auto-generated)
  • .env.dev.secret - Secret value overrides (optional)

Google OAuth Setup

Required for SSO authentication:

  1. Go to Google Cloud Console → Credentials
  2. Create OAuth client ID → Web application
  3. Add authorized redirect URIs for your domain
  4. Copy Client ID and Secret to your .env file
GOTRUE_EXTERNAL_GOOGLE_ENABLED=true
GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID=your_client_id
GOTRUE_EXTERNAL_GOOGLE_SECRET=your_client_secret
GOTRUE_SITE_URL=http://localhost:3000

Start Backend Services

Method 1: Using Script (Recommended)

./script/run_local_server.sh

Method 2: Docker Compose Only

docker compose -f docker-compose-dev.yml up -d

Method 3: Manual Start

# Start services
docker compose -f docker-compose-dev.yml up -d

# Run AppFlowy Cloud manually
SQLX_OFFLINE=true cargo run --bin appflowy_cloud

Frontend Setup

Quick Start (Recommended)

# Clone and setup in one command
git clone https://github.com/AppFlowy-IO/AppFlowy-Web.git
cd AppFlowy-Web
./setup.sh

# Start development server
pnpm run dev

Manual Setup

# Install dependencies
pnpm install

# Setup environment
cp dev.env .env.local

# Start development server
pnpm run dev

Backend Connection: Update .env.local with your backend URL:

VITE_CLOUD_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000

Available Scripts

  • pnpm run dev - Start development server
  • pnpm run build - Build for production
  • pnpm run test - Run tests
  • pnpm run lint - Run ESLint
  • pnpm run type-check - Run TypeScript checks

Troubleshooting

Backend Issues

Docker Compose errors:

  • Make sure ports 5432, 6379, 8000, 9000, 9001 are available
  • Run ./script/generate_env.sh to create .env file
  • Check Docker daemon is running

Database connection failed:

  • Verify PostgreSQL is running: docker compose ps
  • Check database credentials in .env
  • Reset database: docker compose down -v && docker compose up

GoTrue authentication issues:

  • Ensure GOTRUE_JWT_SECRET is consistent across services
  • Check Google OAuth client ID and secret are correct
  • Verify redirect URIs in Google Console

Frontend Issues

Build failures:

  • Delete node_modules and run pnpm install
  • Clear pnpm cache: pnpm store prune
  • Check Node.js version is 18.20.0 or higher

Backend connection errors:

  • Verify backend is running on http://localhost:8000
  • Check VITE_CLOUD_URL in .env.local
  • Ensure CORS is enabled in backend configuration

Hot reload not working:

  • Check if files are being watched correctly
  • Try restarting the development server
  • Verify file permissions in the project directory

Configuration Reference

Common Environment Variables

# Database
DATABASE_URL=postgres://postgres:password@localhost:5432/postgres

# Authentication  
GOTRUE_JWT_SECRET=your-jwt-secret
GOTRUE_ADMIN_EMAIL=admin@example.com
GOTRUE_ADMIN_PASSWORD=password

# Storage
AWS_ACCESS_KEY=minioadmin
AWS_SECRET=minioadmin
APPFLOWY_S3_USE_MINIO=true
APPFLOWY_S3_MINIO_URL=http://localhost:9000

# Features
SPACE_ACL_ENABLED=true
PROJECT_ACL_ENABLED=true

Quick Commands Reference

# Backend
./script/run_local_server.sh              # Start all services
docker compose -f docker-compose-dev.yml logs -f  # View logs
docker compose down                        # Stop services

# Frontend  
pnpm run dev                              # Development server
pnpm run build                            # Production build
pnpm run test                             # Run tests

Need more details? Check the Database Architecture and System Architecture documentation.