Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
ef7398d
helm deployment
TheTechromancer Feb 20, 2026
69bc494
ruffed
TheTechromancer Feb 20, 2026
554e4c5
fix test?
TheTechromancer Feb 20, 2026
db88be4
fix docker tests?
TheTechromancer Feb 20, 2026
d290ca3
publish dev images
TheTechromancer Feb 20, 2026
832ec28
fix docker tests?
TheTechromancer Feb 20, 2026
9efba59
fix docker tests?
TheTechromancer Feb 20, 2026
ba97414
helm and docker publishing
TheTechromancer Feb 25, 2026
512c534
auto docker publishing, helm
TheTechromancer Feb 25, 2026
41076b8
Merge pull request #128 from blacklanternsecurity/helmifying
TheTechromancer Feb 26, 2026
08dfe1a
consolidate dbs
TheTechromancer Feb 26, 2026
2587f61
fix ci
TheTechromancer Feb 26, 2026
ef59239
show diff
TheTechromancer Feb 26, 2026
703b40d
ruffed
TheTechromancer Feb 26, 2026
80c5039
bump version
TheTechromancer Feb 26, 2026
f529297
Merge pull request #130 from blacklanternsecurity/helmifying
TheTechromancer Feb 26, 2026
e881297
don't run helm stuff in main pytest
TheTechromancer Feb 26, 2026
4d1bd8a
Merge branch 'dev' into consolidate-dbs
TheTechromancer Feb 26, 2026
fdc0a6e
persistence, ci
TheTechromancer Feb 26, 2026
04c7c47
watchdog -> worker
TheTechromancer Feb 26, 2026
8eaa529
helm ci
TheTechromancer Feb 26, 2026
4ce6960
Merge pull request #132 from blacklanternsecurity/consolidate-dbs
TheTechromancer Feb 26, 2026
1795039
Merge branch 'dev' into rename-watchdog
TheTechromancer Feb 26, 2026
b7eeb04
merge dev, bump version
TheTechromancer Feb 26, 2026
17e2c03
Merge pull request #133 from blacklanternsecurity/rename-watchdog
TheTechromancer Feb 26, 2026
71dd1ad
docker compose dev / prod, better tests, support custom mongo
TheTechromancer Feb 26, 2026
8d47d49
compose file
TheTechromancer Feb 26, 2026
2dc4f7a
ruffed
TheTechromancer Feb 26, 2026
854e1d6
unify docker and helm tests
TheTechromancer Feb 27, 2026
d479478
fix prod image
TheTechromancer Feb 27, 2026
96e3066
Merge pull request #134 from blacklanternsecurity/docker-compose-prod
ausmaster Feb 27, 2026
221aa83
fix lock
TheTechromancer Feb 27, 2026
2e3f4a6
fix helm test
TheTechromancer Feb 27, 2026
4a4e701
Merge pull request #135 from blacklanternsecurity/docker-compose-prod
TheTechromancer Feb 27, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 110 additions & 13 deletions .github/workflows/docker-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,43 @@ jobs:
run: |
BBOT_SERVER_TEST_DOCKER_COMPOSE=true uv run pytest --disable-warnings --log-cli-level=INFO -k test_docker_compose

helm-test:
runs-on: ubuntu-latest

steps:
- name: Checkout code
uses: actions/checkout@v6

- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: '3.x'

- name: Install Python dependencies
run: pip install requests

- name: Install kubectl
uses: azure/setup-kubectl@v4

- name: Install Helm
uses: azure/setup-helm@v4

- name: Install minikube
uses: medyagh/setup-minikube@latest

- name: Run helm deployment tests
run: python helm_deployment_test.py

- name: Cleanup minikube
if: always()
run: minikube delete

docker-publish:
runs-on: ubuntu-latest
needs: docker-test
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/stable' }}
needs:
- helm-test
- docker-test
if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/stable' || github.ref == 'refs/heads/dev') }}

steps:
- name: Checkout code
Expand Down Expand Up @@ -61,39 +94,103 @@ jobs:
images: blacklanternsecurity/bbot-server
tags: |
type=ref,event=branch
type=ref,event=pr
type=sha,prefix=sha-
type=raw,value=latest,enable={{is_default_branch}}
type=raw,value=v${{ steps.version.outputs.major }}
type=raw,value=v${{ steps.version.outputs.minor }}
type=raw,value=v${{ steps.version.outputs.version }}
type=raw,value=latest,enable=${{ github.ref == 'refs/heads/stable' }}
type=raw,value=v${{ steps.version.outputs.major }},enable=${{ github.ref == 'refs/heads/stable' }}
type=raw,value=v${{ steps.version.outputs.minor }},enable=${{ github.ref == 'refs/heads/stable' }}
type=raw,value=v${{ steps.version.outputs.version }},enable=${{ github.ref == 'refs/heads/stable' }}

