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 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. Here are the key options:

Reverse Proxy

For production deployments, use a reverse proxy with automatic HTTPS. Here's a recommended Caddy configuration:

chat.yourdomain.com {
    reverse_proxy localhost:8080
}

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 a familiar API. Create a bot user in your server settings, then use the bot token to authenticate API requests.

Creating a Bot

1. Go to Server Settings → Bots
2. Click "Create Bot"
3. Give it a name and save
4. Copy the bot token (keep it secret!)

Example: Sending a Message

import requests

TOKEN = "your-bot-token"
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!"}
)

Slash Commands

Register slash commands via the API, then handle interactions via your configured webhook endpoint:

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

API Overview

Bastion exposes a RESTful API at /api/v1/. All endpoints accept and return JSON. Authentication is via Bearer token in the Authorization header.

Key Endpoints

WebSocket connections for real-time events are established at /ws with a valid access token.

Webhooks

Webhooks let you send messages to channels from external services without a bot user. Create a webhook in channel settings, then POST to the webhook URL:

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

Troubleshooting