Development Quickstart Guide¶

This guide helps you get started with development in our Docker infrastructure quickly. Follow these steps to set up your development environment and begin working with our services.

Table of Contents¶

Prerequisites
Initial Setup
Git Repository Setup
Creating Your First Service
Development Workflow
Common Tasks
Next Steps

Prerequisites¶

Before starting, ensure you have: - SSH access to the Docker host - Basic knowledge of Docker and Docker Compose - Git installed on your local machine - A code editor (VS Code, Vim, etc.)

Initial Setup¶

1. Connect to the Server¶

# Via SSH (if you have port forwarding)
ssh [email protected]

# Via Tailscale (recommended for development)
ssh [email protected]

2. Verify Docker Installation¶

# Check Docker is running
docker --version
docker compose version

# Verify you have permissions
docker ps

3. Explore the Infrastructure¶

# Navigate to the Docker data directory
cd /srv/dockerdata

# List existing services
ls -la

# Check running services
docker ps

# View service logs
docker compose -f traefik/docker-compose.yml logs -f

Git Repository Setup¶

Our infrastructure uses a dual-repository setup with Gitea (primary) and optional GitHub (secondary) remotes.

1. Clone the Infrastructure Repository¶

# Clone from Gitea (primary repository)
git clone [email protected]:admin/test-sync-workflow.git
cd test-sync-workflow

# Or clone existing infrastructure
cd /srv/dockerdata
git remote -v  # Check current remotes

2. Configure Dual Remotes¶

Run our automated setup script:

/srv/dockerdata/_scripts/setup-git-remotes.sh

This script will: - Configure Gitea as the primary remote - Optionally add GitHub as a secondary remote - Create useful Git aliases - Set up secure push hooks

3. Manual Remote Configuration (Alternative)¶

If you prefer manual setup:

# Add Gitea as primary
git remote add origin [email protected]:admin/infrastructure.git

# Add GitHub as secondary (optional)
git remote add github [email protected]:yourorg/infrastructure.git

# Configure push to both remotes
git config --add remote.origin.pushurl [email protected]:admin/infrastructure.git
git config --add remote.origin.pushurl [email protected]:yourorg/infrastructure.git

4. Set Up Git Aliases¶

# Push to all remotes
git config --global alias.push-all '!git push origin && git push github 2>/dev/null || true'

# Sync from GitHub to Gitea
git config --global alias.sync-github '!git fetch github && git merge github/main && git push origin'

# Sync from Gitea to GitHub
git config --global alias.sync-gitea '!git fetch origin && git merge origin/main && git push github'

Creating Your First Service¶

Option 1: Using StackWiz (Recommended)¶

StackWiz is our automated service creation tool:

# Create a simple web service
stackwiz myapp

# Create a Pocketbase application
stackwiz --pocketbase myproject

# Create with automatic DNS
stackwiz --create-dns myservice

Follow the interactive prompts to: 1. Choose service type (generic or Pocketbase) 2. Enter domain name (e.g., myapp.rbnk.uk) 3. Specify container image and port 4. Configure environment variables

Option 2: Manual Service Creation¶

# Use the template script
cd /srv/dockerdata
./_templates/mkstack.sh myservice

# Edit the generated files
cd myservice
vim docker-compose.yml
vim .env

# Start the service
docker compose up -d

Development Workflow¶

1. Feature Branch Workflow¶

# Create a feature branch
git checkout -b feature/add-monitoring-service

# Make your changes
cd /srv/dockerdata
stackwiz grafana

# Test the service
cd grafana
docker compose up -d
docker compose logs -f

# Commit changes
git add grafana/
git commit -m "feat(monitoring): add Grafana service

- Configure Grafana with Traefik integration
- Set up persistent storage for dashboards
- Add basic authentication"

# Push to Gitea (primary)
git push -u origin feature/add-monitoring-service

2. Security Best Practices¶

Before committing:

# Check for sensitive data
git diff --staged | grep -i "password\|secret\|token\|key"

# Ensure .env files are in .gitignore
cat .gitignore | grep "\.env"

# Use .env.example files
cp myservice/.env myservice/.env.example
# Edit .env.example to remove sensitive values
vim myservice/.env.example

3. Testing Changes¶

# Local testing
docker compose -f myservice/docker-compose.yml up
curl http://localhost:8080

# Test with Traefik integration
docker compose -f myservice/docker-compose.yml up -d
curl https://myservice.rbnk.uk

# Check Traefik routing
curl http://localhost:8080/api/http/routers | jq

4. Merging and Deployment¶

# Push to Gitea for review
git push origin feature/add-monitoring-service

# After approval, merge to main
git checkout main
git merge feature/add-monitoring-service
git push origin main

# Optionally sync to GitHub
git push github main

Common Tasks¶

Updating a Service¶

# Pull latest changes
cd /srv/dockerdata/myservice
docker compose pull

# Restart with new image
docker compose up -d

# Check logs
docker compose logs -f

Adding Environment Variables¶

# Edit .env file
vim myservice/.env

# Add variables
API_KEY=your-secret-key
DATABASE_URL=postgresql://user:pass@db:5432/app

# Restart to apply
docker compose restart

Debugging Issues¶

# Check service status
docker compose ps

# View detailed logs
docker compose logs -f --tail=100

# Execute commands in container
docker compose exec myservice /bin/sh

# Inspect container
docker inspect myservice_container_name

Database Operations¶

# Access PostgreSQL (Supabase)
docker exec -it supa-db psql -U postgres

# Create backup
/srv/dockerdata/_scripts/supabase-backup.sh

# Access service-specific database
docker compose -f myservice/docker-compose.yml exec db psql -U user

Working with Gitea¶

Access Gitea Web Interface¶

URL: https://gitea.rbnk.uk
Login with your credentials
Create repositories, manage access, review code

Clone a New Project¶

# List available projects
curl https://gitea.rbnk.uk/api/v1/repos/search

# Clone a project
git clone [email protected]:username/project.git

Push to Multiple Remotes¶

# Push to all configured remotes
git push-all

# Or push individually
git push origin main
git push github main

Next Steps¶

1. Explore Documentation¶

Architecture overview: /srv/dockerdata/docs/architecture/
Service guides: /srv/dockerdata/docs/services/
Security practices: /srv/dockerdata/docs/security/

2. Learn Advanced Features¶

StackWiz Guide - Advanced service creation
Adding Services - Manual service configuration
Troubleshooting - Common issues and solutions

3. Set Up Development Tools¶

# Install development utilities
sudo apt-get update
sudo apt-get install -y jq httpie curl vim

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

4. Join the Development Workflow¶

Check existing issues in Gitea
Create feature branches for new work
Test thoroughly before pushing
Create merge requests for review
Keep documentation updated

Quick Command Reference¶

Task	Command
Create new service	`stackwiz myservice`
Start service	`docker compose up -d`
View logs	`docker compose logs -f`
Push to all remotes	`git push-all`
Access database	`docker exec -it supa-db psql -U postgres`
Check service health	`docker ps`
Update service	`docker compose pull && docker compose up -d`
Create DNS record	`cloudflare-dns-create.sh subdomain`

Getting Help¶

Internal documentation: /srv/dockerdata/docs/
Gitea issues: https://gitea.rbnk.uk/admin/infrastructure/issues
Service logs: docker compose logs -f service-name
System status: docker ps and docker stats

Remember: - Always test changes locally first - Never commit sensitive data - Use feature branches for development - Document your changes - Keep services updated and secure