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

# Quickstart

> Get 8Space running locally in under 5 minutes with this express setup guide

## Prerequisites

Before starting, ensure you have the following installed:

* **Node.js** 18 or higher
* **npm** 8 or higher (comes with Node.js)
* **Supabase CLI** ([installation guide](https://supabase.com/docs/guides/cli))
* **Git** for cloning the repository

<Tip>
  Verify your installations:

  ```bash theme={null}
  node --version
  npm --version
  supabase --version
  ```
</Tip>

## Quick setup

Follow these four steps to get 8Space running on your local machine.

<Steps>
  <Step title="Clone and install dependencies">
    Clone the repository and install all workspace dependencies from the project root:

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

    This installs dependencies for both the landing page and the main app using npm workspaces.

    <Note>
      The monorepo uses npm workspaces to manage dependencies across multiple packages efficiently.
    </Note>
  </Step>

  <Step title="Start Supabase and initialize database">
    Navigate to the app package and start the local Supabase instance:

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

    The `supabase start` command:

    * Downloads Docker containers for PostgreSQL, Auth, Storage, and more
    * Starts services on predefined ports (API: 54321, DB: 54322, Studio: 54323)
    * Outputs connection details including the `anon key`

    The `supabase db reset` command:

    * Applies all migrations from `packages/app/supabase/migrations/`
    * Seeds the database with test data from `packages/app/supabase/seed.sql`
    * Creates three test accounts with sample project data

    <Warning>
      Save the `anon key` and `service_role key` from the output. You'll need the anon key for the next step.
    </Warning>
  </Step>

  <Step title="Configure environment variables">
    Create environment files for both packages:

    **For the main app** (`packages/app/.env`):

    ```bash theme={null}
    VITE_SUPABASE_URL=http://127.0.0.1:54321
    VITE_SUPABASE_ANON_KEY=<paste-anon-key-from-step-2>
    ```

    **For the landing page** (`packages/landing/.env.local`) - optional:

    ```bash theme={null}
    NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
    NEXT_PUBLIC_SUPABASE_ANON_KEY=<paste-anon-key-from-step-2>
    ```

    <Info>
      The landing page environment variables are optional for basic usage. Add Stripe and Resend keys only if you're testing billing or email features.
    </Info>

    You can copy from the example files:

    ```bash theme={null}
    cp packages/app/.env.example packages/app/.env
    cp packages/landing/.env.example packages/landing/.env.local
    ```

    Then edit the files to add your actual anon key.
  </Step>

  <Step title="Start the development environment">
    From the project root, start all services with a single command:

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

    This orchestrator script (`scripts/dev-all.mjs`) starts:

    * **Landing page** at `http://localhost:3000` (Next.js dev server)
    * **Main app** at `http://localhost:5173/app/` (Vite dev server)
    * **Swagger UI** at a dynamically-assigned port (printed in console)

    The console output will show:

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

    <Accordion title="Individual service commands">
      You can also run services separately:

      ```bash theme={null}
      npm run dev:landing  # Landing page only
      npm run dev:app      # Main app only
      npm run dev:swagger  # Swagger UI only
      ```
    </Accordion>
  </Step>
</Steps>

## Test your installation

Once all services are running, verify your setup:

### Access the application

1. Open `http://localhost:5173/app/` in your browser
2. You should see the 8Space login page

### Log in with test accounts

The seed data creates three test accounts. All use the password: `password123`

<CodeGroup>
  ```bash Owner account theme={null}
  Email: owner@gantt.local
  Password: password123
  Role: Owner (full access)
  ```

  ```bash Editor account theme={null}
  Email: editor@gantt.local
  Password: password123
  Role: Editor (can create/edit tasks)
  ```

  ```bash Viewer account theme={null}
  Email: viewer@gantt.local
  Password: password123
  Role: Viewer (read-only)
  ```
</CodeGroup>

### Explore the demo project

After logging in, you'll see the "Product Launch Q2" demo project with:

* **5 sample tasks** across different workflow columns
* **Task dependencies** demonstrating the timeline view
* **Labels and priorities** for task organization
* **Multiple assignees** showing collaboration features

<Tip>
  Try switching between the Backlog, Kanban, Timeline, and Dashboard views using the top navigation.
</Tip>

## Verify database connection

You can also access Supabase Studio to inspect the database:

1. Open `http://localhost:54323` in your browser
2. Navigate to the **Table Editor** to see your data
3. Check the **Authentication** section for user accounts
4. View **Database** > **Migrations** to see applied schema changes

## Common issues

<AccordionGroup>
  <Accordion title="Port already in use" icon="circle-exclamation">
    If you see "port already in use" errors:

    **For Supabase**:

    ```bash theme={null}
    supabase stop
    supabase start
    ```

    **For dev servers**: Kill the process using the port or change ports in the respective config files.

    **For Swagger UI**: Set a custom port:

    ```bash theme={null}
    SWAGGER_PORT=55028 npm run dev
    ```
  </Accordion>

  <Accordion title="Supabase connection failed" icon="circle-exclamation">
    If the app can't connect to Supabase:

    1. Verify Supabase is running:
       ```bash theme={null}
       supabase status
       ```

    2. Check your `.env` file has the correct URL and anon key

    3. Restart Supabase:
       ```bash theme={null}
       cd packages/app
       supabase stop
       supabase start
       cd ../..
       ```
  </Accordion>

  <Accordion title="Login fails with test accounts" icon="circle-exclamation">
    If you can't log in with the test accounts:

    1. Reset the database to re-seed data:
       ```bash theme={null}
       cd packages/app
       supabase db reset
       cd ../..
       ```

    2. Verify the email confirmations are disabled in `packages/app/supabase/config.toml`:
       ```toml theme={null}
       [auth.email]
       enable_confirmations = false
       ```
  </Accordion>

  <Accordion title="npm install errors" icon="circle-exclamation">
    If you encounter errors during `npm install`:

    1. Clear npm cache:
       ```bash theme={null}
       npm cache clean --force
       ```

    2. Delete lock files and node\_modules:
       ```bash theme={null}
       rm -rf node_modules package-lock.json
       rm -rf packages/*/node_modules packages/*/package-lock.json
       ```

    3. Reinstall:
       ```bash theme={null}
       npm install
       ```
  </Accordion>
</AccordionGroup>

## Next steps

Now that you have 8Space running locally:

<CardGroup cols={2}>
  <Card title="Installation guide" icon="download" href="/installation">
    Learn about advanced setup options, production deployment, and troubleshooting.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/environment-variables">
    Configure authentication providers, enable billing, and customize settings.
  </Card>

  <Card title="Database schema" icon="database" href="/architecture/database-schema">
    Understand the database structure and relationships.
  </Card>

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

## Development workflow tips

<Note>
  **Hot reload**: Both Vite and Next.js support hot module replacement (HMR). Changes to source files will automatically reload in your browser.
</Note>

<Tip>
  **Database changes**: After modifying the schema, create a new migration:

  ```bash theme={null}
  cd packages/app
  supabase migration new your_migration_name
  ```

  Then apply it with `supabase db reset`.
</Tip>

<Warning>
  **Stopping services**: Press `Ctrl+C` in the terminal running `npm run dev` to stop all services gracefully. Supabase runs in the background and must be stopped separately:

  ```bash theme={null}
  cd packages/app
  supabase stop
  ```
</Warning>