ElectricSheep Development Guide

This guide covers the development workflow, repository structure, and deployment processes for all ElectricSheep services.

Development Environment Setup

Prerequisites

  • Docker and Docker Compose
  • Git with SSH keys configured
  • Node.js 18+ and Python 3.9+
  • Access to ElectricSheep development networks

Quick Start

# Clone the development environment
cd /opt/dev/electricsheep

# Available services for local development:
# - Admin & OSCAL Platform
# - AI Risk Assessment Platform
# - Security Agent Platform

Repository Structure

GitHub Repositories

Production Repositories

  • electricsheep-admin-oscal ✅ LIVE
    • Admin Dashboard and OSCAL Compliance Platform
    • Python Flask application
    • Production deployment: admin.electricsheep.farm, oscal.electricsheep.farm

Ready for Migration

  • AI Risk Assessment Platform - Ready to create repository
  • Security Agent Platform - Ready to create repository

Local Development Structure

/opt/dev/electricsheep/
├── admin-oscal-app/           # Admin & OSCAL platform
│   ├── Dockerfile
│   ├── docker-compose.dev.yml
│   ├── docker-compose.prod.yml
│   ├── app.py
│   ├── requirements.txt
│   └── ...
├── ai-risk-assessment/        # AI Risk platform
│   ├── src/
│   ├── frontend/
│   ├── docker-compose.dev.yml
│   └── ...
├── security-agent/           # Security monitoring
│   ├── src/
│   ├── frontend/
│   ├── docker-compose.dev.yml
│   └── ...
└── electricsheep-website/    # Main Hugo website

Development Workflow

1. Local Development

Admin & OSCAL Platform

cd /opt/dev/electricsheep/admin-oscal-app
docker-compose -f docker-compose.dev.yml up --build

# Access: http://localhost:5001
# Hot reload enabled for development

AI Risk Assessment Platform

cd /opt/dev/electricsheep/ai-risk-assessment
docker-compose -f docker-compose.dev.yml up --build

# Frontend: http://localhost:3000
# Backend: http://localhost:5000

Security Agent Platform

cd /opt/dev/electricsheep/security-agent
docker-compose -f docker-compose.dev.yml up --build

# Frontend: http://localhost:3001
# Backend: http://localhost:5002

2. Making Changes

  1. Edit source code - Changes auto-reload in development mode
  2. Test locally - Verify functionality before committing
  3. For dependency changes - Rebuild containers: 
    docker-compose -f docker-compose.dev.yml up --build
  4. Commit and push - Triggers automated CI/CD pipeline

3. Version Control

  • All repositories use Git with main branch as production
  • Feature branches for development
  • Pull request workflow for code review
  • Automated testing on all commits

Deployment Architecture

Production Infrastructure

