Installation Guide

Overview

This guide covers detailed installation steps for 8Space, including system requirements, dependency setup, database configuration, and deployment options.

For a faster getting started experience, see the Quickstart guide.

System requirements

Required software

Software	Minimum version	Recommended	Purpose
Node.js	18.x	20.x LTS	JavaScript runtime
npm	8.x	10.x	Package manager
Supabase CLI	1.50+	Latest	Local database management
Docker	20.x	Latest	Required for Supabase local dev
Git	2.x	Latest	Version control

Optional software

Python 3 (for Swagger UI dev server)
PostgreSQL client (for direct database access)

Operating system support

8Space is tested on:

macOS 12+ (Apple Silicon and Intel)
Ubuntu 20.04+ and Debian-based Linux
Windows 10+ with WSL2

Windows users should use WSL2 for the best development experience. Native Windows support for Supabase CLI can be limited.

Installation methods

Choose the installation method that fits your needs:

Local development
Production (self-hosted)
Docker

Complete setup for local development with hot reload and debugging.

Local development setup

Follow these steps for a complete local development environment.

Step 1: Install Node.js and npm

brew install node@20

Verify installation:

node --version  # Should show v20.x.x or v18.x.x
npm --version   # Should show 10.x.x or higher

Step 2: Install Supabase CLI

brew install supabase/tap/supabase

Verify installation:

supabase --version  # Should show v1.50.0 or higher

Step 3: Install Docker

Supabase local development requires Docker to run PostgreSQL and other services.

# Download Docker Desktop from:
https://www.docker.com/products/docker-desktop

# Or install via Homebrew:
brew install --cask docker

Verify Docker is running:

docker --version
docker ps  # Should not show errors

On Linux, you may need to log out and back in after adding your user to the docker group.

Step 4: Clone the repository

Clone 8Space from GitHub:

git clone https://github.com/AndreyMishurin/8Space.git
cd 8Space

Check the repository structure:

ls -la
# You should see:
# packages/     - Main code (landing + app)
# docs/        - Documentation and OpenAPI spec
# scripts/     - Development orchestration
# package.json - Root workspace configuration

Step 5: Install dependencies

Install all workspace dependencies from the root:

npm install

This installs dependencies for:

Root workspace
packages/landing (Next.js landing page)
packages/app (React + Vite main application)

Understanding npm workspaces

The root package.json defines a workspace:

{
  "workspaces": ["packages/*"]
}

This allows npm to:

Hoist common dependencies to the root node_modules
Link workspace packages together
Run workspace-specific commands with -w flag

Example:

npm run dev -w packages/landing  # Run landing dev server only

Step 6: Configure Supabase

Initialize and start the local Supabase instance:

cd packages/app
supabase start

What happens during supabase start?

The CLI:

Pulls Docker images for:
- PostgreSQL 15 (database)
- PostgREST (auto-generated REST API)
- GoTrue (authentication)
- Realtime (WebSocket subscriptions)
- Storage (file uploads)
- Kong (API gateway)
- Supabase Studio (admin UI)
Starts containers with ports:
- 54321 - API Gateway
- 54322 - PostgreSQL direct connection
- 54323 - Supabase Studio
- 55324 - Inbucket (email testing)

Outputs connection details:

API URL: http://127.0.0.1:54321
anon key: eyJhbGc...
service_role key: eyJhbGc...

Applies migrations from supabase/migrations/

Important: Save the output from supabase start, especially:

anon key (for client-side auth)
service_role key (for admin operations)

Step 7: Apply migrations and seed data

Reset the database to apply all migrations and seed test data:

supabase db reset
cd ../..

This command:

Drops and recreates the database
Applies migrations in order:
- 20260212220000_init_gantt_mvp.sql - Core schema
- 20260213220000_auto_join_new_users.sql - User onboarding
- 20260213220100_handle_new_user_google_compat.sql - Google OAuth
- 20260216220000_fix_create_project_trigger_conflict.sql - Bug fix
- 20260217143000_multi_tenant_onboarding.sql - Multi-tenancy
Runs seed.sql to create:
- 3 test users (owner, editor, viewer)
- 1 demo tenant (“8Space Demo”)
- 1 demo project (“Product Launch Q2”)
- 5 sample tasks with dependencies

The seed data is defined in packages/app/supabase/seed.sql. You can modify it to create custom test data.

Step 8: Configure environment variables

Create environment files for both packages. App environment (packages/app/.env):

VITE_SUPABASE_URL=http://127.0.0.1:54321
VITE_SUPABASE_ANON_KEY=<paste-anon-key-from-supabase-start>

Landing environment (packages/landing/.env.local):

# Required for auth features
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<paste-anon-key-from-supabase-start>

