First Steps

After installation, this guide walks you through the essential first steps with HiveForge.

1. Create Your First User

Sign Up via UI

Navigate to http://localhost:3000/auth/signup (opens in a new tab)
Enter email and password
Check http://localhost:54324 (opens in a new tab) (Inbucket) for verification email
Click verification link
Log in at http://localhost:3000/auth/login (opens in a new tab)

Create Admin User via CLI

# Create platform admin
pnpm db:create-admin --email admin@example.com --password yourpassword
 
# Or use environment variable
ADMIN_EMAIL=admin@example.com pnpm db:create-admin

2. Explore the Dashboard

After logging in, you'll see:

User Dashboard

Organizations: Create and manage workspaces
Profile: Update user settings
Billing: View subscription status
Settings: Configure preferences

Platform Admin (if admin)

Tenants: Manage all organizations
Users: View all system users
Audit Logs: Track system events
Feature Flags: Enable/disable features
System Health: Monitor application status

3. Create Your First Organization

Organizations (also called workspaces or tenants) are the primary grouping for users and data.

Via Web UI

Go to http://localhost:3000/dashboard (opens in a new tab)
Click "Create Organization"
Fill in details:
- Name: Your organization name
- Slug: URL-friendly identifier
- Tier: Free, Pro, or Enterprise
Click "Create"

Via API

curl -X POST http://localhost:8000/api/organizations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "tier": "pro"
  }'

Via Python Script

from apps.api.app.services.organizations import OrganizationService
 
# Create organization
org = await OrganizationService.create(
    name="Acme Corp",
    slug="acme-corp",
    owner_id="user-id-here",
    tier="pro"
)

4. Invite Team Members

Web UI

Go to Organization Settings > Members
Click "Invite Member"
Enter email address
Select role:
- Owner: Full access
- Admin: Manage members and settings
- Member: Standard access
- Viewer: Read-only access
Click "Send Invitation"

API

curl -X POST http://localhost:8000/api/organizations/{org_id}/invitations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "teammate@example.com",
    "role": "member"
  }'

Invitation email will be sent via Resend (or shown in Inbucket for local dev).

5. Configure Your Organization

Basic Settings

Profile: Logo, description, website
Billing: Add payment method, choose plan
Team: Manage members and roles
API Keys: Generate keys for API access

Advanced Settings

Custom Domain: Set up your domain (Enterprise)
SSO: Configure SAML/OAuth (Enterprise)
Webhooks: Set up event notifications
Feature Flags: Enable beta features

6. Set Up Billing (Optional)

If you're building a paid SaaS:

Configure Stripe Products

Go to Stripe Dashboard
Create products and prices:
- Free: $0/month
- Pro: $29/month
- Enterprise: $99/month
Add metered billing (optional):
- API calls
- Storage usage
- Team members

Connect to HiveForge

Update .env:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
 
# Add product IDs
STRIPE_PRICE_ID_FREE=price_...
STRIPE_PRICE_ID_PRO=price_...
STRIPE_PRICE_ID_ENTERPRISE=price_...

Test Subscription Flow

Go to Organization > Billing
Click "Upgrade Plan"
Use Stripe test cards:
- Success: 4242 4242 4242 4242
- Decline: 4000 0000 0000 0002
Complete checkout
Verify subscription in Stripe Dashboard

See Billing Guide for complete setup.

7. Configure Email Templates

Test Email Sending

# Send test email
curl -X POST http://localhost:8000/api/email/test \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "test@example.com",
    "template": "welcome"
  }'

Customize Templates

Email templates are in apps/web/emails/:

// apps/web/emails/welcome.tsx
import { Html, Button } from '@react-email/components'
 
export default function WelcomeEmail({ name }) {
  return (
    <Html>
      <h1>Welcome to HiveForge, {name}!</h1>
      <Button href="https://app.hiveforge.dev">
        Get Started
      </Button>
    </Html>
  )
}

See Email Guide for customization.

8. Test API Integration

Get API Key

Go to Organization Settings > API Keys
Click "Create API Key"
Name it (e.g., "Development")
Copy the key (shown only once!)

Make API Requests

# Using API key
curl http://localhost:8000/api/users/me \
  -H "X-API-Key: YOUR_API_KEY"
 
# Using JWT token
curl http://localhost:8000/api/users/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Test in Code

// TypeScript example
const response = await fetch('http://localhost:8000/api/users/me', {
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
  },
})
 
const user = await response.json()
console.log(user)

# Python example
import httpx
 
async with httpx.AsyncClient() as client:
    response = await client.get(
        'http://localhost:8000/api/users/me',
        headers={'X-API-Key': 'YOUR_API_KEY'}
    )
    user = response.json()
    print(user)

9. Enable AI Features (Optional)

Configure OpenAI

Add to .env:

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4

Test AI Endpoint

curl -X POST http://localhost:8000/api/ai/generate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a product description for a SaaS tool",
    "max_tokens": 200
  }'

See AI Features Guide for more.

10. Set Up Development Workflow

Run Tests

# All tests
pnpm test
 
# Frontend only
pnpm test:web
 
# Backend only
pnpm test:api
 
# E2E tests
pnpm test:e2e

Code Quality

# Lint code
pnpm lint
 
# Format code
pnpm format
 
# Type check
pnpm typecheck

Database Management

# Create new migration
pnpm db:migration:create add_new_table
 
# Apply migrations
pnpm db:migrate
 
# Rollback last migration
pnpm db:rollback
 
# Reset database
pnpm db:reset

Next Steps

Now that you've completed the first steps:

Quick Reference

Useful Commands

# Development
pnpm dev                    # Start all services
pnpm dev:web               # Frontend only
pnpm dev:api               # Backend only
 
# Database
pnpm db:migrate            # Run migrations
pnpm db:seed               # Seed data
pnpm db:reset              # Reset database
 
# Testing
pnpm test                  # All tests
pnpm test:watch           # Watch mode
 
# Build
pnpm build                 # Build all apps
pnpm build:web            # Build frontend
pnpm build:api            # Build backend
 
# Deployment
pnpm deploy:web           # Deploy frontend
pnpm deploy:api           # Deploy backend

Default URLs

Frontend: http://localhost:3000 (opens in a new tab)
API: http://localhost:8000 (opens in a new tab)
API Docs: http://localhost:8000/docs (opens in a new tab)
Supabase Studio: http://localhost:54323 (opens in a new tab)
Email (Inbucket): http://localhost:54324 (opens in a new tab)
Documentation: http://localhost:3001 (opens in a new tab)

Test Credentials

Default seeded users:

Admin:
Email: admin@example.com
Password: admin123

User:
Email: user@example.com
Password: user123

Stripe test cards:

Success: 4242 4242 4242 4242
Decline: 4000 0000 0000 0002
3D Secure: 4000 0027 6000 3184

Installation Common Workflows