> ## Documentation Index
> Fetch the complete documentation index at: https://docs.8space.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation Guide

> Comprehensive installation and setup instructions for 8Space local development and production deployment

## Overview

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

<Info>
  For a faster getting started experience, see the [Quickstart](/quickstart) guide.
</Info>

## 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

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

## Installation methods

Choose the installation method that fits your needs:

<Tabs>
  <Tab title="Local development">
    Complete setup for local development with hot reload and debugging.
  </Tab>

  <Tab title="Production (self-hosted)">
    Deploy 8Space to your own infrastructure with a production Supabase instance.
  </Tab>

  <Tab title="Docker">
    Run 8Space in containers for isolated development or deployment.
  </Tab>
</Tabs>

## Local development setup

Follow these steps for a complete local development environment.

### Step 1: Install Node.js and npm

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install node@20
  ```

  ```bash Ubuntu/Debian theme={null}
  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  sudo apt-get install -y nodejs
  ```

  ```bash Windows (WSL2) theme={null}
  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  sudo apt-get install -y nodejs
  ```
</CodeGroup>

Verify installation:

```bash theme={null}
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

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install supabase/tap/supabase
  ```

  ```bash Linux/WSL2 theme={null}
  brew install supabase/tap/supabase
  # Or using npm:
  npm install -g supabase
  ```

  ```bash Direct binary download theme={null}
  # Download from GitHub releases
  wget https://github.com/supabase/cli/releases/latest/download/supabase_linux_amd64.tar.gz
  tar -xzf supabase_linux_amd64.tar.gz
  sudo mv supabase /usr/local/bin/
  ```
</CodeGroup>

Verify installation:

```bash theme={null}
supabase --version  # Should show v1.50.0 or higher
```

### Step 3: Install Docker

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

<CodeGroup>
  ```bash macOS theme={null}
  # Download Docker Desktop from:
  https://www.docker.com/products/docker-desktop

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

  ```bash Ubuntu/Debian theme={null}
  sudo apt-get update
  sudo apt-get install -y docker.io docker-compose
  sudo systemctl start docker
  sudo systemctl enable docker
  sudo usermod -aG docker $USER
  ```

  ```bash Windows (WSL2) theme={null}
  # Install Docker Desktop for Windows with WSL2 backend:
  https://docs.docker.com/desktop/windows/wsl/
  ```
</CodeGroup>

Verify Docker is running:

```bash theme={null}
docker --version
docker ps  # Should not show errors
```

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

### Step 4: Clone the repository

Clone 8Space from GitHub:

```bash theme={null}
git clone https://github.com/AndreyMishurin/8Space.git
cd 8Space
```

Check the repository structure:

```bash theme={null}
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:

```bash theme={null}
npm install
```

This installs dependencies for:

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

<Accordion title="Understanding npm workspaces">
  The root `package.json` defines a workspace:

  ```json theme={null}
  {
    "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:

  ```bash theme={null}
  npm run dev -w packages/landing  # Run landing dev server only
  ```
</Accordion>

### Step 6: Configure Supabase

Initialize and start the local Supabase instance:

```bash theme={null}
cd packages/app
supabase start
```

<Accordion title="What happens during supabase start?">
  The CLI:

  1. 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)

  2. Starts containers with ports:
     * `54321` - API Gateway
     * `54322` - PostgreSQL direct connection
     * `54323` - Supabase Studio
     * `55324` - Inbucket (email testing)

  3. Outputs connection details:
     ```
     API URL: http://127.0.0.1:54321
     anon key: eyJhbGc...
     service_role key: eyJhbGc...
     ```

  4. Applies migrations from `supabase/migrations/`
</Accordion>

**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:

```bash theme={null}
supabase db reset
cd ../..
```

This command:

1. Drops and recreates the database
2. 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
3. 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

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

### Step 8: Configure environment variables

Create environment files for both packages.

**App environment** (`packages/app/.env`):

```bash theme={null}
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`):

```bash theme={null}
# 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_...
```

<Warning>
  Never commit `.env` or `.env.local` files to version control. These files are already in `.gitignore`.
</Warning>

