Skip to content

SETUP.md

Latest commit

 

History

History
432 lines (304 loc) · 10.6 KB

SETUP.md

File metadata and controls

432 lines (304 loc) · 10.6 KB

AnonChat Project Setup Guide 🚀

This guide provides comprehensive instructions for setting up the AnonChat project locally for development.

Table of Contents

Prerequisites

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

Required Software

  • Node.js (v18 or higher) - Download
  • Git - Download
  • pnpm (v8 or higher) - Install globally with: 
    npm install -g pnpm

Required Accounts

  • GitHub account - For forking and contributing to the repository
  • Supabase account - For database and authentication services (Sign up)
  • Stellar Wallet - For Web3 wallet authentication testing

Recommended Tools

  • VS Code - Download
  • PostGres Client - For database management
  • Stellar Lab - For testing blockchain interactions (Link)

Initial Setup

1. Fork and Clone the Repository

# Fork the repository on GitHub first, then clone your fork
git clone https://github.com/YOUR-USERNAME/AnonChat.git
cd AnonChat

2. Add Upstream Remote

To keep your fork synchronized with the original repository:

git remote add upstream https://github.com/original-owner/AnonChat.git
git fetch upstream

3. Install Dependencies

Using pnpm (recommended for this project):

pnpm install

This will install all dependencies listed in package.json, including:

  • Next.js - React framework
  • Tailwind CSS - Utility-first CSS framework
  • Radix UI - Headless UI components
  • Stellar Wallet Kit - Web3 wallet integration
  • Supabase - Backend services and authentication

4. Verify Installation

pnpm --version
node --version

Environment Configuration

1. Create Environment Files

Create a .env.local file in the root directory for local development:

cp .env.example .env.local  # If .env.example exists, or create manually

2. Configure Supabase

Add the following environment variables to .env.local:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# Optional: Supabase Service Role Key (for server-side operations)
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

Getting Supabase Credentials:

  1. Go to Supabase Dashboard
  2. Create a new project or select existing one
  3. Navigate to Settings → API
  4. Copy:
    • Project URL → NEXT_PUBLIC_SUPABASE_URL
    • Anon Key → NEXT_PUBLIC_SUPABASE_ANON_KEY
    • Service Role Key → SUPABASE_SERVICE_ROLE_KEY

3. Configure Web3/Stellar Settings

Add Stellar-specific configuration to .env.local:

# Stellar Configuration
NEXT_PUBLIC_STELLAR_NETWORK=testnet  # Use 'testnet' for development, 'public' for production

# Stellar Blockchain Integration (for on-chain group metadata)
STELLAR_NETWORK=testnet
STELLAR_SOURCE_SECRET=S...  # Your Stellar testnet account secret key
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_TRANSACTION_TIMEOUT=30000  # Optional: Transaction timeout in milliseconds (default: 30000)

Getting a Stellar Testnet Account:

  1. Go to Stellar Laboratory
  2. Click Generate keypair to create a new account
  3. Copy the Secret Key (starts with 'S') → STELLAR_SOURCE_SECRET
  4. Copy the Public Key (starts with 'G')
  5. Click Fund account with Friendbot to get testnet XLM
  6. Verify your account has funds on Stellar Expert

4. Verify Environment Setup

Ensure your .env.local file is in the root directory and contains all required variables:

# List environment files (should show .env.local)
ls -la | grep env

Database Setup

1. Initialize Supabase Database

The database schema is managed through Supabase migrations. SQL migration files are located in the scripts/ directory:

  • 001_create_profiles.sql - Creates user profiles table
  • 002_create_profile_trigger.sql - Creates database trigger for profile creation
  • 003_room_members_and_removal_votes.sql - Room membership and wallet-based removal voting

2. Execute Migrations

Option A: Using Supabase Dashboard (Recommended for beginners)

  1. Go to Supabase Dashboard → Your Project
  2. Navigate to SQL Editor
  3. Click New Query
  4. Copy and paste the contents of scripts/001_create_profiles.sql
  5. Click Run
  6. Repeat for scripts/002_create_profile_trigger.sql and scripts/003_room_members_and_removal_votes.sql

Option B: Using Supabase CLI (Advanced)

# Install Supabase CLI (if not already installed)
npm install -g supabase

