Spaces

Spaces is a web app that creates secure cloud based development enviorments, accessible through a web browser. The goal of this project is to allow people to create amazing projects no matter what hardware they have access to. Spaces was developed by Ivie Fonner, Arnav and Hack Club

Setup:

Manual Setup:

Prerequisites:

Before installing, you must have:

• Docker installed and the daemon running
• Node.js (v18.x or higher) and npm installed
• PostgreSQL database set up and accessible
• Airtable account with API key and base ID for email verification

Installation:

git clone https://github.com/hackclub/spaces-new.git

cp example.env .env # fill out the .env

npm install

npm run client-install

# run both client and server
npm run dev

# run only backend
npm run serve:server

# run only client 
npm run serve:client

Docker Setup:

Prerequisites:

Before installing, you must have:

• Docker and docker-compose installed and the daemon running
• PostgreSQL database set up and accessible
• Airtable account with API key and base ID for email verification

Installation:

git clone https://github.com/hackclub/spaces-new.git

cp example.env .env # make sure to set DOCKER=true

docker compose up --build
# server is now live at localhost:2593

.env setup:

# postgres database connection 
PG_CONNECTION_STRING=your-postgres-db-url
# airtable credentials for email otps
AIRTABLE_API_KEY=your-airtable-pat
AIRTABLE_BASE_ID=your-airtable-base-id

# Server configuration
PORT=3000
NODE_ENV=development

# Frontend configuration
FRONTEND_URL=http://localhost:5173

# Server URL for container access URLs
SERVER_URL=http://localhost

# Set to 'true' if running in Docker, 'false' for manual setup
DOCKER=false

Required Environment Variables:

• PG_CONNECTION_STRING - PostgreSQL database connection URL
• AIRTABLE_API_KEY - Airtable API key for email verification
• AIRTABLE_BASE_ID - Airtable base ID for storing verification codes
• PORT - Backend server port (default: 3000)
• DOCKER - Must be 'true' for Docker setup, 'false' for manual setup
• SERVER_URL - Base URL for container access (e.g., http://localhost or your domain)
• FRONTEND_URL - Frontend URL for CORS (default: http://localhost:5173)
• NODE_ENV - Environment mode: 'development' or 'production'

API Documentation:

By default the API will be accessible at /api/v1

Authentication

All API endpoints that require authentication expect an authorization token in the request headers or body. This token is obtained during login/signup and must be included in subsequent requests.

Users API (/api/v1/users)

Send Verification Code

• POST /api/v1/users/send
• Description: Send a verification code to the provided email address
• Body:

  {
    "email": "user@example.com"
  }

• Response:

  {
    "success": true,
    "message": "Verification code sent successfully",
    "data": {
      "email": "user@example.com"
    }
  }

Sign Up

• POST /api/v1/users/signup
• Description: Create a new user account with email verification
• Body:

  {
    "email": "user@example.com",
    "username": "myusername",
    "verificationCode": "123456"
  }

• Response:

  {
    "success": true,
    "message": "User created successfully",
    "data": {
      "id": 1,
      "email": "user@example.com",
      "username": "myusername",
      "authorization": "auth_token_here"
    }
  }

Login

• POST /api/v1/users/login
• Description: Login with email and verification code
• Body:

  {
    "email": "user@example.com",
    "code": "123456"
  }

• Response:

  {
    "success": true,
    "message": "Login successful",
    "data": {
      "email": "user@example.com",
      "username": "myusername",
      "authorization": "new_auth_token_here"
    }
  }

Sign Out

• POST /api/v1/users/signout
• Description: Sign out and invalidate the current authorization token
• Body:

  {
    "authorization": "current_auth_token"
  }

• Response:

  {
    "success": true,
    "message": "Sign out successful",
    "data": {
      "email": "user@example.com"
    }
  }

Spaces API (/api/v1/spaces)

Create Container

• POST /api/v1/spaces/create
• Description: Create a new containerized workspace
• Headers:
  • authorization: your_auth_token
• Body:

  {
    "password": "container_password",
    "type": "code-server"
  }

• Valid Types: code-server, blender, kicad
• Response:

  {
    "message": "Container created successfully",
    "spaceId": 1,
    "containerId": "docker_container_id",
    "type": "code-server",
    "description": "VS Code Server",
    "image": "linuxserver/code-server",
    "port": 8080,
    "accessUrl": "http://localhost:8080"
  }

Start Container

• POST /api/v1/spaces/start/:spaceId
• Description: Start an existing container
• Headers:
  • authorization: your_auth_token
• Parameters:
  • spaceId: The ID of the space to start
• Response:

  {
    "message": "Container started successfully",
    "spaceId": 1,
    "containerId": "docker_container_id"
  }

Stop Container

• POST /api/v1/spaces/stop/:spaceId
• Description: Stop a running container
• Headers:
  • authorization: your_auth_token
• Parameters:
  • spaceId: The ID of the space to stop
• Response:

  {
    "message": "Container stopped successfully",
    "spaceId": 1,
    "containerId": "docker_container_id"
  }

Get Container Status

• GET /api/v1/spaces/status/:spaceId
• Description: Get the current status of a container
• Headers:
  • authorization: your_auth_token
• Parameters:
  • spaceId: The ID of the space to check
• Response:

  {
    "spaceId": 1,
    "containerId": "docker_container_id",
    "type": "code-server",
    "description": "VS Code Server",
    "accessUrl": "http://localhost:8080",
    "status": "running",
    "running": true,
    "startedAt": "2023-01-01T00:00:00.000Z",
    "finishedAt": "0001-01-01T00:00:00Z"
  }

List User Spaces

• GET /api/v1/spaces/list
• Description: Get all spaces owned by the authenticated user
• Headers:
  • authorization: your_auth_token
• Response:

  {
    "message": "Spaces retrieved successfully",
    "spaces": [
      {
        "id": 1,
        "type": "code-server",
        "description": "VS Code Server",
        "image": "linuxserver/code-server",
        "port": 8080,
        "access_url": "http://localhost:8080",
        "created_at": "2023-01-01T00:00:00.000Z"
      }
    ]
  }

Container Types

Type	Description	Image
code-server	VS Code Server	linuxserver/code-server
blender	Blender 3D	linuxserver/blender
kicad	KiCad PCB Design	linuxserver/kicad

Error Responses

All endpoints return consistent error responses:

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error (development only)"
}

Common HTTP status codes:

• 400: Bad Request (missing/invalid parameters)
• 401: Unauthorized (invalid/missing auth token)
• 404: Not Found (resource doesn't exist)
• 409: Conflict (duplicate email/username)
• 500: Internal Server Error