Skip to content

Commit 69cdd81

Browse files
butschsterbutschster
committed
docs: update documentation for Buggregator v2.0 (Go rewrite)
Rewrite all documentation to reflect the v2.0 architecture: - Go single binary (~30 MB) instead of PHP/RoadRunner/Centrifugo - SQLite (embedded) instead of DoltDB/PostgreSQL/MySQL - New config system: buggregator.yaml, env vars, CLI flags - New pages: Server Configuration, Database, MCP (AI assistants) - Expanded SSO: 6 providers (Auth0, Google, GitHub, Keycloak, GitLab, OIDC) - Removed: RoadRunner config, external database, Sentry JS bundle - Updated: metrics, webhooks, projects, helm-chart, contributing, cookbook - Updated sidebar navigation and LLM metadata - Replaced CI/CD workflow with build+deploy pipeline - Updated Dockerfile to use local checkout instead of git clone
1 parent cc56c74 commit 69cdd81

21 files changed

Lines changed: 1299 additions & 832 deletions

‎.docker/Dockerfile‎

Lines changed: 6 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,11 @@
1-
# Clone the project
2-
FROM alpine/git as git
1+
FROM node:22-slim AS builder
32

4-
ARG REPOSITORY=https://github.com/buggregator/docs
5-
ARG BRANCH=master
6-
RUN git clone -b $BRANCH $REPOSITORY /app
7-
8-
FROM node:19 as node
9-
10-
COPY --from=git /app /app
113
WORKDIR /app
4+
COPY package.json package-lock.json ./
5+
RUN npm ci
126

13-
RUN npm add -D vitepress
14-
RUN npm i
7+
COPY . .
158
RUN npm run docs:build
169

17-
FROM nginx:alpine as server
18-
19-
COPY --from=node /app/docs/.vitepress/dist /usr/share/nginx/html
10+
FROM nginx:alpine
11+
COPY --from=builder /app/docs/.vitepress/dist /usr/share/nginx/html

‎.github/workflows/deploy.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: Build & Deploy Docs
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
8+
env:
9+
REGISTRY: ghcr.io
10+
IMAGE: ghcr.io/${{ github.repository }}
11+
12+
jobs:
13+
# ── Build docs Docker image ───────────────────────────────
14+
build:
15+
runs-on: ubuntu-latest
16+
if: "!github.event.release.prerelease"
17+
permissions:
18+
contents: read
19+
packages: write
20+
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- name: Log in to GitHub Container Registry
25+
uses: docker/login-action@v3
26+
with:
27+
registry: ${{ env.REGISTRY }}
28+
username: ${{ github.actor }}
29+
password: ${{ secrets.GITHUB_TOKEN }}
30+
31+
- name: Set up Docker Buildx
32+
uses: docker/setup-buildx-action@v3
33+
34+
- name: Build and push
35+
uses: docker/build-push-action@v6
36+
with:
37+
context: .
38+
file: .docker/Dockerfile
39+
push: true
40+
platforms: linux/amd64,linux/arm64
41+
tags: |
42+
${{ env.IMAGE }}:latest
43+
${{ env.IMAGE }}:${{ github.event.release.tag_name || github.sha }}
44+
cache-from: type=gha,scope=docs
45+
cache-to: type=gha,mode=max,scope=docs
46+
47+
# ── Deploy to production server ─────────────────────────────
48+
deploy:
49+
runs-on: ubuntu-latest
50+
needs: [build]
51+
if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
52+
53+
steps:
54+
- name: Connect to WireGuard VPN
55+
run: |
56+
sudo apt-get install -y wireguard
57+
echo "${{ secrets.WG_CONFIG }}" | sudo tee /etc/wireguard/wg0.conf > /dev/null
58+
sudo chmod 600 /etc/wireguard/wg0.conf
59+
sudo wg-quick up wg0
60+
61+
- name: Deploy via SSH
62+
uses: appleboy/ssh-action@v1
63+
with:
64+
host: ${{ secrets.DEPLOY_HOST }}
65+
port: ${{ secrets.DEPLOY_SSH_PORT || 22 }}
66+
username: ${{ secrets.DEPLOY_USER }}
67+
key: ${{ secrets.DEPLOY_SSH_KEY }}
68+
script: |
69+
cd /servers/buggregator.dev.v2
70+
71+
# Pull latest docs image
72+
docker compose pull buggregator-docs
73+
74+
# Restart docs container with new image
75+
docker compose up -d buggregator-docs
76+
77+
# Clean up old images
78+
docker image prune -f

‎.github/workflows/docker-image.yml‎

