AeThex Forge – Local Development Setup

Quick Start Guide

This guide will help you set up and run the AeThex Developer Platform locally.

Prerequisites

1. Node.js (v18 or higher)

   • Download Node.js
   • Includes npm (Node Package Manager)

2. Git (recommended for updates)

   • Download Git

Installation Steps

1. Install Node.js

• Download and install the LTS version from nodejs.org
• Follow the setup wizard
• Restart your terminal after installation

2. Verify Installation

Open your terminal and run:

node --version
npm --version

You should see version numbers (e.g., v20.x.x and 10.x.x)

3. Install Project Dependencies

Navigate to the project folder and install dependencies:

cd /path/to/aethex-forge
npm install

This may take a few minutes as it downloads all required packages.

4. Set Up Environment Variables

Create a .env file in the root directory (aethex-forge/) with the following variables:

Minimum Required (to run the app):

# Supabase Configuration (Required)
VITE_SUPABASE_URL=your_supabase_url_here
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key_here
SUPABASE_SERVICE_ROLE=your_service_role_key_here
SUPABASE_URL=your_supabase_url_here

# API Base URL
VITE_API_BASE=http://localhost:5000

Optional (for full functionality):

# Discord Integration
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
DISCORD_BOT_TOKEN=your_discord_bot_token
DISCORD_PUBLIC_KEY=your_discord_public_key
DISCORD_REDIRECT_URI=http://localhost:5000/api/discord/oauth/callback

# Foundation OAuth
VITE_FOUNDATION_URL=https://aethex.foundation
FOUNDATION_OAUTH_CLIENT_ID=your_foundation_client_id
FOUNDATION_OAUTH_CLIENT_SECRET=your_foundation_client_secret

# Email Service (SMTP)
SMTP_HOST=your_smtp_host
SMTP_PORT=587
SMTP_USER=your_smtp_user
SMTP_PASSWORD=your_smtp_password

# Other Services
VITE_GHOST_API_URL=your_ghost_api_url
GHOST_ADMIN_API_KEY=your_ghost_admin_key

Note: You can start with just the Supabase variables to get the app running. Add other credentials as needed for full functionality.

5. Run the Development Server

npm run dev

The application will start on http://localhost:5000 (or the port set in your config).

Open your browser and navigate to that URL to view the application.

Available Commands

• npm run dev – Start development server (default: port 5000)
• npm run build – Build for production
• npm start – Start production server
• npm run typecheck – Check TypeScript types
• npm test – Run tests

aethex-forge/ aethex-forge/

Project Structure

aethex-forge/
├── client/       # React SPA frontend (pages, components, UI)
├── server/       # Express backend API
├── api/          # API route handlers (modular)
├── shared/       # Shared types/interfaces (client/server)
├── supabase/     # Database migrations & SQL
├── docs/         # Project documentation
└── ...           # Other supporting folders

Getting Supabase Credentials

If you don't have Supabase credentials yet:

1. Go to supabase.com
2. Create a free account and project
3. In your project, go to Settings → API
4. Copy:
   • Project URL → VITE_SUPABASE_URL and SUPABASE_URL
   • anon public key → VITE_SUPABASE_ANON_KEY
   • service_role secret key → SUPABASE_SERVICE_ROLE

Troubleshooting

Port Already in Use

If port 5000 is already in use, you can change it in vite.config.ts:

server: {
   port: 5001, // Change to any available port
}

Module Not Found Errors

Try deleting node_modules and package-lock.json, then run npm install again:

rm -rf node_modules package-lock.json
npm install

Environment Variables Not Loading

• Ensure .env is in the root aethex-forge directory
• Restart the dev server after adding new environment variables
• Variables starting with VITE_ are exposed to the client

Need Help?

• See the docs/ folder for detailed documentation
• Review AGENTS.md for architecture and tech stack
• See replit.md for cloud deployment info
• For advanced troubleshooting, check DEPLOYMENT_CHECKLIST.md and PHASE1_IMPLEMENTATION_SUMMARY.md