Discord Activity Setup & Deployment Guide

Overview

AeThex can be embedded as a Discord Activity, allowing users to access the platform directly within Discord servers. This guide covers the setup, configuration, and deployment process.

What is a Discord Activity?

A Discord Activity is an embedded application that runs within Discord. It allows users to:

Access AeThex features directly in Discord
Share their experience with server members
Collaborate in real-time without leaving Discord

Architecture

Discord Server
    ↓
Discord Activity (https://aethex.dev/discord)
    ↓
AeThex Frontend + Backend
    ↓
Supabase + DevConnect DBs

Prerequisites

Discord Application: Application ID 578971245454950421
Domain: https://aethex.dev (must be a proper domain, not IP)
SSL/HTTPS: Required for Discord Activities
Cloudflare: Configured to allow traffic to aethex.dev

Configuration Files

1. Discord Manifest (`code/public/discord-manifest.json`)

This file tells Discord how to handle the AeThex Activity:

{
  "id": "578971245454950421",
  "name": "AeThex",
  "url": "https://aethex.dev",
  "instance_url": "https://aethex.dev/discord",
  "oauth2": {
    "client_id": "578971245454950421",
    "scopes": ["identify", "email", "guilds"],
    "redirect_uris": ["https://aethex.dev/discord/callback"]
  }
}

Key Configuration Points:

instance_url: Where Discord Activity iframe loads (MUST be domain, not IP)
redirect_uris: OAuth callback endpoint (MUST match Discord app settings)
scopes: What Discord permissions the Activity requests

2. Code Configuration

Frontend Pages (code/client/pages/):

DiscordActivity.tsx - Main Activity page mounted at /discord
Discord OAuth callback handler at /discord/callback

Context (code/client/contexts/DiscordContext.tsx):

Manages Discord user session
Handles OAuth flow
Exposes Discord user data to components

Routes (code/client/App.tsx):

<Route path="/discord" element={<DiscordActivity />} />
<Route path="/discord/callback" element={<DiscordOAuthCallback />} />

3. HTML Configuration (`code/index.html`)

The Discord SDK is loaded in the HTML head:

<script async src="https://cdn.discordapp.com/assets/embed.js"></script>

This must be present for Discord Activity to initialize.

Local Testing

Prerequisites

Node.js 18+
npm or yarn
Running AeThex dev server

Steps

Start the dev server:
```
npm run dev
# or
yarn dev
```
Access locally via tunnel (if testing Discord Activity):
- Use a tool like ngrok to expose localhost to Discord
- Or use Discord's local testing tools
Test routes:
- Activity: http://localhost:5173/discord (becomes domain in production)
- Callback: http://localhost:5173/discord/callback

Local Testing Limitations

⚠️ Note: Discord Activities require HTTPS and a proper domain. Local testing with IP addresses will fail with Cloudflare Error 1003.

Local testing workarounds:

Use ngrok with a tunnel URL
Use Discord's local testing documentation
Test OAuth flow after deploying to staging

Deployment

Production URLs (MUST use domain, not IP)

Activity URL: https://aethex.dev/discord
OAuth Redirect: https://aethex.dev/discord/callback
Manifest: https://aethex.dev/public/discord-manifest.json

Deployment Checklist

App deployed to aethex.dev domain
SSL/HTTPS certificate valid and active
Cloudflare configured to allow traffic to aethex.dev
Discord manifest file accessible at /public/discord-manifest.json
Discord SDK script loads successfully in browser console
OAuth redirect URIs match Discord app settings
Discord Application ID is correct: 578971245454950421

Cloudflare Configuration

Critical: Cloudflare blocks direct IP access (Error 1003). Ensure:

DNS record for aethex.dev points to correct server/CDN
Cloudflare allows traffic to your origin
SSL/TLS encryption is enabled
No IP-based redirect rules that block Activity iframe

Environment Variables

No special environment variables needed for Discord Activity. The configuration is done via:

code/public/discord-manifest.json
Discord Application settings
code/client/contexts/DiscordContext.tsx

OAuth Flow

High-Level Flow

1. User opens AeThex Activity in Discord
2. DiscordActivity page loads (/discord)
3. Discord SDK initializes with manifest config
4. User clicks "Login with Discord"
5. Redirects to Discord's OAuth authorization page
6. User grants permissions (identify, email, guilds)
7. Discord redirects back to https://aethex.dev/discord/callback
8. DiscordOAuthCallback processes the authorization code
9. Backend exchanges code for access token
10. User session created, redirected to main Activity UI

Implementation Details

DiscordActivity.tsx handles:

Discord SDK initialization
OAuth trigger and callback handling
Activity UI rendering

DiscordContext.tsx manages:

Discord user state
Token storage
Session lifecycle

API calls use Discord access token for:

User identification
Guild information
Activity-specific operations

Error Handling

Cloudflare Error 1003: Direct IP Access Not Allowed

Cause: Accessing Activity via IP address instead of domain

Solution:

❌ http://192.168.1.100:5173/discord
✅ https://aethex.dev/discord

Error Message in UI: Users will see a helpful error message explaining:

The issue (Cloudflare blocking IP access)
How to fix it (use domain instead)
Troubleshooting steps

Discord SDK Error

Cause: Discord SDK not loaded or manifest invalid

Solution:

Verify Discord SDK script in code/index.html
Check manifest is accessible at /public/discord-manifest.json
Verify Discord Application ID: 578971245454950421

Testing Checklist

Functional Tests

Activity loads without Cloudflare errors
Discord SDK initializes successfully
OAuth flow completes successfully
User is authenticated in AeThex after OAuth
Activity can access user Discord profile info
Activity can read server/guild information
Multiple users can run Activity simultaneously

Security Tests

OAuth tokens are stored securely
HTTPS enforced (no HTTP fallback)
CORS headers properly configured
No sensitive data in localStorage
Logout properly clears session

Browser Tests

Works in Discord desktop client
Works in Discord web client
Works in Discord mobile app
Responsive design works in Discord's narrow sidebar

Troubleshooting

Activity Won't Load

Error: Blank white screen in Discord Activity

Debug Steps:

Open browser DevTools in Discord
Check Console for errors
Check Network tab for failed requests
Verify domain is accessible (test in regular browser tab)
Verify Cloudflare isn't blocking traffic

Common Causes:

IP address used instead of domain (Cloudflare Error 1003)
Discord SDK script failed to load
Manifest file not accessible
CORS policy violation

OAuth Not Working

Error: OAuth flow doesn't complete or redirect fails

Debug Steps:

Check Discord Application settings - redirect URIs match exactly
Verify OAuth callback route exists: /discord/callback
Check browser console for authorization error codes
Verify Discord Application permissions (identify, email, guilds)

Common Causes:

Redirect URI mismatch between manifest and Discord app
Discord Application doesn't have "Identify" scope enabled
Activity not installed in Discord server

User Can't See Guild Information

Error: Guild list is empty or shows no servers

Debug Steps:

Verify "guilds" scope is in OAuth config
Check user actually has permission in those guilds
Verify Discord OAuth token has guilds scope

Deployment to Production

Step 1: Build

npm run build
# or
yarn build

This creates optimized bundles in dist/ directory.

Step 2: Verify Configuration

Discord manifest is in dist/public/discord-manifest.json
All routes are correctly wired in App.tsx
No hardcoded localhost URLs

Step 3: Deploy

Using your deployment provider (Netlify, Vercel, custom):

# Deploy dist/ folder to https://aethex.dev

Step 4: Verify in Production

Access https://aethex.dev/discord in browser
Check DevTools Console for errors
Try Discord Activity in actual Discord server
Test OAuth flow end-to-end

Step 5: Add to Discord

In Discord Developer Portal:

Go to Application Settings
Add Activity URL: https://aethex.dev/discord
Set OAuth2 Redirect URIs to: https://aethex.dev/discord/callback
Publish Application
Users can now install AeThex Activity in servers

File Structure

code/
├── client/
│   ├── pages/
│   │   └── DiscordActivity.tsx        # Main Activity page
│   ├── contexts/
│   │   └── DiscordContext.tsx         # Discord OAuth/session management
│   └── App.tsx                        # Routes: /discord, /discord/callback
├── index.html                         # Discord SDK script loaded here
├── public/
│   └── discord-manifest.json          # Discord Activity configuration
└── docs/
    └── DISCORD-ACTIVITY-SETUP.md      # This file

IP Governance: code/docs/IP-GOVERNANCE-FRAMEWORK.md - Data ownership and licensing
Onboarding: code/client/pages/Onboarding.tsx - User onboarding flow
Authentication: code/client/contexts/AuthContext.tsx - Primary auth system

Support

For issues or questions:

Check this guide for common troubleshooting
Check Discord Developer Docs: https://discord.com/developers/docs/activities/building-an-app
Check browser console for specific error messages
Verify domain/DNS configuration with Cloudflare

Version History

v1.0.0 (Current)
- Discord Activity foundation
- OAuth 2.0 integration
- Cloudflare Error 1003 handling
- Multi-user support

Last Updated: 2024 Maintained by: AeThex Engineering Team

PreviousDiscord Activity Errors - Diagnostic & Fix Guide NextDiscord Activity SPA Implementation Guide

Last updated 3 months ago

Good afternoon

hashtagOverview

hashtagWhat is a Discord Activity?

hashtagArchitecture

hashtagPrerequisites

hashtagConfiguration Files

hashtag1. Discord Manifest (code/public/discord-manifest.json)

hashtag2. Code Configuration

hashtag3. HTML Configuration (code/index.html)

hashtagLocal Testing

hashtagPrerequisites

hashtagSteps

hashtagLocal Testing Limitations

hashtagDeployment

hashtagProduction URLs (MUST use domain, not IP)

hashtagDeployment Checklist

hashtagCloudflare Configuration

hashtagEnvironment Variables

hashtagOAuth Flow

hashtagHigh-Level Flow

hashtagImplementation Details

hashtagError Handling

hashtagCloudflare Error 1003: Direct IP Access Not Allowed

hashtagDiscord SDK Error

hashtagTesting Checklist

hashtagFunctional Tests

hashtagSecurity Tests

hashtagBrowser Tests

hashtagTroubleshooting

hashtagActivity Won't Load

hashtagOAuth Not Working

hashtagUser Can't See Guild Information

hashtagDeployment to Production

hashtagStep 1: Build

hashtagStep 2: Verify Configuration

hashtagStep 3: Deploy

hashtagStep 4: Verify in Production

hashtagStep 5: Add to Discord

hashtagFile Structure

hashtagRelated Documentation

hashtagSupport

hashtagVersion History

Overview

What is a Discord Activity?

Architecture

Prerequisites

Configuration Files

1. Discord Manifest (`code/public/discord-manifest.json`)

2. Code Configuration

3. HTML Configuration (`code/index.html`)

Local Testing

Prerequisites

Steps

Local Testing Limitations

Deployment

Production URLs (MUST use domain, not IP)

Deployment Checklist

Cloudflare Configuration

Environment Variables

OAuth Flow

High-Level Flow

Implementation Details

Error Handling

Cloudflare Error 1003: Direct IP Access Not Allowed

Discord SDK Error

Testing Checklist

Functional Tests

Security Tests

Browser Tests

Troubleshooting

Activity Won't Load

OAuth Not Working

User Can't See Guild Information

Deployment to Production

Step 1: Build

Step 2: Verify Configuration

Step 3: Deploy

Step 4: Verify in Production

Step 5: Add to Discord

File Structure

Related Documentation

Support

Version History