ElectricSheep Production Environment
├── Traefik (Reverse Proxy + SSL)
│   ├── SSL Certificate Management (Let's Encrypt)
│   ├── Domain Routing
│   └── Load Balancing
├── Docker Compose Services
│   ├── static-website-prod (Hugo/Nginx)
│   ├── ai-risk-prod (Python/Flask + React)
│   ├── admin-app-prod (Python/Flask)
│   └── security-agent-prod (Coming Soon)
└── Persistent Storage
    ├── Database Volumes
    ├── Application Data
    └── Log Storage

Development Networks

# Create development network (if not exists)
docker network create electricsheep-dev

# All development services use this shared network
# for inter-service communication

CI/CD Pipeline

GitHub Actions Workflow

Each repository includes automated CI/CD:

1. Testing Phase

test:
  runs-on: ubuntu-latest
  steps:
    - Checkout code
    - Setup Python/Node.js
    - Install dependencies
    - Run syntax checks
    - Test Docker build

2. Deployment Phase

deploy:
  needs: test
  if: github.ref == 'refs/heads/main'
  steps:
    - SSH to production server
    - Pull latest changes
    - Stop current service
    - Build and deploy new version
    - Health check verification
    - Cleanup old images

3. Repository Secrets Required

  • HOST: Production server IP
  • USERNAME: SSH username (usually root)
  • SSH_KEY: Private SSH key for server access

Deployment Process

  1. Push to main branch - Triggers automated pipeline
  2. Automated testing - Syntax checks, Docker builds
  3. Production deployment - If tests pass
  4. Health verification - Ensures service is healthy
  5. Rollback capability - If deployment fails

Service Configuration

Environment Variables

Admin & OSCAL Platform

FLASK_ENV=production          # Environment mode
FLASK_DEBUG=0                # Debug mode (0 for production)
DATABASE_URL=sqlite:///...    # Database connection

AI Risk Assessment

NODE_ENV=production          # React environment
REACT_APP_API_URL=...        # Backend API URL
PYTHON_ENV=production        # Flask environment

Security Agent

NODE_ENV=production          # Frontend environment
API_BASE_URL=...            # Backend API endpoint
MONITORING_ENABLED=true      # Enable monitoring features

Database Management

SQLite (Admin & OSCAL)

  • Local SQLite databases for development
  • Production data in Docker volumes
  • Schema files for database initialization

PostgreSQL (AI Risk Assessment)

  • Development: Local Docker PostgreSQL
  • Production: Managed PostgreSQL instance
  • Migration scripts for schema updates

SSL and Security

Traefik Configuration

# Automatic SSL certificate management
- "traefik.http.routers.{service}.tls.certresolver=letsencrypt"
- "traefik.http.routers.{service}.entrypoints=websecure"

Security Headers

  • HTTPS enforcement
  • Security headers (HSTS, CSP, etc.)
  • CORS configuration for API endpoints

Development Best Practices

Code Quality

  • Linting: ESLint for JavaScript, Black/Flake8 for Python
  • Testing: Unit tests and integration tests
  • Documentation: Comprehensive code comments
  • Type Checking: TypeScript for frontend, mypy for Python

Docker Best Practices

  • Multi-stage builds for production images
  • Health checks for all services
  • Proper volume management for persistent data
  • Environment-specific configurations

Security Considerations

  • No secrets in source code
  • Environment variable management
  • Input validation and sanitization
  • SQL injection prevention
  • HTTPS enforcement

Monitoring and Logging

Health Checks

  • Built-in health endpoints for all services
  • Docker health check configurations
  • Automated monitoring and alerting

Logging

# View logs for specific service
docker logs {container-name}

# Follow logs in real-time
docker logs -f {container-name}

# Development logs with docker-compose
docker-compose -f docker-compose.dev.yml logs -f {service-name}

Performance Monitoring

  • Application performance metrics
  • Resource usage monitoring
  • Error tracking and alerting
  • Database performance monitoring

Troubleshooting

Common Development Issues

Port Conflicts

# Check which ports are in use
netstat -tulnp | grep :{port}

# Stop conflicting services
docker-compose down

Database Issues

# Reset development database
docker-compose down -v  # Removes volumes
docker-compose up --build

SSL Certificate Issues

# Check certificate status
docker logs traefik

# Force certificate renewal
docker restart traefik

Production Troubleshooting

Service Health Checks

# Check all services
docker ps

# Check specific service logs
docker logs {service-name}

# Restart unhealthy service
docker-compose -f docker-compose.prod.yml restart {service}

Performance Issues

# Check system resources
docker stats

# Monitor database performance
docker exec {db-container} psql -c "SELECT * FROM pg_stat_activity;"

Testing Strategies

Unit Testing

  • Python: pytest framework
  • JavaScript: Jest testing framework
  • Database: Test database with fixtures

Integration Testing

  • API endpoint testing
  • Database integration tests
  • Service-to-service communication tests

End-to-End Testing

  • Frontend automation testing
  • Complete user workflow testing
  • Cross-service integration testing

Performance Testing

  • Load testing with appropriate tools
  • Database performance testing
  • API response time monitoring

Future Development

Planned Features

  • Enhanced Monitoring: Advanced metrics and alerting
  • API Gateway: Centralized API management
  • Microservices: Further service decomposition
  • Kubernetes: Container orchestration migration

Scalability Considerations

  • Horizontal scaling capabilities
  • Database sharding strategies
  • CDN integration for static assets
  • Caching layer implementation

Getting Help

Documentation

  • Service-specific README files
  • API documentation in repository docs
  • Architecture diagrams and technical specifications

Support Channels

  • GitHub Issues for bug reports and feature requests
  • Development team contact for technical questions
  • Wiki documentation for detailed guides

Contributing

  • Fork repository and create feature branches
  • Follow coding standards and best practices
  • Submit pull requests with comprehensive descriptions
  • Include tests for new functionality

For specific technical questions or to report issues, please refer to the individual repository documentation or contact the development team.