Lines changed: 0 additions & 48 deletions
This file was deleted.

‎docs/.vitepress/config.mts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,11 +77,12 @@ export default defineConfig({
7777
{
7878
text: 'Configuration',
7979
items: [
80-
{text: 'RoadRunner', link: '/config/roadrunner'},
80+
{text: 'Server', link: '/config/server'},
81+
{text: 'Database', link: '/config/database'},
8182
{text: 'Projects', link: '/config/projects'},
8283
{text: 'Webhooks', link: '/config/webhooks'},
8384
{text: 'Single Sign On (SSO)', link: '/config/sso'},
84-
{text: 'External Database', link: '/config/external-db'},
85+
{text: 'MCP (AI Assistants)', link: '/config/mcp'},
8586
{text: 'Helm Chart', link: '/config/helm-chart'},
8687
{text: 'Metrics', link: '/config/metrics'},
8788
]
@@ -91,7 +92,7 @@ export default defineConfig({
9192
text: 'Cookbook',
9293
items: [
9394
{text: 'Dev environment using docker', link: '/cookbook/docker-install'},
94-
{text: 'Dev environment', link: '/cookbook/manual-install'},
95+
{text: 'Manual installation', link: '/cookbook/manual-install'},
9596
]
9697
},
9798

‎docs/config/database.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
llms_description: "Database configuration: SQLite with in-memory (default, data lost on restart) or file-based persistence. Environment variable DATABASE_DSN. Storage modes for attachments: memory or filesystem. Docker volume examples for persistent data."
3+
---
4+
5+
# Configuration — Database
6+
7+
Buggregator uses [SQLite](https://www.sqlite.org/) as its database. SQLite is embedded directly into the binary —
8+
no external database server is needed.
9+
10+
## Storage Modes
11+
12+
### In-Memory (Default)
13+
14+
By default, Buggregator stores everything in memory. This is the fastest option but **all data is lost when the
15+
server restarts**.
16+
17+
```yaml
18+
database:
19+
dsn: ":memory:"
20+
```
21+
22+
This is the default — no configuration needed.
23+
24+
### File-Based
25+
26+
To persist data across restarts, specify a file path:
27+
28+
```yaml
29+
database:
30+
dsn: data.db
31+
```
32+
33+
Or via environment variable:
34+
35+
```bash
36+
DATABASE_DSN=data.db
37+
```
38+
39+
The database file will be created next to the binary (or at the specified path). In Docker, make sure to
40+
mount a volume:
41+
42+
```bash
43+
docker run --pull always \
44+
-p 127.0.0.1:8000:8000 \
45+
-e DATABASE_DSN=/data/buggregator.db \
46+
-v buggregator-data:/data \
47+
ghcr.io/buggregator/server:latest
48+
```
49+
50+
### Docker Compose Example
51+
52+
```yaml
53+
services:
54+
buggregator:
55+
image: ghcr.io/buggregator/server:latest
56+
ports:
57+
- 127.0.0.1:8000:8000
58+
- 127.0.0.1:1025:1025
59+
- 127.0.0.1:9912:9912
60+
- 127.0.0.1:9913:9913
61+
environment:
62+
DATABASE_DSN: /data/buggregator.db
63+
STORAGE_MODE: filesystem
64+
STORAGE_PATH: /data/storage
65+
volumes:
66+
- buggregator-data:/data
67+
68+
volumes:
69+
buggregator-data:
70+
```
71+
72+
## Attachment Storage
73+
74+
SMTP attachments and HTTP dump files are stored separately from the database. Two modes are available:
75+
76+
| Mode | Environment Variable | Description |
77+
|------|---------------------|-------------|
78+
| `memory` (default) | `STORAGE_MODE=memory` | Stored in RAM. Fast but lost on restart. |
79+
| `filesystem` | `STORAGE_MODE=filesystem` | Stored on disk in the directory specified by `STORAGE_PATH`. |
80+
81+
```yaml
82+
storage:
83+
mode: filesystem
84+
path: ./storage
85+
```
86+
87+
> **Tip:** If you use `DATABASE_DSN=:memory:` but `STORAGE_MODE=filesystem`, the event metadata will be lost on
88+
> restart but the attachment files will remain on disk (orphaned). For consistency, either persist both or
89+
> keep both in memory.
90+
91+
## Migrations
92+
93+
Buggregator automatically creates and migrates database tables on startup. No manual migration steps are required.

‎docs/config/external-db.md‎

Lines changed: 0 additions & 120 deletions
This file was deleted.

0 commit comments

Comments
 (0)