<Accordion title="Google OAuth configuration">
  To enable Google sign-in:

  1. Create OAuth credentials in [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
  2. Add authorized redirect URI: `http://127.0.0.1:54321/auth/v1/callback`
  3. Copy Client ID and Secret
  4. Edit `packages/app/supabase/config.toml`:
     ```toml theme={null}
     [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"
     ```
  5. Restart Supabase:
     ```bash theme={null}
     cd packages/app
     supabase stop
     supabase start
     cd ../..
     ```
</Accordion>

### Step 9: Start the development environment

Run all services with the unified dev script:

```bash theme={null}
npm run dev
```

This starts:

1. **Landing page** (`packages/landing`)
   * Next.js dev server on `http://localhost:3000`
   * Hot reload enabled
   * API routes at `/api/*`

2. **Main app** (`packages/app`)
   * Vite dev server on `http://localhost:5173/app/`
   * Fast HMR (Hot Module Replacement)
   * React DevTools compatible

3. **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/
```

<Tip>
  Press `Ctrl+C` in the terminal to stop all services gracefully. The script handles cleanup automatically.
</Tip>

### Step 10: Verify the installation

Test your setup:

1. **Open the app**: `http://localhost:5173/app/`

2. **Log in** with test account:
   * Email: `owner@gantt.local`
   * Password: `password123`

3. **Explore features**:
   * Switch between Backlog, Kanban, Timeline, and Dashboard views
   * Create a new task
   * Drag tasks between columns
   * View task dependencies in Timeline

4. **Check Supabase Studio**: `http://localhost:54323`
   * Browse tables in Table Editor
   * View auth users
   * Run SQL queries

5. **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:

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

### Create a Supabase project

<Steps>
  <Step title="Sign up for Supabase">
    Create a free account at [supabase.com](https://supabase.com) or set up a self-hosted instance.
  </Step>

  <Step title="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)
  </Step>

  <Step title="Run migrations">
    Link your local project and push migrations:

    ```bash theme={null}
    cd packages/app
    supabase link --project-ref your-project-ref
    supabase db push
    ```

    This applies all migrations from `supabase/migrations/` to production.
  </Step>

  <Step title="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:

    ```bash theme={null}
    VITE_SUPABASE_URL=https://your-project.supabase.co
    VITE_SUPABASE_ANON_KEY=eyJhbGc...
    ```
  </Step>
</Steps>

### Deploy to Vercel

8Space is optimized for deployment on Vercel.

<Steps>
  <Step title="Prepare the repository">
    Commit your changes and push to GitHub:

    ```bash theme={null}
    git add .
    git commit -m "Configure for production"
    git push origin main
    ```
  </Step>

  <Step title="Import project to Vercel">
    1. Sign up at [vercel.com](https://vercel.com)
    2. Click **Add New Project**
    3. Import your GitHub repository
    4. Vercel auto-detects the Next.js app in `packages/landing`
  </Step>

  <Step title="Configure build settings">
    Set the root directory:

    * **Root Directory**: `packages/landing`
    * **Build Command**: `npm run build`
    * **Output Directory**: `.next`
  </Step>

  <Step title="Add environment variables">
    In Vercel project settings, add:

    ```bash theme={null}
    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_...
    ```
  </Step>

  <Step title="Deploy">
    Click **Deploy** and wait for the build to complete.
    Vercel provides a URL: `https://your-app.vercel.app`
  </Step>
</Steps>

<Note>
  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.
</Note>

### Deploy the React app

Build the Vite app for production:

```bash theme={null}
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:

```nginx theme={null}
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:

```bash theme={null}
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:

```sql theme={null}
-- Example: Add a new column
alter table public.tasks add column estimated_hours numeric(10, 2);
```

Apply the migration locally:

```bash theme={null}
supabase db reset
```

### Rolling back migrations

To undo the last migration:

```bash theme={null}
supabase migration repair --status reverted <timestamp>_migration_name
supabase db reset
```

### Viewing migration status

Check which migrations are applied:

```bash theme={null}
supabase migration list
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Docker daemon not running" icon="docker">
    **Error**: `Cannot connect to the Docker daemon`

    **Solution**:

    ```bash theme={null}
    # macOS: Start Docker Desktop
    open -a Docker

    # Linux: Start Docker service
    sudo systemctl start docker
    ```
  </Accordion>

  <Accordion title="Port conflicts" icon="circle-exclamation">
    **Error**: `Port 54321 is already in use`

    **Solution**: Stop conflicting services or change ports in `packages/app/supabase/config.toml`:

    ```toml theme={null}
    [api]
    port = 54325  # Change to available port
    ```

    Then update your `.env` file accordingly.
  </Accordion>

  <Accordion title="Migration failures" icon="database">
    **Error**: `Migration failed: relation already exists`

    **Solution**: Reset the database completely:

    ```bash theme={null}
    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
    ```
  </Accordion>

  <Accordion title="Authentication errors" icon="shield-halved">
    **Error**: `Invalid JWT` or `User not found`

    **Solution**:

    1. Verify `VITE_SUPABASE_ANON_KEY` matches `supabase status` output
    2. Check `packages/app/supabase/config.toml` has:
       ```toml theme={null}
       [auth.email]
       enable_confirmations = false
       ```
    3. Clear browser localStorage and cookies
    4. Restart Supabase:
       ```bash theme={null}
       cd packages/app
       supabase stop
       supabase start
       ```
  </Accordion>

  <Accordion title="npm install fails" icon="npm">
    **Error**: `ERESOLVE unable to resolve dependency tree`

    **Solution**:

    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Vite build errors" icon="react">
    **Error**: `Transform failed with 1 error` or `Cannot find module`

    **Solution**:

    1. Clear Vite cache:
       ```bash theme={null}
       rm -rf packages/app/node_modules/.vite
       ```
    2. Restart dev server
    3. Check TypeScript errors:
       ```bash theme={null}
       cd packages/app
       npm run build
       ```
  </Accordion>
</AccordionGroup>

## Advanced configuration

### Custom Supabase configuration

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

```toml theme={null}
[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:

```bash theme={null}
cd packages/app
supabase stop
supabase start
```

### Environment-specific configurations

Use different `.env` files for each environment:

```bash theme={null}
.env.local          # Local development (gitignored)
.env.staging        # Staging environment
.env.production     # Production (never commit!)
```

Load them based on `NODE_ENV`:

```javascript theme={null}
// vite.config.ts
import { loadEnv } from 'vite'

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

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration/environment-variables">
    Learn about all available environment variables and configuration options.
  </Card>

  <Card title="Database schema" icon="database" href="/architecture/database-schema">
    Deep dive into the PostgreSQL schema and data relationships.
  </Card>

  <Card title="Authentication" icon="shield-halved" href="/configuration/authentication">
    Set up email, Google OAuth, and other authentication providers.
  </Card>

  <Card title="API reference" icon="code" href="/api/overview">
    Explore the REST API and integrate with external services.
  </Card>
</CardGroup>