# Login to Supabase
supabase login

# Push migrations
supabase db push

3. Verify Database Setup

Check that tables are created in Supabase:

  1. Go to Supabase Dashboard → Table Editor
  2. Verify profiles table exists with expected columns

Running the Project

1. Development Mode

Start the development server:

pnpm dev

The application will be available at http://localhost:3000

2. Production Build

Build the project for production:

pnpm build

3. Start Production Server

After building, start the production server:

pnpm start

4. Linting

Check code for style violations:

pnpm lint

Project Structure Overview

AnonChat/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   │   ├── auth/          # Authentication endpoints
│   │   ├── messages/      # Message handling
│   │   └── rooms/         # Chat rooms
│   ├── chat/              # Chat pages
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Home page
├── components/            # Reusable React components
├── lib/                   # Utility functions and services
│   └── supabase/          # Supabase client configurations
├── public/                # Static assets
├── scripts/               # Database migration scripts
├── styles/                # Global CSS
├── package.json           # Project dependencies
├── tsconfig.json          # TypeScript configuration
└── next.config.mjs        # Next.js configuration

Key Technology Stack

Layer Technology
Frontend Framework Next.js 16 / React 19
Styling Tailwind CSS 4, Radix UI
Language TypeScript 5
Web3 Auth Stellar Wallet Kit
Backend Supabase (PostGres + APIs)
Forms React Hook Form, Zod validation
Real-time Supabase Realtime
Deployment Vercel

Common Development Tasks

Working on a Feature

# 1. Create a new feature branch
git checkout -b feature-[issue-number]

# 2. Make changes and test
pnpm dev

# 3. Lint and build
pnpm lint
pnpm build

# 4. Commit with proper message
git commit -m "Feat: description (#issue-number)"

# 5. Push to your fork
git push origin feature-[issue-number]

# 6. Create a Pull Request on GitHub

Updating from Main Branch

# Fetch latest changes
git fetch upstream

# Rebase your branch on latest main
git rebase upstream/main

# If there are conflicts, resolve them and continue
git rebase --continue

Testing the Application

Manual Testing Checklist

Before submitting a PR, test locally:

  • Application starts without errors: pnpm dev
  • No console errors or warnings
  • Responsive design works on mobile/tablet/desktop
  • Web3 wallet connection works (if modified)
  • Chat functionality works as expected
  • All linting passes: pnpm lint
  • Production build succeeds: pnpm build

Troubleshooting

Common Issues and Solutions

Issue: pnpm install fails

Solution:

# Clear pnpm cache
pnpm store prune

# Clean install
rm -rf node_modules pnpm-lock.yaml
pnpm install

Issue: Port 3000 already in use

Solution:

# Run on different port
pnpm dev -- -p 3001

Issue: Supabase connection errors

Solution:

  1. Verify .env.local has correct Supabase credentials
  2. Check internet connection
  3. Verify Supabase project is active in dashboard
  4. Try refreshing Supabase auth token: 
    supabase logout
supabase login

Issue: Database migrations not applied

Solution:

  1. Verify you're using correct Supabase project
  2. Check SQL syntax in migration files
  3. Try running migrations manually in Supabase Dashboard SQL Editor
  4. Check Supabase logs for errors

Issue: TypeScript errors in IDE

Solution:

# Rebuild TypeScript
pnpm tsc --noEmit

# Clean and reinstall
rm -rf node_modules .next
pnpm install
pnpm build

Issue: Stellar wallet not connecting

Solution:

  1. Ensure you're using a testnet wallet for development
  2. Check wallet browser extension is installed and enabled
  3. Verify NEXT_PUBLIC_STELLAR_NETWORK is set to testnet
  4. Try a different wallet (Freighter, Lobstr, etc.)

Getting Help

Next Steps After Setup

  1. ✅ Read the README.md to understand the project
  2. ✅ Review CONTRIBUTING.md for contribution guidelines
  3. ✅ Check design.md for UI/UX specifications
  4. ✅ Look at open issues and find one to work on
  5. ✅ Follow the branch naming conventions mentioned in CONTRIBUTING.md
  6. ✅ Submit your first PR!

Resources

Happy Coding! 🎉

If you encounter any issues during setup, please open an issue on GitHub with details about your environment and the error message.