# Optional: Google OAuth (configure in supabase/config.toml first)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# Optional: Stripe for billing
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Optional: Resend for emails
RESEND_API_KEY=re_...

Never commit .env or .env.local files to version control. These files are already in .gitignore.

Google OAuth configuration

To enable Google sign-in:

Create OAuth credentials in Google Cloud Console
Add authorized redirect URI: http://127.0.0.1:54321/auth/v1/callback
Copy Client ID and Secret

Edit packages/app/supabase/config.toml:

[auth.external.google]
enabled = true
client_id = "env(GOOGLE_CLIENT_ID)"
secret = "env(GOOGLE_CLIENT_SECRET)"
redirect_uri = "http://127.0.0.1:54321/auth/v1/callback"

Restart Supabase:

cd packages/app
supabase stop
supabase start
cd ../..

Step 9: Start the development environment

Run all services with the unified dev script:

npm run dev

This starts:

Landing page (packages/landing)
- Next.js dev server on http://localhost:3000
- Hot reload enabled
- API routes at /api/*
Main app (packages/app)
- Vite dev server on http://localhost:5173/app/
- Fast HMR (Hot Module Replacement)
- React DevTools compatible
Swagger UI (from docs/api/)
- Auto-assigned port (default: 55027)
- Serves OpenAPI spec at /openapi.yaml
- Interactive API testing

The console shows:

[dev:all] Starting services from /path/to/8Space
[dev:all] Swagger UI: http://127.0.0.1:55027/

Press Ctrl+C in the terminal to stop all services gracefully. The script handles cleanup automatically.

Step 10: Verify the installation

Test your setup:

Open the app: http://localhost:5173/app/
Log in with test account:
- Email: [email protected]
- Password: password123
Explore features:
- Switch between Backlog, Kanban, Timeline, and Dashboard views
- Create a new task
- Drag tasks between columns
- View task dependencies in Timeline
Check Supabase Studio: http://localhost:54323
- Browse tables in Table Editor
- View auth users
- Run SQL queries
Test API docs: http://127.0.0.1:55027
- Browse endpoints in Swagger UI
- Test API calls directly

Production deployment

For production deployment, you’ll need:

Production Supabase project (Supabase Cloud or self-hosted)
Frontend hosting (Vercel, Netlify, or custom server)
Custom domain (optional but recommended)

Create a Supabase project

Create a free account at supabase.com or set up a self-hosted instance.

Create a new project

In the Supabase dashboard:

Click New project
Choose a name and region
Set a strong database password
Wait for provisioning (2-3 minutes)

Run migrations

Link your local project and push migrations:

cd packages/app
supabase link --project-ref your-project-ref
supabase db push

This applies all migrations from supabase/migrations/ to production.

Configure environment variables

Get your production credentials from the Supabase dashboard:

Project Settings > API
Copy Project URL and anon public key

Update your production environment:

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGc...

Deploy to Vercel

8Space is optimized for deployment on Vercel.

Prepare the repository

Commit your changes and push to GitHub:

git add .
git commit -m "Configure for production"
git push origin main

Import project to Vercel

Sign up at vercel.com
Click Add New Project
Import your GitHub repository
Vercel auto-detects the Next.js app in packages/landing

Configure build settings

Set the root directory:

Root Directory: packages/landing
Build Command: npm run build
Output Directory: .next

Add environment variables

In Vercel project settings, add:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGc...
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
RESEND_API_KEY=re_...

Deploy

Click Deploy and wait for the build to complete. Vercel provides a URL: https://your-app.vercel.app

For the React app (packages/app), you’ll need to build and serve it separately or include it in the same deployment with appropriate routing.

Deploy the React app

Build the Vite app for production:

cd packages/app
npm run build

This creates an optimized build in dist/. Serve it with:

Static hosting: Upload dist/ to Netlify, Vercel, or S3 + CloudFront
Custom server: Use Nginx, Apache, or Node.js serve

Example Nginx configuration:

server {
  listen 80;
  server_name app.yourdomain.com;
  root /var/www/8space/app/dist;
  index index.html;

  location /app/ {
    try_files $uri $uri/ /index.html;
  }
}

Database management

Creating migrations

When you modify the database schema:

cd packages/app
supabase migration new your_migration_name

This creates a new file in supabase/migrations/ with a timestamp prefix. Edit the file to add your SQL changes:

-- Example: Add a new column
alter table public.tasks add column estimated_hours numeric(10, 2);

Apply the migration locally:

supabase db reset

Rolling back migrations

To undo the last migration:

supabase migration repair --status reverted <timestamp>_migration_name
supabase db reset

Viewing migration status

Check which migrations are applied:

supabase migration list

Troubleshooting

Docker daemon not running

Error: Cannot connect to the Docker daemonSolution:

# macOS: Start Docker Desktop
open -a Docker

# Linux: Start Docker service
sudo systemctl start docker

Port conflicts

Error: Port 54321 is already in useSolution: Stop conflicting services or change ports in packages/app/supabase/config.toml:

[api]
port = 54325  # Change to available port

Then update your .env file accordingly.

Migration failures

Error: Migration failed: relation already existsSolution: Reset the database completely:

cd packages/app
supabase db reset --no-seed  # Skip seed data
# Or fully destroy and recreate:
supabase stop
docker volume prune -f
supabase start
supabase db reset

Authentication errors

Error: Invalid JWT or User not foundSolution:

Verify VITE_SUPABASE_ANON_KEY matches supabase status output

Check packages/app/supabase/config.toml has:

[auth.email]
enable_confirmations = false

Clear browser localStorage and cookies

Restart Supabase:

cd packages/app
supabase stop
supabase start

npm install fails

Error: ERESOLVE unable to resolve dependency treeSolution:

# Clear cache
npm cache clean --force

# Remove all node_modules
rm -rf node_modules package-lock.json
rm -rf packages/*/node_modules packages/*/package-lock.json

# Reinstall with legacy peer deps
npm install --legacy-peer-deps

Vite build errors

Error: Transform failed with 1 error or Cannot find moduleSolution:

Clear Vite cache:
```
rm -rf packages/app/node_modules/.vite
```
Restart dev server
Check TypeScript errors:
```
cd packages/app
npm run build
```

Advanced configuration

Custom Supabase configuration

Edit packages/app/supabase/config.toml to customize:

[db]
port = 54322
max_rows = 5000  # Increase API row limit

[auth]
jwt_expiry = 7200  # 2-hour sessions
enable_signup = false  # Disable public registration

[storage]
file_size_limit = "100MiB"  # Increase upload limit

Restart Supabase after changes:

cd packages/app
supabase stop
supabase start

Environment-specific configurations

Use different .env files for each environment:

.env.local          # Local development (gitignored)
.env.staging        # Staging environment
.env.production     # Production (never commit!)

Load them based on NODE_ENV:

// vite.config.ts
import { loadEnv } from 'vite'

export default ({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '')
  // Use env.VITE_SUPABASE_URL etc.
}

Next steps

Configuration

Learn about all available environment variables and configuration options.

Database schema

Deep dive into the PostgreSQL schema and data relationships.

Authentication

Set up email, Google OAuth, and other authentication providers.

API reference

Explore the REST API and integrate with external services.

Get Started

Core Features

Configuration

Architecture

Installation Guide

Overview

System requirements

Required software

Optional software

Operating system support

Installation methods

Local development setup

Step 1: Install Node.js and npm

Step 2: Install Supabase CLI

Step 3: Install Docker

Step 4: Clone the repository

Step 5: Install dependencies

Step 6: Configure Supabase

Step 7: Apply migrations and seed data

Step 8: Configure environment variables

Step 9: Start the development environment

Step 10: Verify the installation

Production deployment

Create a Supabase project

Deploy to Vercel

Deploy the React app

Database management

Creating migrations

Rolling back migrations

Viewing migration status

Troubleshooting

Advanced configuration

Custom Supabase configuration

Environment-specific configurations

Next steps

Configuration

Database schema

Authentication

API reference

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Architecture

​Overview

​System requirements

​Required software

​Optional software

​Operating system support

​Installation methods

​Local development setup

​Step 1: Install Node.js and npm

​Step 2: Install Supabase CLI

​Step 3: Install Docker

​Step 4: Clone the repository

​Step 5: Install dependencies

​Step 6: Configure Supabase

​Step 7: Apply migrations and seed data

​Step 8: Configure environment variables

​Step 9: Start the development environment

​Step 10: Verify the installation

​Production deployment

​Create a Supabase project

​Deploy to Vercel

​Deploy the React app

​Database management

​Creating migrations

​Rolling back migrations

​Viewing migration status

​Troubleshooting

​Advanced configuration

​Custom Supabase configuration

​Environment-specific configurations

​Next steps

Configuration

Database schema

Authentication

API reference

Build docs developers (and LLMs) love

Overview

System requirements

Required software

Optional software

Operating system support

Installation methods

Local development setup

Step 1: Install Node.js and npm

Step 2: Install Supabase CLI

Step 3: Install Docker

Step 4: Clone the repository

Step 5: Install dependencies

Step 6: Configure Supabase

Step 7: Apply migrations and seed data

Step 8: Configure environment variables

Step 9: Start the development environment

Step 10: Verify the installation

Production deployment

Create a Supabase project

Deploy to Vercel

Deploy the React app

Database management

Creating migrations

Rolling back migrations

Viewing migration status

Troubleshooting

Advanced configuration

Custom Supabase configuration

Environment-specific configurations

Next steps