A Discord soundboard with a browser UI.
BardBoard lets you play sound effects, music, and voice lines into a Discord voice channel from a clean web interface. It is designed for tabletop sessions, watch parties, and any server where quick audio cues are useful.
- Quick Start
- Features
- Requirements
- Discord Bot Setup
- Run With Docker
- Run Locally
- Adding Sounds
- Using BardBoard
- Configuration
- Troubleshooting
- Development
- Contributing
- License
After creating and inviting a Discord bot, start BardBoard from the repository root:
docker compose up --build -d --waitOpen http://localhost:3000, enter the bot token and admin credentials on the
setup page, then save. The containers restart automatically when required.
- Browser-based soundboard for Discord voice channels.
- One-click playback with volume, pause/resume, stop, repeat, and seeking.
- Playlist queue with drag-and-drop ordering.
- Drag tracks into the playlist to queue them.
- Upload audio from the browser by browsing or dragging files into the upload modal.
- Organize tracks into categories.
- Drag tracks between categories to move files on disk.
- Create categories manually or by dragging a track to the "New Category" drop zone.
- Rename or delete tracks and categories from the UI.
- Required admin authentication with an optional readonly account.
- First-run setup page: no manual
.envfile is required for Docker. - Swagger UI at
/api-docs.
For the normal Docker setup:
- Docker Desktop or Docker Engine with Docker Compose.
- A Discord bot token.
- A Discord server where you can invite the bot.
For local development without Docker:
- Node.js 24.
ffmpegavailable in yourPATH.- Platform audio dependencies required by Discord voice packages.
- Create a Discord application in the Discord Developer Portal.
- Create a bot and copy its token.
- In OAuth2 -> URL Generator, select the
botscope. - Give the bot at least Connect and Speak permissions.
- Open the generated invite URL and add the bot to your server.
Keep the bot token private. Do not commit it.
The Docker setup does not require a host .env file. On first start, BardBoard creates a config file inside the Docker volume bardboard-config and sends you to the setup page.
- Clone or download this repository.
- Open a terminal in the project folder.
- Start the app:
docker compose up --build -d --wait- Open
http://localhost:3000. - Complete the first-run setup page:
- Discord bot token.
- Admin username.
- Admin password.
- Optional readonly user.
- Save and restart when prompted.
After setup, configuration is stored in the named Docker volume:
bardboard-config:/usr/src/app/config
Audio files and sessions are mounted from the project folder:
./audio-files -> /usr/src/app/audio-files
./sessions -> /usr/src/app/sessions
The production image runs as the unprivileged node user (UID/GID 1000) and
both services enable a small init process plus no-new-privileges. On Linux,
make sure the bind-mounted directories are writable before the first start:
mkdir -p audio-files sessions
sudo chown -R 1000:1000 audio-files sessionsOnly the bot container reads the optional host .env; the web container receives
only its proxy URL and port, so Discord tokens and login credentials are not copied
into the public-facing process environment.
A host .env file is optional. Compose uses it for deployment values and the bot
can use its values to seed a missing config volume. Explicit deployment values
(WEB_PORT, BOT_PORT, BACKEND_URL, UPLOAD_MAX_MB, and the container session
path) take precedence over stale values in the persisted file. For bot credentials
and other application settings, the persisted config volume remains authoritative;
change them from the admin UI after first-run setup.
Example:
WEB_PORT=3000
BOT_PORT=3001
UPLOAD_MAX_MB=50
SESSION_HOST_DIR=./sessionsSESSION_HOST_DIR selects the directory on the Docker host. Inside the bot
container it is always mounted at /usr/src/app/sessions; keep the application
setting SESSION_DIR=./sessions when using Docker. BACKEND_URL is configured
automatically by Compose and normally should not be overridden.
If you change a port or SESSION_HOST_DIR, recreate the containers. Changes to
UPLOAD_MAX_MB also require rebuilding the web image because Next.js reads the
proxy upload limit during its production build:
docker compose up --build -d --waitBoth services have health checks and restart automatically after a crash or host
restart. The bot handles SIGTERM/SIGINT by stopping HTTP traffic, Discord audio,
FFmpeg processes, voice connections, and the Discord client before exiting.
docker compose ps
docker compose restart bard-board-bot
docker compose logs -f --tail=200Docker JSON logs rotate at 10 MB, retaining three files per service, so an
unattended installation cannot grow a single container log indefinitely.
The default Compose setup publishes only the web UI; the bot/API port remains on the internal Docker network. Do not publish the bot/API port directly.
http://localhost:3000 is suitable for access from the Docker host. If BardBoard
is reachable from another machine or from the internet, place it behind an HTTPS
reverse proxy and restrict access with a firewall or private network. Login
credentials and session cookies must not travel over an unencrypted public
connection.
Back up the persisted data before an update, then fetch the new code and recreate the services from a freshly pulled base image:
git pull --ff-only
docker compose build --pull
docker compose up -d --wait
docker compose psAfter confirming that both services are healthy, old unused images can be removed
manually with docker image prune if disk space is needed.
The config backup contains the Discord token and account credentials. Keep the
backups directory private; it is excluded from Git. For a consistent backup,
briefly stop both services and copy the named volume plus bind-mounted data.
PowerShell:
$BackupDir = "backups/$(Get-Date -Format yyyyMMdd-HHmmss)"
$SessionHostDir = "./sessions" # Match SESSION_HOST_DIR when customized.
New-Item -ItemType Directory -Force "$BackupDir/config" | Out-Null
docker compose stop
try {
docker compose cp bard-board-bot:/usr/src/app/config/. "$BackupDir/config"
Copy-Item audio-files "$BackupDir/audio-files" -Recurse -Force
if (Test-Path $SessionHostDir) { Copy-Item $SessionHostDir "$BackupDir/sessions" -Recurse -Force }
} finally {
docker compose start
}Bash:
set -e
BACKUP_DIR="backups/$(date +%Y%m%d-%H%M%S)"
SESSION_HOST_DIR="./sessions" # Match SESSION_HOST_DIR when customized.
mkdir -p "$BACKUP_DIR/config"
docker compose stop
trap 'docker compose start' EXIT
docker compose cp bard-board-bot:/usr/src/app/config/. "$BACKUP_DIR/config"
cp -a audio-files "$BACKUP_DIR/audio-files"
if [ -d "$SESSION_HOST_DIR" ]; then cp -a "$SESSION_HOST_DIR" "$BACKUP_DIR/sessions"; fi
docker compose start
trap - EXITRestore only from a trusted backup. Check that both the configuration and audio directories exist before stopping BardBoard. The following commands replace the current audio, sessions, and persisted configuration.
PowerShell:
$BackupDir = "backups/20260904-120000" # Select an existing backup explicitly.
$SessionHostDir = "./sessions" # Match SESSION_HOST_DIR when customized.
if (!(Test-Path "$BackupDir/config") -or !(Test-Path "$BackupDir/audio-files")) {
throw "The selected backup is incomplete: $BackupDir"
}
docker compose down --volumes
if (Test-Path audio-files) { Remove-Item audio-files -Recurse -Force }
Copy-Item "$BackupDir/audio-files" audio-files -Recurse -Force
if (Test-Path $SessionHostDir) { Remove-Item $SessionHostDir -Recurse -Force }
if (Test-Path "$BackupDir/sessions") { Copy-Item "$BackupDir/sessions" $SessionHostDir -Recurse -Force }
if (!(Test-Path $SessionHostDir)) { New-Item -ItemType Directory -Force $SessionHostDir | Out-Null }
docker compose create bard-board-bot
docker compose cp "$BackupDir/config/." bard-board-bot:/usr/src/app/config
docker compose run --rm --no-deps --user root bard-board-bot chown -R node:node /usr/src/app/config
docker compose up -d --waitBash:
set -e
BACKUP_DIR="backups/20260904-120000" # Select an existing backup explicitly.
SESSION_HOST_DIR="./sessions" # Match SESSION_HOST_DIR when customized.
if [ ! -d "$BACKUP_DIR/config" ] || [ ! -d "$BACKUP_DIR/audio-files" ]; then
echo "The selected backup is incomplete: $BACKUP_DIR" >&2
exit 1
fi
docker compose down --volumes
rm -rf audio-files "$SESSION_HOST_DIR"
cp -a "$BACKUP_DIR/audio-files" audio-files
if [ -d "$BACKUP_DIR/sessions" ]; then cp -a "$BACKUP_DIR/sessions" "$SESSION_HOST_DIR"; fi
mkdir -p "$SESSION_HOST_DIR"
docker compose create bard-board-bot
docker compose cp "$BACKUP_DIR/config/." bard-board-bot:/usr/src/app/config
docker compose run --rm --no-deps --user root bard-board-bot chown -R node:node /usr/src/app/config
sudo chown -R 1000:1000 audio-files "$SESSION_HOST_DIR"
docker compose up -d --waitRun docker compose ps afterwards and confirm both services report healthy.
This deletes the persisted BardBoard config volume. Audio files and sessions use bind mounts and are not removed by this command.
docker compose down --volumes
docker compose up --build -d --waitLocal development also supports first-run setup. If .env is missing, the backend creates one in the project root and the web UI redirects to /setup.
- Install dependencies:
npm ci- Start the bot/API and web app:
npm run dev- Open
http://localhost:3000. - Complete the setup page if prompted.
You can also copy .env.sample to .env and pre-fill values manually.
Supported formats:
- MP3
- WAV
- OGG
- M4A
You can add sounds in two ways.
Click Add Song, then drag files into the upload modal or browse for files. You can:
- Upload multiple files at once.
- Remove files from the pending upload list.
- Choose an existing category.
- Create a new category during upload.
- See upload progress.
Put audio files in audio-files/ and refresh the page.
Use first-level folders for categories:
audio-files/
Tavern.mp3
Intro.ogg
Combat/
Clash.mp3
Bash.wav
Roar.ogg
NPCs/
Merchant.mp3
Guard.mp3
This creates root tracks plus Combat and NPCs sections in the UI.
Open the web UI, select a Discord voice channel, then click a track.
- Click a track to play it immediately.
- Use the mini buttons on each track to add to playlist, rename, or delete.
- Drag tracks between categories to move the underlying audio file.
- Drag tracks to the playlist to queue them without moving the file.
- Categories can be expanded and collapsed.
- Rename or delete categories from the category header.
- Drag a track to another category to move it.
- Drag a track to New Category to create a category and move the track into it.
- Select the Discord voice channel.
- Adjust volume.
- Mute and restore volume.
- Pause/resume.
- Repeat the current track.
- Stop playback.
- Seek within the current track using the progress bar.
- Queue tracks from the soundboard.
- Drag tracks into the playlist panel.
- Reorder queued tracks with drag and drop.
- Shuffle, clear, play queue, or skip.
The settings page is available to admins. It shows editable runtime configuration values. Changes that affect bot login, auth, rate limits, or sessions require a restart.
BardBoard reads configuration from:
- Docker:
/usr/src/app/config/.envby default, persisted in thebardboard-configvolume. - Local development:
./.envby default. - Custom path: set
BARDBOARD_ENV_PATH. - Process environment variables, used as defaults when generating a missing config file.
- Explicit deployment environment values for ports, proxying, uploads, and the container session path, which take precedence over persisted values.
SESSION_HOST_DIR is a Docker Compose variable rather than an application setting,
so it is not shown or edited by the BardBoard settings page.
The setup page requires:
DISCORD_TOKENAUTH_ADMIN_USERAUTH_ADMIN_PASS
AUTH_READONLY_USER and AUTH_READONLY_PASS are optional.
| Variable | Required | Default | Description | Apply method |
|---|---|---|---|---|
DISCORD_TOKEN |
Yes | empty | Discord bot token. | Restart |
AUTH_ADMIN_USER |
Yes for setup | empty | Admin username. | Restart |
AUTH_ADMIN_PASS |
Yes for setup | empty | Admin password. | Restart |
AUTH_READONLY_USER |
No | empty | Optional readonly username. | Restart |
AUTH_READONLY_PASS |
No | empty | Optional readonly password. | Restart |
SESSION_SECRET |
Recommended | generated | Session signing secret. | Restart |
LOGIN_REMEMBER_DAYS |
No | 30 |
Remember-me cookie duration. | Restart |
SESSION_DIR |
No | ./sessions |
Application session path. Keep ./sessions in Docker. |
Restart |
SESSION_HOST_DIR |
No | ./sessions |
Docker host directory mounted for session persistence. | Recreate containers |
NOISES_FOLDER |
No | !noises |
Category folder used for overlay noises. | Restart |
NOISES_VOLUME |
No | 2 |
Overlay noise gain (1 = original level, 2 = double amplitude; range 0-10). |
Restart |
RATE_LIMIT_AUDIO |
No | 120 |
Requests/minute for audio actions. | Restart |
RATE_LIMIT_FILES |
No | 60 |
Requests/minute for file actions. | Restart |
RATE_LIMIT_AUDIO_STATUS |
No | 600 |
Requests/minute for status polling. | Restart |
RATE_LIMIT_PLAYLIST |
No | 120 |
Requests/minute for playlist actions. | Restart |
CORS_ORIGINS |
No | empty | Comma-separated allowed origins. | Restart |
SESSION_FILE_RETRIES |
No | 5 |
Session file-store retry attempts. | Restart |
SESSION_FILE_RETRY_FACTOR |
No | 1 |
Session file-store retry backoff factor. | Restart |
SESSION_FILE_RETRY_MIN_MS |
No | 50 |
Minimum session retry delay in ms. | Restart |
SESSION_FILE_RETRY_MAX_MS |
No | 200 |
Maximum session retry delay in ms. | Restart |
SESSION_WRITE_RETRIES |
No | 6 |
Extra retries for transient file-lock races. | Restart |
WEB_PORT |
No | 3000 |
Web UI port. | Recreate containers |
BOT_PORT |
No | 3001 |
Bot/API port. | Recreate containers |
BACKEND_URL |
No | http://localhost:3001 |
Next.js API proxy target; Compose sets it automatically. | Restart locally; Docker-managed |
UPLOAD_MAX_MB |
No | 50 |
Max upload size per file in MB. | Rebuild containers |
BARDBOARD_ENV_PATH |
No | varies | Path to the config file. Docker sets this automatically. | Restart |
Docker does not rely on the project-root .env for persisted app configuration. It writes setup values to the bardboard-config volume at /usr/src/app/config/.env.
If you want to reset Docker setup, remove the config volume as shown in Reset Docker First-Run Setup.
- Make sure the bot is invited to your server.
- Make sure the bot has Connect and Speak permissions.
- Select a voice channel in the BardBoard header.
- Check logs:
docker compose logs -f- Check the Discord token in setup/settings.
- Restart the bot container:
docker compose restart bard-board-bot- Add supported audio files to
audio-files/. - Refresh the page.
- Use first-level subfolders only for categories.
- Use the admin credentials configured during first-run setup.
- If credentials were changed, old sessions may no longer be valid.
- Restart after changing auth-related settings.
- Swagger UI:
http://localhost:3000/api-docs - Raw OpenAPI JSON:
http://localhost:3000/api-docs.json
Useful commands:
npm ci
npm run dev
npm run build
npm run start
npm run lint
npm test
npm audit --omit=dev --audit-level=highUse npm install instead when intentionally adding, removing, or updating a
dependency so that npm can update package-lock.json.
Run the bot API test suite with:
npm testThe tests send real HTTP requests to temporary local Express servers and replace
Discord voice primitives with in-memory test doubles. They cover audio controls,
playback state, authentication and permissions, CORS, file and category management,
uploads, configuration, channel switching, and playlist behavior without requiring a
Discord token, a voice channel, ffmpeg, or a running application.
Generate a source coverage report with:
npm run test:coverageThe coverage command also enforces minimum project-wide thresholds of 90% for lines, 70% for branches, and 85% for functions. The CI fails if a change drops below any of these gates. Process-lifecycle tests exercise production restart and graceful signal handling, while filesystem and concurrency tests cover atomic config writes, partial uploads, simultaneous uploads, file mutations, playlists, and session creation.
Run the Chromium end-to-end tests with:
npx playwright install chromium
npm run test:e2eThe end-to-end suite builds and starts the real Next.js application, then checks
login, persistent sessions and logout, first-boot setup, settings permissions and
validation, voice-channel selection, playback, audio upload/rename/move/delete flows,
playlist reordering and commands, and visible API error feedback in a browser. Most
Discord API responses are intercepted for determinism; a dedicated smoke test instead
uses Next.js's real proxy and an isolated Express server with a fake Discord channel.
No real bot token or Discord connection is required. Ports 3001 and 3100 must be
available while the end-to-end suite runs.
Validate the production Docker deployment with:
npm run test:dockerThis smoke test validates the Compose configuration, builds the production image,
starts the API and web containers under an isolated project name, waits for both
health checks, and calls /api/health through the web proxy. It also verifies the
non-root user, secret isolation, init/security and log settings, graceful restart,
automatic recovery after forced container termination, and a real config-volume
backup/restore cycle. It chooses a free web port automatically and removes its
containers, network, volume, and temporary files when finished. Docker with Compose
must be running.
GitHub Actions runs unit/API tests, lint, a production dependency audit, Chromium end-to-end tests, this Docker smoke test, and a blocking Trivy scan for fixable high or critical image vulnerabilities on every push and pull request.
The project uses:
- Next.js 16
- React 19
- Express 5
- Discord.js 14
- Node.js 24
package.json includes a targeted postcss override because the current Next.js release depends on a vulnerable PostCSS range. Keep this override until Next.js ships a patched dependency.
Issues and pull requests are welcome.
For bugs, include:
- What you expected.
- What happened.
- Relevant logs from
docker compose logs -f. - Browser console errors if the issue is UI-related.
BardBoard is licensed under the GNU General Public License v3.0. See LICENSE.md.
