Run ArcRaids on Your Twitch Channel

Follow this step-by-step guide to get your chat bot up and running

Start Setup View GitLab Repo
Get the code on GitLab
1 / 9

Prerequisites

Make sure you have everything you need before starting

What you'll do

Verify that you have Node.js, npm, Git, and a Twitch account set up on your system.

Checklist

Verify Installation

Terminal
$ node -v
Terminal
$ npm -v
Terminal
$ git --version

Node.js not found? Download from nodejs.org (LTS version recommended)

npm not found? npm comes with Node.js. If missing, reinstall Node.js.

Git not found? Install from git-scm.com

Get the Code

Clone the repository from GitLab

What you'll do

Clone the ArcRaids repository to your local machine using Git.

Checklist

Clone Repository

gitlab.com/your-username/arcraids
Terminal
$ git clone REPO_URL
Terminal
$ cd arcraids

Permission denied? Make sure you have Git installed and access to the repository.

Repository not found? Verify the URL is correct and you have access permissions.

Install Dependencies

Install all required npm packages

What you'll do

Install all project dependencies using npm. This may take a few minutes.

Checklist

Install Packages

Terminal
$ npm install

Installation fails? Make sure you're using Node.js 18+ and try deleting node_modules and package-lock.json, then run npm install again.

Permission errors? Avoid using sudo with npm. Use a Node version manager like nvm instead.

Configure Environment

Set up your environment variables

What you'll do

Create a .env file from the example template and fill in your Twitch credentials.

Checklist

Create .env File

Terminal
$ cp .env.example .env
.env
TWITCH_USERNAME=your_bot_username
TWITCH_OAUTH_TOKEN=oauth:your_token_here
TWITCH_CHANNEL=your_channel_name
DB_PATH=./data/arcraids.db
EXTENSION_SECRET=your_extension_secret_base64
EXTENSION_CLIENT_ID=your_client_id
BASE_URL=http://localhost:3000
PORT=3000

.env.example not found? Check the repository structure. The file should be in the project root.

Token format? OAuth tokens should start with oauth: prefix.

Create Twitch App & Token

Set up your Twitch Developer application

What you'll do

Create a Twitch Developer application and generate an OAuth token with the required scopes.

Checklist

Required OAuth Scopes

chat:read Read chat messages
chat:edit Send chat messages

Steps

  1. Go to Twitch Developer Console
  2. Click "Register Your Application"
  3. Fill in application details (name, OAuth redirect URL can be http://localhost)
  4. Note your Client ID
  5. Generate a User Access Token using Twitch Token Generator or Twitch CLI
  6. Select scopes: chat:read and chat:edit
  7. Copy the token (it should start with oauth:)

Token invalid? Make sure it starts with oauth: and includes both required scopes.

Can't generate token? Use twitchtokengenerator.com or the official Twitch CLI tool.

Bot account? The token must be generated for your bot account, not your broadcaster account.

Run Locally

Start the bot and verify it's working

What you'll do

Start the bot in development mode and verify it connects to Twitch successfully.

Checklist

Start the Bot

Terminal
$ npm run dev

Expected Output

Connected to Twitch IRC at irc.chat.twitch.tv:6697 Raid scheduler started Server running on port 3000

Connection failed? Check your OAuth token is valid and has the correct scopes.

Port already in use? Change the PORT in your .env file to a different port.

Database errors? Make sure the DB_PATH directory exists and is writable.

Connect to Your Channel

Invite the bot and test commands

What you'll do

Invite the bot to your channel (if needed) and verify it responds to commands in chat.

Checklist

Test Commands

In your Twitch chat, try these commands:

!create MyCallsign Creates your character profile
!profile Shows your profile
Note: The bot account must have permission to chat in your channel. If the bot doesn't respond, make sure it's not banned and has chat permissions.

Bot not responding? Check that the bot account is not banned and has permission to chat.

Commands not working? Verify the bot is connected and the channel name in .env matches your channel.

Deploy for 24/7 Operation

Optional: Run the bot continuously

What you'll do

Deploy the bot to a hosting service so it runs 24/7 without keeping your computer on.

Checklist

Docker Deployment

Terminal
$ docker build -t arcraids .
Terminal
$ docker run --env-file .env -p 3000:3000 arcraids

Note: Make sure Docker is installed and your .env file is in the project root.

Cloud Hosting (Render/Fly/Railway/VPS)

  1. Create an account on your chosen hosting service (Render, Fly.io, Railway, or a VPS)
  2. Connect your GitLab repository
  3. Set environment variables in the hosting dashboard (copy from your .env file)
  4. Configure build command: npm install
  5. Configure start command: npm start
  6. Set healthcheck endpoint (if available): GET /health
  7. Deploy!
⚠️ Important: Never commit your .env file to Git. Always use the hosting service's environment variable settings.

Docker build fails? Make sure you have a Dockerfile in the project root.

Hosting service issues? Check that all environment variables are set correctly in the dashboard.

Bot not connecting? Verify your OAuth token is still valid and hasn't expired.

Verify Everything

Final checks to ensure everything works

What you'll do

Run through a final checklist to verify all bot features are working correctly.

Verification Checklist

Run Diagnostics

Raids not starting? Check the bot logs for scheduler errors. Verify the time is correct on your server.

Inventory not saving? Check database permissions and that DB_PATH is writable.

Extension not loading? Verify EXTENSION_SECRET and EXTENSION_CLIENT_ID are correct in .env.