SafeSpace Setup Guide

Complete installation and development setup guide for SafeSpace
Last Updated: 2026

Prerequisites
Installation
Environment Configuration
Development Server
Database Setup (SpacetimeDB)
AI Integration (Gemini)
Build & Deployment
Troubleshooting
IDE Setup
Testing

Prerequisites

Required Software

Software	Minimum Version	Recommended	Download
Node.js	18.17.0	20.x LTS	nodejs.org
npm	9.0.0	10.x	Bundled with Node.js
pnpm	8.0.0	9.x	`npm install -g pnpm`
Git	2.30.0	Latest	git-scm.com

Optional Tools

VS Code - Recommended code editor
Spacetime CLI - For SpacetimeDB management
Docker - For containerized development

System Requirements

OS: Windows 10+, macOS 10.15+, Linux (Ubuntu 20.04+)
RAM: 4GB minimum, 8GB recommended
Disk Space: 2GB for dependencies and build artifacts

Installation

1. Clone the Repository

# Using HTTPS
git clone https://github.com/mrbrightsides/safespace.git

# Or using SSH
git clone git@github.com:mrbrightsides/safespace.git

# Navigate to project directory
cd safespace

2. Install Dependencies

Using pnpm (Recommended)

# Install pnpm globally if not already installed
npm install -g pnpm

# Install project dependencies
pnpm install

Using npm

npm install

Using yarn

yarn install

3. Verify Installation

# Check Node.js version
node --version
# Should output: v20.x.x or higher

# Check npm version
npm --version
# Should output: 10.x.x or higher

# Verify all dependencies installed
pnpm list

Environment Configuration

1. Create Environment File

# Copy the example environment file
cp .env.example .env.local

# Or create manually
touch .env.local

2. Configure Environment Variables

Edit .env.local with your configuration:

# ============================================
# SAFESPACE ENVIRONMENT CONFIGURATION
# ============================================

# -------------------------------
# Application Settings
# -------------------------------
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development

# -------------------------------
# SpacetimeDB Configuration
# -------------------------------
NEXT_PUBLIC_SPACETIMEDB_URL=wss://testnet.spacetimedb.com
NEXT_PUBLIC_SPACETIMEDB_MODULE_NAME=safespace_db
# Optional: For production deployment
SPACETIMEDB_AUTH_TOKEN=your_spacetimedb_token_here

# -------------------------------
# AI Configuration (Google Gemini)
# -------------------------------
NEXT_PUBLIC_GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-2.5-flash

# -------------------------------
# Feature Flags
# -------------------------------
NEXT_PUBLIC_ENABLE_DEMO_MODE=true
NEXT_PUBLIC_ENABLE_ANALYTICS=false

# -------------------------------
# Localization
# -------------------------------
NEXT_PUBLIC_DEFAULT_LANGUAGE=en
NEXT_PUBLIC_SUPPORTED_LANGUAGES=en,id

# -------------------------------
# Security
# -------------------------------
# Generate with: openssl rand -base64 32
NEXTAUTH_SECRET=your_nextauth_secret_here
NEXTAUTH_URL=http://localhost:3000

# -------------------------------
# Optional: Third-Party Services
# -------------------------------
# Email service (future feature)
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# SMTP_USER=your_email@example.com
# SMTP_PASSWORD=your_password

3. Obtain API Keys

Google Gemini API Key

Visit Google AI Studio
Sign in with your Google account
Click "Create API Key"
Copy the key to NEXT_PUBLIC_GEMINI_API_KEY in .env.local

SpacetimeDB Setup

Visit SpacetimeDB Cloud
Sign up for a free account
Create a new database module
Copy the WebSocket URL to NEXT_PUBLIC_SPACETIMEDB_URL
Copy the module name to NEXT_PUBLIC_SPACETIMEDB_MODULE_NAME

NextAuth Secret

# Generate a secure random secret
openssl rand -base64 32
# Copy output to NEXTAUTH_SECRET in .env.local

Development Server

1. Start Development Server

# Using pnpm
pnpm dev

# Using npm
npm run dev

# Using yarn
yarn dev

2. Access the Application

Open your browser and navigate to:

Local: http://localhost:3000
Network: http://192.168.x.x:3000 (for mobile testing)

3. Development Commands

# Start development server
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

# Run linter
pnpm lint

# Run type checking
pnpm type-check

# Run tests
pnpm test

# Format code
pnpm format

Database Setup (SpacetimeDB)

1. Install Spacetime CLI

# macOS/Linux
curl -fsSL https://install.spacetimedb.com | bash

# Windows (PowerShell)
iwr https://install.spacetimedb.com/windows | iex

# Verify installation
spacetime version

2. Initialize SpacetimeDB Module

The SafeSpace project uses SpacetimeDB for real-time data synchronization. The database schema is defined in Rust modules.

# Navigate to SpacetimeDB module directory (if exists)
cd spacetime-server

# Build the module
cargo build --release

# Publish to SpacetimeDB Cloud
spacetime publish safespace_db --clear-database

3. Database Schema Overview

The SpacetimeDB module includes the following tables:

reports - Anonymous bullying reports
forum_posts - Community forum discussions
counselor_profiles - Licensed counselor information
crisis_contacts - Emergency hotline contacts
chat_messages - AI chatbot conversation history (optional)

4. Local Development Database

For local development without cloud:

# Start local SpacetimeDB instance
spacetime start

# Publish module locally
spacetime publish safespace_db --server http://localhost:3000

AI Integration (Gemini)

1. Gemini API Setup

SafeSpace uses Google's Gemini 2.5 Flash for the AI chatbot feature.

# Ensure API key is set in .env.local
NEXT_PUBLIC_GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.5-flash

2. Test AI Integration

# Start development server
pnpm dev

# Navigate to chatbot tab
# Open http://localhost:3000 and click "AI Support"
# Send a test message: "Hello, I need help"

3. AI Configuration Options

Edit src/lib/ai-config.ts to customize:

export const aiConfig = {
  model: 'gemini-2.5-flash',
  temperature: 0.7,
  maxTokens: 1024,
  systemPrompt: `You are a compassionate AI assistant for SafeSpace, 
                 an anti-bullying platform. Provide empathetic support...`
};

Build & Deployment

1. Production Build

# Create optimized production build
pnpm build

# Output will be in .next/ directory

2. Test Production Build Locally

# Build first
pnpm build

# Start production server
pnpm start

# Open http://localhost:3000

3. Deployment to Vercel

SafeSpace is optimized for Vercel deployment:

# Install Vercel CLI
npm install -g vercel

# Deploy to Vercel
vercel

# Deploy to production
vercel --prod

Vercel Environment Variables

Add these to your Vercel project settings:

NEXT_PUBLIC_GEMINI_API_KEY
NEXT_PUBLIC_SPACETIMEDB_URL
NEXT_PUBLIC_SPACETIMEDB_MODULE_NAME
NEXTAUTH_SECRET
NEXTAUTH_URL (set to your production domain)

4. Docker Deployment (Optional)

# Build Docker image
docker build -t safespace:latest .

# Run container
docker run -p 3000:3000 --env-file .env.local safespace:latest

Troubleshooting

Common Issues

1. "Module not found" errors

# Clear node_modules and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Clear Next.js cache
rm -rf .next
pnpm dev

2. SpacetimeDB connection failed

# Check WebSocket URL in .env.local
# Ensure no firewall blocking WSS connections
# Verify SpacetimeDB module is published

# Test connection
curl -I https://testnet.spacetimedb.com

3. Gemini API errors

# Verify API key is correct
# Check quota at https://makersuite.google.com
# Ensure model name is correct: gemini-2.5-flash
# Check for rate limiting (wait 60 seconds and retry)

4. TypeScript errors

# Run type check
pnpm type-check

# Regenerate types
rm -rf .next
pnpm dev

5. Port 3000 already in use

# Kill process on port 3000
# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# Or use different port
PORT=3001 pnpm dev

Debug Mode

# Enable verbose logging
DEBUG=* pnpm dev

# Next.js debug mode
NODE_OPTIONS='--inspect' pnpm dev

Getting Help

GitHub Issues: https://github.com/mrbrightsides/safespace/issues
Email: support@elpeef.com
Telegram: @khudriakhmad
Discord: @khudri_61362

IDE Setup

Visual Studio Code (Recommended)

1. Install Extensions

# Essential extensions
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension bradlc.vscode-tailwindcss
code --install-extension ms-vscode.vscode-typescript-next

# Optional but useful
code --install-extension christian-kohler.path-intellisense
code --install-extension streetsidesoftware.code-spell-checker

2. VS Code Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

3. Recommended Snippets

Create .vscode/safespace.code-snippets:

{
  "React Component": {
    "prefix": "rfc",
    "body": [
      "interface ${1:ComponentName}Props {",
      "  $2",
      "}",
      "",
      "export function ${1:ComponentName}({ $3 }: ${1:ComponentName}Props) {",
      "  return (",
      "    <div>",
      "      $0",
      "    </div>",
      "  );",
      "}"
    ]
  }
}

Testing

1. Unit Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

2. E2E Tests (Playwright)

# Install Playwright
pnpm exec playwright install

# Run E2E tests
pnpm test:e2e

# Run E2E tests in UI mode
pnpm exec playwright test --ui

3. Type Checking

# Run TypeScript type check
pnpm type-check

4. Linting

# Run ESLint
pnpm lint

# Fix auto-fixable issues
pnpm lint:fix

Performance Optimization

1. Bundle Analysis

# Analyze bundle size
pnpm build
pnpm analyze

# Opens bundle analyzer in browser

2. Lighthouse Audit

# Run Lighthouse CI
pnpm lighthouse

Next Steps

After setup is complete:

✅ Explore the codebase - Read ARCHITECTURE.md
✅ Make your first contribution - See CONTRIBUTING.md
✅ Review API integrations - Check THIRD_PARTY_APIs.md
✅ Join the community - Discord | Telegram

Contact & Support

Live App: https://safespace.elpeef.com
Repository: https://github.com/mrbrightsides/safespace
Email: support@elpeef.com
Telegram: @khudriakhmad
Discord: @khudri_61362

FilesExpand file tree

SETUP.md

Latest commit

History