- name: Build and push Docker image
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
cache-from: type=gha
cache-to: type=gha,mode=max

- name: Clean up old Docker Hub tags (up to 50 most recent tags plus 'latest')
- name: Clean up old Docker Hub tags (keep 50 most recent plus protected tags)
run: |
# Install jq for JSON processing
sudo apt-get update && sudo apt-get install -y jq

echo "Cleaning up bbot-server tags..."

# Protected tags that should never be deleted
PROTECTED="latest stable dev v${{ steps.version.outputs.major }} v${{ steps.version.outputs.minor }} v${{ steps.version.outputs.version }}"

tags_response=$(curl -s -H "Authorization: Bearer ${{ secrets.DOCKER_TOKEN }}" \
"https://hub.docker.com/v2/repositories/bbot-server}/tags/?page_size=100")
"https://hub.docker.com/v2/repositories/blacklanternsecurity/bbot-server/tags/?page_size=100")

tags_to_delete=$(echo "$tags_response" | jq -r '.results[] | select(.name != "latest") | [.last_updated, .name] | @tsv' | \
sort -r | tail -n +51 | cut -f2)
tags_to_delete=$(echo "$tags_response" | jq -r '.results[].name' | sort -r | tail -n +51)

for tag in $tags_to_delete; do
# Skip protected tags
if echo "$PROTECTED" | grep -qw "$tag"; then
echo "Skipping protected tag: $tag"
continue
fi
echo "Deleting bbot-server tag: $tag"
curl -X DELETE -H "Authorization: Bearer ${{ secrets.DOCKER_TOKEN }}" \
"https://hub.docker.com/v2/repositories/bbot-server/tags/$tag/"
"https://hub.docker.com/v2/repositories/blacklanternsecurity/bbot-server/tags/$tag/"
done

echo "Cleanup completed for bbot-server. Kept 50 most recent tags plus 'latest'."
echo "Cleanup completed for bbot-server."


helm-publish:
runs-on: ubuntu-latest
needs:
- helm-test
- docker-test
if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/stable' || github.ref == 'refs/heads/dev') }}

steps:
- name: Checkout code
uses: actions/checkout@v6

- name: Install uv
uses: astral-sh/setup-uv@v7

- name: Get version from pyproject.toml
id: version
run: |
VERSION=$(uv version --short)
echo "version=$VERSION" >> $GITHUB_OUTPUT

- name: Install Helm
uses: azure/setup-helm@v4

- name: Update Chart.yaml version and appVersion
run: |
VERSION="${{ steps.version.outputs.version }}"
CHART_VERSION="$VERSION"
IMAGE_TAG="stable"
if [ "${{ github.ref }}" = "refs/heads/dev" ]; then
CHART_VERSION="${VERSION}-dev"
IMAGE_TAG="dev"
fi
sed -i "s/^version:.*/version: ${CHART_VERSION}/" helm/Chart.yaml
sed -i "s/^appVersion:.*/appVersion: \"${VERSION}\"/" helm/Chart.yaml
# ensure the packaged chart defaults to the correct docker image tag
sed -i "s/^ tag:.*/ tag: \"${IMAGE_TAG}\"/" helm/values.yaml
echo "Chart version: $CHART_VERSION"
echo "App version: $VERSION"
echo "Image tag: $IMAGE_TAG"
cat helm/Chart.yaml

- name: Add Helm repositories
run: helm repo add bitnami https://charts.bitnami.com/bitnami

- name: Build Helm dependencies
run: helm dependency build helm/

- name: Package Helm chart
run: helm package helm/

- name: Login to Docker Hub OCI registry
run: echo "${{ secrets.DOCKER_TOKEN }}" | helm registry login registry-1.docker.io -u blacklanternsecurity --password-stdin

- name: Push Helm chart to Docker Hub
run: helm push bbot-server-*.tgz oci://registry-1.docker.io/blacklanternsecurity
44 changes: 43 additions & 1 deletion .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ jobs:
- name: Lint
run: |
uv run ruff check
uv run ruff format --check
uv run ruff format --diff
- name: Run tests
run: |
NO_COLOR=true uv run pytest --reruns 2 --disable-warnings --log-cli-level=INFO --cov-report xml:cov.xml --cov=bbot_server .
Expand All @@ -47,3 +47,45 @@ jobs:
token: ${{ secrets.CODECOV_TOKEN }}
files: ./cov.xml
verbose: true

