Skip to content

Development Guide

This guide covers development workflows, best practices, and procedures for working with the rbnk.uk infrastructure.

Overview

The development documentation provides guidelines for adding new services, modifying existing configurations, and following best practices for infrastructure as code.

Development Workflow

1. Quickstart Guide

Get up and running quickly with: - Environment setup - Basic commands - Common tasks

2. Adding Services

Step-by-step guide for deploying new services: - Using StackWiz for quick deployment - Manual service configuration - Traefik integration - DNS setup

3. StackWiz Guide

Using the stack creation wizard: - Creating generic service stacks - Deploying Pocketbase applications - Automatic DNS configuration - Template customization

4. Git Workflow

Version control best practices: - Branching strategy - Commit guidelines - Secret management - Sync procedures

5. Local Development

Setting up local development environment: - Docker Desktop configuration - Local testing procedures - Debugging techniques

6. API Integration

Integrating with infrastructure APIs: - Supabase REST API - LiteLLM endpoints - n8n webhooks - Monitoring APIs

Development Tools

StackWiz

Quick stack creation tool: 

# Create generic service
stackwiz myservice

# Create Pocketbase app
stackwiz --pocketbase myapp

# With DNS creation
stackwiz --create-dns myservice

Docker Commands

Essential Docker operations: 

# Build and start services
docker compose up -d --build

# View logs
docker compose logs -f SERVICE_NAME

# Execute commands in container
docker exec -it CONTAINER_NAME /bin/sh

# Clean up
docker system prune -a

Git Operations

Version control commands: 

# Standard workflow
git add .
git commit -m "feat: add new service"
git push origin main

# Check for secrets
git diff --staged | grep -iE 'password|secret|token|key'

Best Practices

1. Service Configuration

  • Use environment variables for configuration
  • Store secrets in .env files (never commit)
  • Follow existing naming conventions
  • Document all configuration options

2. Network Architecture

  • Add services to appropriate Docker networks
  • Use internal DNS names for service communication
  • Configure Traefik labels for external access
  • Document port mappings

3. Security

  • Never hardcode credentials
  • Use strong, unique passwords
  • Enable authentication on all services
  • Regular security updates

4. Documentation

  • Update documentation with changes
  • Include configuration examples
  • Document troubleshooting steps
  • Keep README files current

5. Testing

  • Test locally when possible
  • Verify Traefik routing
  • Check DNS resolution
  • Monitor logs during deployment

Common Tasks

Adding a New Service

  1. Create stack: stackwiz servicename
  2. Configure service: Edit docker-compose.yml
  3. Add Traefik labels: 
    labels:
  - "traefik.enable=true"
  - "traefik.http.routers.servicename.rule=Host(`servicename.rbnk.uk`)"
  - "traefik.http.routers.servicename.tls.certresolver=cf"
  4. Create DNS record: ./_scripts/cloudflare-dns-create.sh servicename
  5. Start service: docker compose up -d
  6. Verify: Access at https://servicename.rbnk.uk

Updating Services

  1. Pull latest images: 

    docker compose pull
docker compose up -d

  2. Force recreate: 

    docker compose up -d --force-recreate

  3. With build: 

    docker compose up -d --build

Debugging Issues

  1. Check logs: docker compose logs -f
  2. Inspect container: docker inspect CONTAINER_NAME
  3. Network debugging: docker exec CONTAINER ping TARGET
  4. Traefik routing: Check Traefik dashboard
  5. DNS issues: Verify with dig servicename.rbnk.uk

Integration Examples

Supabase Integration

const { createClient } = require('@supabase/supabase-js');
const supabase = createClient(
  'https://supabase.rbnk.uk',
  process.env.ANON_KEY
);

n8n Webhook

curl -X POST https://n8n.rbnk.uk/webhook/WEBHOOK_ID \
  -H "Content-Type: application/json" \
  -d '{"event": "deployment", "service": "myapp"}'

Notification Integration

# Send notification via helper script
notify "Deployment Complete" "Service deployed successfully" normal system

# Direct Apprise API
curl -X POST https://apprise.rbnk.uk/notify/apprise \
  -F "title=Deployment" \
  -F "body=Service deployed" \
  -F "tag=development"

Troubleshooting

For common issues and solutions, see: - Troubleshooting Guide - Service-specific Issues - Docker Issues - Networking Problems

Resources

  • Templates: /srv/dockerdata/_templates/
  • Scripts: /srv/dockerdata/_scripts/
  • Documentation: /srv/dockerdata/docs/
  • Examples: Check existing service configurations