Skip to content

Latest commit

 

History

History
414 lines (292 loc) · 8.21 KB

QUICKSTART.md

File metadata and controls

414 lines (292 loc) · 8.21 KB

SkillSpark Quick Start Guide

This guide will help you get started with the SkillSpark project quickly.

Table of Contents

Prerequisites

Before you begin, ensure you have the following installed on your system:

Required Software

  1. Docker & Docker Compose

  2. Node.js

    • Version: 18.x or higher
    • Download from: https://nodejs.org/
    • Verify installation: 
      node --version
npm --version

  3. Bun (JavaScript runtime & package manager)

  4. Go (Golang)

    • Version: 1.24.0 or higher
    • Download from: https://go.dev/dl/
    • Verify installation: 
      go version

  5. Supabase CLI (for database management)

  6. Make (build automation)

    • Linux: Usually pre-installed
    • macOS: Install Xcode Command Line Tools 
      xcode-select --install
    • Windows: Install via Chocolatey 
      choco install make

VS Code Setup

Recommended Extensions

Install these essential VS Code extensions for the best development experience:

  1. Go (golang.go)

    • Official Go language support
    • Provides IntelliSense, debugging, and testing

  2. ESLint (dbaeumer.vscode-eslint)

    • JavaScript/TypeScript linting
    • Auto-fix on save

  3. Prettier - Code formatter (esbenp.prettier-vscode)

    • Consistent code formatting
    • Works with JavaScript, TypeScript, JSON, CSS, etc.

  4. Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)

    • Autocomplete for Tailwind classes
    • Syntax highlighting

  5. Docker (ms-azuretools.vscode-docker)

    • Manage Docker containers and images
    • View logs and inspect containers

Installation

  1. Clone the repository (if you haven't already):

    git clone <repository-url>
cd skillspark

  2. Set up environment variables for backend:

    cd backend
cp env.sample .env

    Edit .env and fill in the required values:

Running the Application

Option 1: Using Docker (Recommended)

This is the easiest way to run both frontend and backend together.

Start All Services

make up

This command will:

  • Build both frontend and backend Docker images
  • Start the containers with hot reload enabled
  • Set up networking between services

Access your application:

View Logs

# All services
make logs

# Backend only
make logs-backend

# Frontend only
make logs-frontend

Stop All Services

# Stop and remove containers
make down

# Stop without removing (preserves state)
make stop

Restart Services

make restart

Option 2: Running Services Independently

For development, you might want to run services separately for more control.

Running Backend Independently

  1. Navigate to backend directory:

    cd backend

  2. Install Go dependencies:

    make deps

  3. Start local Supabase (PostgreSQL database):

    make db-start

    This will start a local Supabase instance on Docker. Note the database URL:

  4. Apply database migrations:

    make db-reset

  5. Run the backend server:

    make dev

    The backend will be available at http://localhost:8080

Backend Commands:

make help              # Show all available commands
make test              # Run all tests
make lint              # Run linter
make format            # Format code
make db-status         # Check database status

Running Frontend Independently

  1. Navigate to frontend directory:

    cd frontend/web

  2. Install dependencies:

    bun install

  3. Start the development server:

    make dev
# or directly:
bun run dev

    The frontend will be available at http://localhost:5173

Frontend Commands:

make help              # Show all available commands
make build             # Build for production
make lint              # Run ESLint
make format            # Format code with Prettier
make type-check        # Run TypeScript type checking

Running with Docker (Individual Services)

Backend only:

# From project root
make up-backend

Frontend only:

# From project root
make up-frontend

Verification

Check if Everything is Running

  1. Check Docker containers (if using Docker):

    make ps

    You should see both backend and web-frontend containers running.

  2. Test the backend:

    curl http://localhost:8080

  3. Test the frontend:

  4. Check API documentation:

Run Tests

Backend tests:

cd backend
make test

Frontend tests:

cd frontend/web
bun test

Available Commands

Root Level Commands (Docker)

make help              # Show all available commands
make up                # Start all services with hot reload
make down              # Stop and remove all containers
make restart           # Restart all services
make logs              # View logs from all services
make build             # Build all services
make up-backend        # Start only backend
make up-frontend       # Start only frontend
make clean             # Remove containers and volumes

Backend Commands

cd backend
make help              # Show all available backend commands
make dev               # Run development server
make test              # Run all tests
make lint              # Run linter
make format            # Format code
make db-start          # Start local Supabase
make db-stop           # Stop local Supabase
make db-reset          # Reset database and apply migrations
make db-new NAME=...   # Create new migration
make api-gen           # Generate OpenAPI spec

Frontend Commands

cd frontend/web
make help              # Show all available frontend commands
make dev               # Start development server
make build             # Build for production
make preview           # Preview production build
make lint              # Run ESLint
make format            # Format code with Prettier
make type-check        # Run TypeScript type checking
make check             # Run all checks (type, lint, format)
make fix               # Fix all issues

Troubleshooting

  1. Check the logs: make logs
  2. Read the documentation in docs/ folder
  3. Check existing GitHub issues
  4. Ask the team on your communication channel

Next Steps

Reach out to your TLs if you have any issues <3