StockedUp Discord Subscription Automation

Overview

This guide walks you through deploying the StockedUp Discord Auth Automation system to production. The workflow is:

Chargebee Payment → Redirect → Middleware → Discord OAuth → Airtable Update → Discord Bot → Role Assigned

Components

Table of Contents

• Prerequisites
• Architecture
• Step 1: Discord Developer Setup
• Step 2: Chargebee Configuration
• Step 3: Airtable Setup
• Step 4: Environment Variables
• Step 5: Verification and Testing
• Step 6: Build and Deploy (PebbleHost)
• Troubleshooting
• Optional: Additional Features
• Optional: Cloudflare Tunnel Setup
• Quick Reference

Prerequisites

• Node.js 18+ and npm 8+
• Discord Developer Account: discord.com/developers
• Chargebee account with API access
• Airtable account with a prepared base
• Production domain with SSL certificate
• Server/hosting (Railway, Render, AWS, DigitalOcean, etc.)

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         EXTERNAL SERVICES                           │
├─────────────────┬─────────────────┬─────────────────────────────────┤
│    Chargebee    │     Discord     │            Airtable             │
│   (Payments)    │   (OAuth/Bot)   │           (Database)            │
└────────┬────────┴────────┬────────┴────────────────┬────────────────┘
         │                 │                         │
         │ Webhooks        │ OAuth + Gateway         │ REST API
         │ + Redirects     │                         │
         ▼                 ▼                         ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      YOUR PRODUCTION SERVER                         │
