djb 0.2.23

Django + Bun deployment platform

djb - Django + Bun Platform

djb is a deployment platform for Django applications with frontend tooling (Bun). It provides utilities for secrets management, deployment, and development workflows.

djb structure:

djb/
├── src/djb/
│   ├── __init__.py      # Package initialization + logging exports
│   ├── config.py        # User configuration (name, email)
│   ├── project.py       # Project utilities
│   ├── cli/             # Command-line interface
│   │   ├── djb.py       # Main CLI entry point
│   │   ├── init.py      # Environment initialization
│   │   ├── secrets.py   # Secrets management commands
│   │   ├── deploy.py    # Heroku deployment
│   │   ├── publish.py   # Package publishing
│   │   ├── superuser.py # Django Superuser syncing
│   │   ├── editable.py  # Editable djb management
│   │   ├── logging.py   # CLI logging utilities
│   │   └── utils.py     # Shared utilities
│   ├── core/            # Core utilities
│   │   └── exceptions.py
│   ├── management/      # Django management commands
│   │   └── commands/
│   │       └── sync_superuser.py
│   └── secrets/         # Encrypted secrets management
│       ├── __init__.py  # Public API exports
│       ├── core.py      # Encryption/decryption
│       └── init.py      # Secrets initialization
└── pyproject.toml

Installation

If you don't have uv installed yet:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install djb as a dependency in your project:

# Add djb to your project
uv add djb

# Verify djb is available
djb --help

For local development of djb alongside your project:

# Clone djb into your project as a subdirectory
git clone https://github.com/kajicom/djb

# Install in editable mode
djb editable-djb

Features

Initialization

One-command setup for development environment:

# Full initialization
djb init

# Initialize with options
djb init --skip-brew          # Skip Homebrew dependencies
djb init --skip-frontend      # Skip frontend setup
djb init --skip-secrets       # Skip secrets initialization
djb init --project-root /path # Specify project directory

This installs:

• System dependencies via Homebrew (age, SOPS, PostgreSQL, GDAL, Bun)
• Python dependencies (uv sync)
• Frontend dependencies (bun install)
• Encrypted secrets management

Secrets Management

Age + SOPS encrypted secrets for secure configuration:

# Initialize secrets (creates .age/keys.txt in project root)
djb secrets init

# Edit environment secrets
djb secrets edit dev
djb secrets edit heroku_prod

# View secrets
djb secrets view dev
djb secrets list

# Backup private key to clipboard (store in password manager!)
djb secrets export-key | pbcopy

Each project has its own encryption key stored in .age/keys.txt. Make sure to back up your key securely. If lost, you won't be able to decrypt existing secrets. Copy your private Age key to the clipboard:

djb secrets export-key | pbcopy

Documentation: See docs/SECRETS_GUIDE.md

Deployment

Heroku deployment with frontend builds, secrets sync, and migrations:

# Deploy to Heroku (uses DJB_APP_NAME from Django settings)
djb deploy heroku

# Or specify app explicitly
djb deploy heroku --app myapp

# Deploy with options
djb deploy heroku --local-build --skip-secrets

# Configure Heroku app (buildpacks, postgres, git remote)
djb deploy heroku setup

# Revert to previous deployment
djb deploy heroku revert

# Revert to specific commit
djb deploy heroku revert abc1234

App Name Auto-Detection: If DJB_APP_NAME is set in your Django settings, deployment commands will use it automatically. You can still override with --app.

# In settings.py
DJB_APP_NAME = "myapp"

Usage

Command Line

Run djb commands directly:

djb <command>

Python API

Import djb modules directly in Python code:

from djb.secrets import load_secrets, SecretsManager
from pathlib import Path

# Load secrets for current environment
secrets = load_secrets()
api_key = secrets['api_keys']['stripe']

# Encrypt/decrypt programmatically (requires SOPS and age)
manager = SecretsManager(secrets_dir=Path('secrets'))
secrets = manager.load_secrets('dev')

Development

Adding New Commands

1. Create a new subcommand module in djb/cli/
2. Define your Click command group
3. Register it in djb/cli/djb.py:

from djb.cli.mycommand import mycommand

djb_cli.add_command(mycommand)

Adding New Features

1. Implement the feature in an appropriate module under djb/
2. Export public API in djb/__init__.py if needed
3. Add CLI commands if applicable
4. Update documentation

Architecture Decisions

Why Integrated Development

djb can be embedded within projects as a subdirectory and installed in editable mode. This allows:

1. Rapid iteration on both the platform and application
2. Project-specific customization
3. Simplified dependency management during development

For production deployments, djb is installed from PyPI.

Future Plans

Planned djb features:

• Environment initialization - djb init
• Deployment commands (Heroku) - djb deploy heroku, djb deploy heroku revert
• Heroku setup - djb deploy heroku setup (buildpacks, postgres, git remote)
• App name auto-detection from Django settings (DJB_APP_NAME)
• Git hooks setup via djb init (pre-commit hook for editable djb check)
• Multi-recipient secret encryption
• Secret rotation automation
• Deployment commands (Kubernetes)
• Development server management
• Database migration utilities
• Environment variable syncing

References

• Secrets Guide - User guide for secrets management
• Age Encryption - Encryption specification
• Click - CLI framework

License

djb is licensed under the MIT License.

Mascot Attribution

The djb mascot (dj_bun) was created for this project and is distributed under CC BY-SA 4.0.

---

/dj_bun: playin' dev and deploy since 1984 🎶