Skip to content

Installation Guide

Jump to bottom
Julian Speckmann edited this page Jan 31, 2026 · 4 revisions

SourceXchange Sync Bot

A Discord bot that automatically syncs user roles based on product purchases from SourceXchange.

Installation Guide

This guide shows two ways to run the bot: locally with Node.js or using Docker.

Prerequisites

  • Discord account with server admin permissions
  • SourceXchange account
  • Git
  • Node.js 18+ and npm (for local run)
  • Docker (for container run)

Clone the repository

git clone https://github.com/KingIronMan2011/sourcexchange-sync-bot.git
cd sourcexchange-sync-bot

Environment variables

Copy the example env file and edit with your values:

cp .env.example .env

Required vars in .env:

DISCORD_TOKEN=
CLIENT_ID=
API_TOKEN=
PRODUCT_ID=
DISCORD_ROLE_ID=
NODE_ENV=production

Running locally (Node.js)

Install dependencies

npm install

Start the bot

npm start

You should see:

Logged in as YourBotName#1234
Slash commands deployed

Docker

Using the prebuilt image (recommended)

Pull and run the prebuilt image:

docker pull kingjulian2011/sourcexchange-bot:latest
docker run --rm --env-file .env --name sourcexchange-bot kingjulian2011/sourcexchange-bot:latest

Build and run locally

docker build -t sourcexchange-bot:local .
docker run --rm --env-file .env --name sourcexchange-bot sourcexchange-bot:local

Docker Compose

The repository includes docker-compose.yml that uses the prebuilt image by default.

Start the service:

docker compose up -d

Rebuild (if you change Dockerfile or want a local build):

docker compose build
docker compose up -d

CI / Publishing images

A GitHub Actions workflow builds and pushes images to Docker Hub and GHCR on push and workflow_dispatch. Add these repo secrets to enable Docker Hub pushes:

  • DOCKER_USERNAME
  • DOCKER_PASSWORD

GHCR uses the repository GITHUB_TOKEN by default.

Configure Discord application

Create application and bot

  1. Go to the Discord Developer Portal → New Application.
  2. Save the Application ID as CLIENT_ID.
  3. Create a Bot user and copy the bot token → DISCORD_TOKEN.
  4. Enable Server Members Intent under Bot settings if required.

Invite the bot

  1. OAuth2 → URL Generator
  2. Select scopes: bot, applications.commands
  3. Select permissions: Send Messages, Use Slash Commands, Manage Roles
  4. Open generated URL and invite to your server.

Finding Product ID and Role ID

  • Product ID: check your product URL / seller dashboard on SourceXchange.
  • Discord Role ID: enable Developer Mode → right-click role → Copy ID.

Secrets and .env

Keep secrets out of source. Use repository secrets for CI and .env for local runs. Example .env.example is provided.

Troubleshooting

  • Check logs:
    • Docker: docker logs -f sourcexchange-bot
    • Local: console output from npm start
  • Verify env values and that the bot has Manage Roles and required intents.

Production

Use a process manager

PM2 example:

npm install -g pm2
pm2 start bot.ts --name sourcexchange-bot --interpreter node
pm2 save
pm2 startup

Use systemd

Create a systemd unit to run the container or pm2 service (not included here).

Security / Vulnerabilities

  • Do not upgrade global npm inside images unless pinned to a verified patched version.
  • Keep dependencies and base images up to date and commit lockfiles.

Next steps

  • See repository docs for Configuration, User Guide and Troubleshooting.
# SourceXchange Sync Bot

A Discord bot that automatically syncs user roles based on product purchases from [SourceXchange](https://www.sourcexchange.net).

## Installation Guide

This guide shows two ways to run the bot: locally with Node.js or using Docker.

### Prerequisites

- Discord account with server admin permissions  
- SourceXchange account  
- Git  
- Node.js 18+ and npm (for local run)  
- Docker (for container run)

### Clone the repository

```bash
git clone https://github.com/KingIronMan2011/sourcexchange-sync-bot.git
cd sourcexchange-sync-bot

Environment variables

Copy the example env file and edit with your values:

cp .env.example .env

Required vars in .env:

DISCORD_TOKEN=
CLIENT_ID=
API_TOKEN=
PRODUCT_ID=
DISCORD_ROLE_ID=
NODE_ENV=production

Running locally (Node.js)

Install dependencies

npm install

Start the bot

npm start

You should see:

Logged in as YourBotName#1234
Slash commands deployed

Docker

Using the prebuilt image (recommended)

Pull and run the prebuilt image:

docker pull kingjulian2011/sourcexchange-bot:latest
docker run --rm --env-file .env --name sourcexchange-bot kingjulian2011/sourcexchange-bot:latest

Build and run locally

docker build -t sourcexchange-bot:local .
docker run --rm --env-file .env --name sourcexchange-bot sourcexchange-bot:local

Docker Compose

The repository includes docker-compose.yml that uses the prebuilt image by default.

Start the service:

docker compose up -d

Rebuild (if you change Dockerfile or want a local build):

docker compose build
docker compose up -d

CI / Publishing images

A GitHub Actions workflow builds and pushes images to Docker Hub and GHCR on push and workflow_dispatch. Add these repo secrets to enable Docker Hub pushes:

  • DOCKER_USERNAME
  • DOCKER_PASSWORD

GHCR uses the repository GITHUB_TOKEN by default.

Configure Discord application

Create application and bot

  1. Go to the Discord Developer Portal → New Application.
  2. Save the Application ID as CLIENT_ID.
  3. Create a Bot user and copy the bot token → DISCORD_TOKEN.
  4. Enable Server Members Intent under Bot settings if required.

Invite the bot

  1. OAuth2 → URL Generator
  2. Select scopes: bot, applications.commands
  3. Select permissions: Send Messages, Use Slash Commands, Manage Roles
  4. Open generated URL and invite to your server.

Finding Product ID and Role ID

  • Product ID: check your product URL / seller dashboard on SourceXchange.
  • Discord Role ID: enable Developer Mode → right-click role → Copy ID.

Secrets and .env

Keep secrets out of source. Use repository secrets for CI and .env for local runs. Example .env.example is provided.

Troubleshooting

  • Check logs:
    • Docker: docker logs -f sourcexchange-bot
    • Local: console output from npm start
  • Verify env values and that the bot has Manage Roles and required intents.

Production

Use a process manager

PM2 example:

npm install -g pm2
pm2 start bot.ts --name sourcexchange-bot --interpreter node
pm2 save
pm2 startup

Use systemd

Create a systemd unit to run the container or pm2 service (not included here).

Security / Vulnerabilities

  • Do not upgrade global npm inside images unless pinned to a verified patched version.
  • Keep dependencies and base images up to date and commit lockfiles.

Next steps

  • See repository docs for Configuration, User Guide and Troubleshooting.

Clone this wiki locally