Documentation

Getting Started

Bastion is designed to be easy to self-host. The quickest way to get started is with Docker Compose, which sets up the entire stack — backend, database, and cache — in a single command.

git clone https://github.com/Calmingstorm/bastion.git
cd bastion
cp .env.example .env    # Edit with your settings
docker compose up -d

That's it! Open http://localhost:8080 in your browser to access your Bastion instance. The first user to register becomes the server owner.

Requirements

Minimum requirements for self-hosting:

Bastion runs well on budget VPS providers like Linode, DigitalOcean, or Hetzner. A $5/month instance is sufficient for small communities.

Installation

Detailed installation steps:

1. Clone the repository

git clone https://github.com/Calmingstorm/bastion.git
cd bastion

2. Configure environment

cp .env.example .env

Edit .env with your preferred settings. At minimum, change BASTION_JWT_SECRET to a random string. See Configuration for all options.

3. Start the stack

docker compose up -d

4. Verify

# Check all containers are running
docker compose ps

# View logs
docker compose logs -f bastion

Configuration

Bastion is configured via environment variables. All variables support a BASTION_ prefix. Where noted, a shorter fallback name is also accepted.

Server

Database (PostgreSQL)

JWT Authentication

Redis

File Uploads

Email (SMTP)

SMTP is checked first for sending emails. Configure either SMTP or Mailgun (or both as fallback).

Email (Mailgun)

Used as a fallback if SMTP is not configured, or as the primary sender on hosts that block outbound SMTP (e.g. Linode).

GIF Search (Optional)

Set one of these to enable the GIF picker in the client. Tenor takes priority if both are set. The /api/v1/features endpoint reports whether GIF search is enabled.

Reverse Proxy

For production deployments, use a reverse proxy with automatic HTTPS. WebSocket support is required for real-time features. Here's a recommended Caddy configuration:

chat.yourdomain.com {
    reverse_proxy localhost:8080
}

Caddy handles WebSocket upgrades and TLS automatically. Nginx alternative:

server {
    server_name chat.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Bot Development

Bastion supports bots with full API access. Bots authenticate with Authorization: Bot <token> and have their own user identity with the same role and permission system as regular users. Bot messages display a BOT badge.

Creating a Bot

1. Go to Server Settings → Integrations → Bots
2. Click "Create Bot" and give it a name
3. Copy the bot token (prefixed with bot_) — keep it secret!
4. The bot token is hashed with argon2id and cannot be recovered. Use "Regenerate Token" if lost.

Authentication

Bot requests use a different auth scheme than user JWTs. Include the token in the Authorization header:

Authorization: Bot bot_your_token_here

Example: Sending a Message

import requests

TOKEN = "bot_your_token_here"
BASE_URL = "https://your-instance.com/api/v1"

# Send a message to a channel
response = requests.post(
    f"{BASE_URL}/channels/{channel_id}/messages",
    headers={"Authorization": f"Bot {TOKEN}"},
    json={"content": "Hello from my bot!"}
)

WebSocket Events

Bots can connect to the WebSocket at /api/v1/ws using the same Bot token scheme to receive real-time events such as new messages, member joins, and interaction dispatches.

Webhooks

Webhooks let you send messages to channels from external services without a bot user. Create a webhook in Server Settings → Webhooks, then POST to the webhook URL. Webhook tokens are prefixed with whk_.

curl -X POST "https://your-instance.com/api/v1/webhooks/{id}/{token}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deployment successful!", "username": "CI Bot"}'

Webhook execution is rate-limited to 30 requests per minute per IP. No authentication header is needed — the token in the URL serves as the credential.

Slash Commands

Bots can register slash commands that users invoke with / in the message input. Bastion supports three command types:

• Type 1 — Slash commands (e.g. /ping)
• Type 2 — User context menus (right-click a user)
• Type 3 — Message context menus (right-click a message)

Registering a Command

# Register a slash command for your bot
requests.post(
    f"{BASE_URL}/servers/{server_id}/bots/{bot_id}/commands",
    headers={"Authorization": f"Bot {TOKEN}"},
    json={
        "name": "ping",
        "description": "Check if the bot is alive",
        "type": 1
    }
)

Handling Interactions

When a user invokes a command, the server creates an interaction token (15-minute TTL) and dispatches an INTERACTION_CREATE event to your bot via WebSocket. Your bot responds by calling the interaction callback endpoint:

# Respond to an interaction
requests.post(
    f"{BASE_URL}/interactions/{interaction_token}/callback",
    json={
        "content": "Pong! Bot is alive.",
        "ephemeral": True  # Only visible to the invoker
    }
)

If the bot has no active WebSocket connections when a command is invoked, the server returns a 503 BOT_OFFLINE error to the user.

API Overview

Bastion exposes a RESTful API at /api/v1/. All endpoints accept and return JSON. The legacy /api/ prefix redirects to /api/v1/ for backward compatibility.

The server also provides auto-generated API documentation at /api/v1/docs and an OpenAPI 3.0 specification at /api/v1/docs/openapi.yaml.

Authentication

Protected endpoints require an Authorization header. Bastion supports two schemes:

• Bearer <jwt_access_token> — for user sessions
• Bot <bot_token> — for bot integrations

Rate Limiting

Authentication Endpoints

All auth endpoints are public (no token required).

Users

Servers

Channels & Categories

Messages

Direct Messages

Roles & Permissions

Permissions use a bitfield system with per-channel overrides. The computed permissions endpoint returns a member's effective permissions after applying role hierarchy and channel-level overrides.

Moderation

Invites

Bots API

Webhooks API

Interactions API

Search, GIFs & Utilities

WebSocket

Real-time events are delivered via WebSocket at /api/v1/ws. Connect with a valid access token or bot token. The connection supports heartbeat/keepalive and automatic reconnection.

const ws = new WebSocket(
  `wss://your-instance.com/api/v1/ws?token=${accessToken}`
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.type, data.payload);
};

Events include message create/update/delete, typing indicators, presence changes, member updates, channel changes, interaction dispatches, and more.

Troubleshooting