├─────────────────────────────┬───────────────────────────────────────┤
│     Middleware Service      │        Discord Bot Service            │
│        (Port 3000)          │           (Port 3001)                 │
│                             │                                       │
│ • /chargebee/redirect       │ • Discord Gateway connection          │
│ • /chargebee/webhook        │ • Role assignment                     │
│ • /auth/discord/*           │ • guildMemberAdd events               │
│ • /health                   │ • /internal/assign-role               │
└─────────────────────────────┴───────────────────────────────────────┘
      

Step 1: Discord Developer Setup

1.1 Create a Discord Application

1. Go to the Discord Developer Portal.
2. Create a new application (e.g., "StockedUp Subscription Bot").
3. Copy the Client ID → Save as env variable: DISCORD_CLIENT_ID
4. Copy the Client Secret → Save as env variable: DISCORD_CLIENT_SECRET

1.2 Configure OAuth2

1. In OAuth2 → General, add the redirect URI:

https://auth.stockedup.university/auth/discord/callback

Save as env variable: DISCORD_REDIRECT_URI

1.3 Create a Bot

1. In the Bot section, click Add Bot and reset the token.
2. Copy the token → Save as env variable: DISCORD_BOT_TOKEN

1.4 Configure Bot Permissions

• Enable SERVER MEMBERS INTENT.
• Bot permissions: MANAGE_ROLES and VIEW_CHANNEL.

1.5 Invite the Bot

1. Use OAuth2 → URL Generator with scope bot.
2. Select permissions Manage Roles, View Channels, and Send Messages.
3. Open the generated URL to authorize the bot in your server.

1.6 Get Server and Role IDs

1. Enable Discord Developer Mode.
2. Right-click your server → Copy ID → Save as env variable: DISCORD_GUILD_ID
3. Right-click the role to assign → Copy ID → Save as env variable: DISCORD_ROLE_ID

Step 2: Chargebee Configuration

2.1 Get API Credentials

1. In Settings → Configure Chargebee → API Keys:
2. Copy your site name (subdomain only, e.g., stockedup-test) → Save as env variable: CHARGEBEE_SITE
3. Copy your API key → Save as env variable: CHARGEBEE_API_KEY

2.2 Configure Checkout Redirect URL

1. In Settings → Configure Chargebee → Checkout & Self-Serve Portal, set the redirect URL:

https://auth.stockedup.university/auth/discord?subscription_id={{subscription.id}}&customer_id={{customer.id}}&plan_id={{plan.id}}

This redirects customers to the Discord onboarding page after successful payment.

2.3 Configure Chargebee Webhook (Required)

1. In Settings → Configure Chargebee → Webhooks, click Add Webhook.
2. Set the Webhook URL to: https://auth.stockedup.university/chargebee/webhook
3. Enable "Protect webhook URL with basic authentication"
4. Generate or create a secure webhook secret (minimum 32 characters).
5. In the Username field, paste your webhook secret (leave Password field empty).
6. Save as env variable: CHARGEBEE_WEBHOOK_SECRET
7. Select API Version 2
8. Recommended: Select specific events (more efficient than "All Events"):
   • subscription_created
   • subscription_changed
   • subscription_cancelled
   • subscription_paused
   • subscription_resumed
   • subscription_renewed
   • subscription_deleted
   • customer_created
   • customer_changed
   • customer_deleted
9. Click Create to save the webhook.

2.4 Identify Discord Product Plan IDs

1. In Product Catalog → Plans, collect the plan IDs that should trigger Discord roles.
2. List them comma-separated → Save as env variable: DISCORD_PRODUCT_PLAN_IDS
3. Example: premium-monthly,premium-yearly,vip-lifetime

Step 3: Airtable Setup

3.1 Create Airtable Base

Create a base (e.g., “StockedUp Subscriptions”) and add the tables below.

3.2 Create Tables

Table 1: Subscriptions

Table 2: Customers

Table 3: Audit_Logs

Event Types: oauth_started, oauth_redirect, oauth_callback, oauth_token_exchange, oauth_user_fetch, oauth_completed, oauth_failed, discord_verification_started, discord_verification_verified, discord_verification_failed, discord_verification_revoked, role_assignment_started, role_assignment_completed, role_assignment_failed, subscription_created, subscription_updated, subscription_cancelled, subscription_paused, subscription_expired, customer_created, customer_updated.

Table 4: Discord_Verifications

3.3 Get Airtable Credentials

1. Create a Personal Access Token in Account → Developer Hub with scopes: data.records:read, data.records:write, and schema.bases:read.
2. Copy the token → Save as env variable: AIRTABLE_API_KEY
3. Copy your Base ID (format appXXXXXXXXXXXXXX) from the Airtable URL → Save as env variable: AIRTABLE_BASE_ID

Step 4: Environment Variables

Create a .env file with the following values:

# Discord OAuth Configuration
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
DISCORD_REDIRECT_URI=https://auth.stockedup.university/auth/discord/callback

# Discord Bot Configuration
DISCORD_BOT_TOKEN=your_discord_bot_token
DISCORD_GUILD_ID=your_discord_server_id
DISCORD_ROLE_ID=your_subscriber_role_id
# DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/xxx/xxx

# Discord Product Configuration
DISCORD_PRODUCT_PLAN_IDS=plan_discord_monthly,plan_discord_yearly

# Chargebee Configuration
CHARGEBEE_SITE=your_chargebee_site
CHARGEBEE_API_KEY=your_chargebee_api_key
CHARGEBEE_WEBHOOK_SECRET=your_chargebee_webhook_secret

# Airtable Configuration
AIRTABLE_API_KEY=your_airtable_personal_access_token
AIRTABLE_BASE_ID=appXXXXXXXXXXXXXX
AIRTABLE_TABLE_NAME=Subscriptions
AIRTABLE_CUSTOMERS_TABLE_NAME=Customers
AIRTABLE_AUDIT_LOGS_TABLE_NAME=Audit_Logs
AIRTABLE_DISCORD_VERIFICATIONS_TABLE_NAME=Discord_Verifications
AIRTABLE_AUDIT_LOG_RETENTION_DAYS=30

# Application Configuration
REDIRECT_BASE_URL=https://auth.stockedup.university
SESSION_SECRET=your-secure-random-string-at-least-32-characters-long
PORT=3000
BOT_PORT=3001
NODE_ENV=production

Environment Variable Reference

Step 5: Verification and Testing

5.1 Health Check

curl https://auth.stockedup.university/health
# Expected: {"status":"ok","service":"middleware","timestamp":"..."}

5.2 Test Webhook

1. Use Chargebee's "Test Webhook".
2. Verify the event in application logs and in the Airtable Audit_Logs table.

5.3 Test OAuth Flow

1. Create a test subscription in Chargebee and complete the payment.
2. Confirm the redirect to Discord OAuth and authorize.
3. Check Airtable for updated Subscriptions and Discord_Verifications records plus Audit_Logs entries.

5.4 Verify Role Assignment

1. Confirm the user receives the role in Discord.
2. If the user joins after purchase, the guildMemberAdd event should assign the role automatically.

Step 6: Build and Deploy (PebbleHost)

6.1 Prepare Project Files

Ensure your local project has the following core files and folders:

stockedup-discord-subscription-automation/
├── apps/
│   ├── discord-bot/
│   │   ├── dist/              ← Compiled JavaScript (from build)
│   │   ├── src/               ← TypeScript source
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── middleware/
│       ├── dist/              ← Compiled JavaScript (from build)
│       ├── src/               ← TypeScript source
│       ├── package.json
│       └── tsconfig.json
├── packages/
│   ├── shared-airtable/
│   │   ├── dist/              ← Compiled JavaScript
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── shared-config/
│   │   ├── dist/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── shared-logger/
│   │   ├── dist/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── shared-types/
│       ├── dist/
│       ├── src/
│       ├── package.json
│       └── tsconfig.json
├── docs/                      ← Documentation
├── scripts/                   ← Utility scripts
├── .env                       ← Create with your environment variables
├── .env.example              ← Template
├── bot.js                    ← Main entry point
├── package.json
├── package-lock.json
├── tsconfig.json
└── README.md

6.2 Upload to PebbleHost

Upload all project files to your PebbleHost server. You can use:

• SFTP/FTP: Use FileZilla or similar to upload the entire project folder
• Git: Clone the repository directly on the server (recommended)

6.3 Create .env File

SSH into your PebbleHost server and create a .env file in the root directory with all environment variables from Step 4:

cd stockedup-discord-subscription-automation
nano .env  # Or use vi, vim, or upload via SFTP

6.4 Install Dependencies and Build

In your project directory on the server, run:

npm install
npm run build

This will install all dependencies and compile TypeScript to JavaScript in the dist/ folders.

6.5 Start the Application

PebbleHost will automatically start the bot using the bot.js entry point. If you need to manually start it:

node bot.js

The bot will automatically start both services:

• Middleware: Runs on port 3000 (handles OAuth and webhooks)
• Discord Bot: Runs on port 3001 (handles role assignments)

6.6 Verify Startup

Check the console logs to confirm both services started successfully. You should see:

[Middleware] Server listening on port 3000
[Discord Bot] Bot logged in as YourBotName#1234
[Discord Bot] Server listening on port 3001

6.7 Post-Deployment Verification

After deployment, verify everything is working:

1. Health check: curl https://auth.stockedup.university/health
2. Test webhook: Use Chargebee's test webhook feature
3. Test OAuth: Create a test subscription and complete the flow
4. Monitor logs: Watch for any errors in Airtable Audit_Logs and console output

Troubleshooting

Common Issues

• Missing required environment variable: Ensure all required variables are set (see Step 4).
• Chargebee webhook signature verification failed: Verify CHARGEBEE_WEBHOOK_SECRET and webhook URL.
• Airtable field errors: Use Checkbox type for role_assigned; ensure Single Select options match exactly.
• Bot cannot assign roles: Check role hierarchy, permissions, DISCORD_GUILD_ID, and DISCORD_ROLE_ID.
• OAuth redirect errors: Ensure DISCORD_REDIRECT_URI matches Discord settings and SSL is valid; confirm REDIRECT_BASE_URL.
• Rate limiting: Airtable (5 req/s) and Discord OAuth (20 req/15min/IP). The system includes internal backoff.

Log Locations

• Application logs: stdout/stderr or PM2 logs.
• Audit logs: Airtable Audit_Logs table.
• Discord webhook logs: Configure DISCORD_WEBHOOK_URL.

Getting Help

1. Check the Airtable Audit_Logs table.
2. Review console output.
3. Verify environment variables.
4. Contact support at [email protected].

Optional: Additional Features

These features are optional but can enhance monitoring and debugging capabilities.

Discord Webhook Logs

Configure a Discord webhook to receive real-time application logs and notifications in a Discord channel.

Benefits:

• Real-time notifications for subscription events
• Role assignment confirmations
• Error alerts and debugging information
• Centralized monitoring in your Discord server

Setup Instructions:

1. Go to your Discord server and select the channel where you want to receive logs (e.g., #bot-logs or #notifications).
2. Click the gear icon (⚙️) next to the channel name to open Channel Settings.
3. Navigate to Integrations → Webhooks.
4. Click New Webhook or Create Webhook.
5. Give it a name (e.g., "StockedUp Bot Logs").
6. Optionally customize the webhook avatar to match your branding.
7. Click Copy Webhook URL.
8. Save as env variable (optional): DISCORD_WEBHOOK_URL
9. Add the URL to your .env file and restart the application.

Optional: Cloudflare Tunnel Setup

Use Cloudflare Tunnel to expose your production server securely without opening ports or managing SSL certificates.

Install cloudflared

# macOS
brew install cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

# Windows
winget install Cloudflare.cloudflared

Authenticate

cloudflared tunnel login

Create a Tunnel

cloudflared tunnel create stockedup

Save the tunnel ID and credentials file path.

Configure DNS

cloudflared tunnel route dns stockedup your-subdomain.yourdomain.com

Create Configuration File

tunnel: YOUR_TUNNEL_ID
credentials-file: /path/to/credentials.json

ingress:
  - hostname: your-subdomain.yourdomain.com
    service: http://localhost:3000
  - service: http_status:404

Run the Tunnel

cloudflared tunnel run stockedup

Set up cloudflared as a system service for production.

Quick Reference

Active Endpoints

Commands

# Development (with Cloudflare tunnel)
npm run dev

# Development (without tunnel)
npm run dev:no-tunnel

# Production
npm run start

# Build
npm run build

# Lint
npm run lint