publish_pypi:
needs: test
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/stable'
continue-on-error: true
steps:
- uses: actions/checkout@v6
- name: Install uv
uses: astral-sh/setup-uv@v7
- name: Get version
id: calc_version
run: |
VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
echo "Version: $VERSION"
- name: Build PyPI package
run: uv build
- name: Publish PyPI package
uses: pypa/gh-action-pypi-publish@release/v1.13
with:
password: ${{ secrets.PYPI_API_TOKEN }}
outputs:
VERSION: ${{ steps.calc_version.outputs.VERSION }}

tag_commit:
needs: publish_pypi
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/stable'
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Configure git
run: |
git config --local user.email "info@blacklanternsecurity.com"
git config --local user.name "GitHub Actions"
- name: Tag commit
run: |
VERSION="v${{ needs.publish_pypi.outputs.VERSION }}"
git tag -a "$VERSION" -m "Stable Release $VERSION"
git push origin "$VERSION"
7 changes: 6 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
FROM ghcr.io/astral-sh/uv:python3.11-trixie
RUN apt-get -y update && apt-get -y install curl jq
COPY . /app
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project
COPY . .
RUN cp bbot_server/defaults_docker.yml bbot_server/defaults.yml
RUN uv sync --frozen
RUN useradd -u 1000 -m bbot && chown -R bbot:bbot /app
USER bbot
ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8807
CMD ["uv", "run", "bbctl", "server", "start", "--api-only"]
107 changes: 100 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,28 +24,121 @@ BBOT Server is a database and multiplayer hub for all your [BBOT](https://github
## Installation

```bash
# clone the repo and cd into it
git clone git@github.com:blacklanternsecurity/bbot-server.git && cd bbot-server
# install with uv (recommended)
uv tool install bbot-server

# or with pipx
pipx install bbot-server
```

To install `uv`, see the [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).

### From source (for development)

# Install dependencies and create virtual environment
```bash
git clone git@github.com:blacklanternsecurity/bbot-server.git && cd bbot-server
uv sync
```

Note: to update to the latest version, run `git pull && uv sync` in the `bbot-server` directory.

To install `uv`, see the [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).

Commands shown below as `bbctl` can be run with `uv run bbctl` from the project directory, or you can activate the virtual environment first with `source .venv/bin/activate`.
When installed from source, commands shown below as `bbctl` can be run with `uv run bbctl` from the project directory, or you can activate the virtual environment first with `source .venv/bin/activate`.

## Start the server

Note: this requires Docker and Docker Compose to be installed.

```bash
# Start BBOT server using Docker Compose
# Start BBOT server using Docker Compose (pulls from Docker Hub)
bbctl server start
```

### Development mode

When working on the bbot-server source code, use `--dev` to build from source and mount your code for live reload:

```bash
# From the bbot-server repo root
bbctl server --dev start
```

The `--dev` flag works with all server subcommands (`start`, `stop`, `down`, `logs`, `status`, `compose`).

## Deploy with Helm (Kubernetes)

BBOT Server can be deployed to Kubernetes using its official Helm chart. The chart deploys the API server, worker, MongoDB, and Redis.

### Quick Start

```bash
# Add the Helm repo
helm repo add blacklanternsecurity https://blacklanternsecurity.github.io/bbot-server

# Install
helm install bbot blacklanternsecurity/bbot-server
```

Or install directly from the OCI registry:

```bash
helm install bbot oci://registry-1.docker.io/blacklanternsecurity/bbot-server
```

### Configuration

Key values can be overridden with `--set` or a custom values file:

```bash
helm install bbot blacklanternsecurity/bbot-server \
--set ingress.enabled=true \
--set ingress.hosts[0].host=bbot.example.com \
--set ingress.hosts[0].paths[0].path=/ \
--set ingress.hosts[0].paths[0].pathType=Prefix
```

Or with a values file:

```yaml
# custom-values.yaml
ingress:
enabled: true
className: nginx
annotations:
cert-manager.io/cluster-issuer: letsencrypt
hosts:
- host: bbot.example.com
paths:
- path: /
pathType: Prefix
tls:
- secretName: bbot-tls
hosts:
- bbot.example.com

secrets:
# provide your own API key, or leave empty to auto-generate
apiKey: ""
```

```bash
helm install bbot blacklanternsecurity/bbot-server -f custom-values.yaml
```

### Retrieving the API Key

If you didn't provide an API key, one is auto-generated. Retrieve it with:

```bash
kubectl get secret bbot-api-key -o jsonpath='{.data.api-key}' | base64 -d
```

### Upgrading

```bash
helm repo update
helm upgrade bbot blacklanternsecurity/bbot-server
```

## Interacting with BBOT Server Remotely (Multiplayer)

By default, BBOT Server listens on localhost. Use `--listen` to expose it to the network:
Expand Down
Loading