Skip to main content

​
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)
  • Git for cloning the repository
Verify your installations:
node --version
npm --version
supabase --version

​
Quick setup

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

Clone and install dependencies

Clone the repository and install all workspace dependencies from the project root:
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.
The monorepo uses npm workspaces to manage dependencies across multiple packages efficiently.
2

Start Supabase and initialize database

Navigate to the app package and start the local Supabase instance:
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
Save the anon key and service_role key from the output. You’ll need the anon key for the next step.
3

Configure environment variables

Create environment files for both packages:For the main app (packages/app/.env):
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:
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=<paste-anon-key-from-step-2>
The landing page environment variables are optional for basic usage. Add Stripe and Resend keys only if you’re testing billing or email features.
You can copy from the example files:
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.
4

Start the development environment

From the project root, start all services with a single command:
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/
You can also run services separately:
npm run dev:landing  # Landing page only
npm run dev:app      # Main app only
npm run dev:swagger  # Swagger UI only

​
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 
Email: [email protected]
Password: password123
Role: Owner (full access)

​
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
Try switching between the Backlog, Kanban, Timeline, and Dashboard views using the top navigation.

​
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

If you see “port already in use” errors:For Supabase:
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:
SWAGGER_PORT=55028 npm run dev
If the app can’t connect to Supabase:
  1. Verify Supabase is running: 
    supabase status
  2. Check your .env file has the correct URL and anon key
  3. Restart Supabase: 
    cd packages/app
supabase stop
supabase start
cd ../..
If you can’t log in with the test accounts:
  1. Reset the database to re-seed data: 
    cd packages/app
supabase db reset
cd ../..
  2. Verify the email confirmations are disabled in packages/app/supabase/config.toml: 
    [auth.email]
enable_confirmations = false
If you encounter errors during npm install:
  1. Clear npm cache: 
    npm cache clean --force
  2. Delete lock files and node_modules: 
    rm -rf node_modules package-lock.json
rm -rf packages/*/node_modules packages/*/package-lock.json
  3. Reinstall: 
    npm install

​
Next steps

Now that you have 8Space running locally:

Installation guide

Learn about advanced setup options, production deployment, and troubleshooting.

Configuration

Configure authentication providers, enable billing, and customize settings.

Database schema

Understand the database structure and relationships.

API reference

Explore the API endpoints and integrate with external tools.

​
Development workflow tips

Hot reload: Both Vite and Next.js support hot module replacement (HMR). Changes to source files will automatically reload in your browser.
Database changes: After modifying the schema, create a new migration:
cd packages/app
supabase migration new your_migration_name
Then apply it with supabase db reset.
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:
cd packages/app
supabase stop

Build docs developers (and LLMs) love

Get started for freeTalk to us