🚀 Multi-Server Development Environment v1.2.0

A containerized development environment for testing and developing applications across multiple server technologies simultaneously. This project provides hot-reloading development servers for HTML/CSS/JS, Python (Flask and FastAPI), and Node.js Express, all running in Docker containers with a unified dashboard for monitoring.

✨ Features

Beautiful UI: Dark and light theme with modern component library
Cross-platform compatibility: All services run in Docker containers
Hot reloading: All servers automatically reload when code changes
Unified dashboard: Monitor all services in one interface
Standardized API endpoints: Common patterns across all server implementations
CORS enabled: All services configured for cross-origin requests
Health checks: Docker health checks implemented for all services
API testing tools: Built-in interface for testing endpoints
Theme switching: Toggle between dark and light themes with persistent preferences
Loading screen: Smooth page load experience with animated loading indicator
Responsive Layout: Mobile-friendly design with adaptive components
Git workflow: Complete Git configuration with hooks, templates, and CI/CD

🏗️ Architecture

The development environment consists of the following components:

Service	Technology	Port	Purpose
Dashboard	HTML/JS/CSS (Live Server)	8081	Monitor all services
Flask API	Python Flask	8082	Python web framework
FastAPI	Python FastAPI	8083	Modern Python API framework
Node.js API	Express.js	8084	JavaScript API server
Reverse Proxy	Nginx (optional)	8080	Unified routing

🚀 Quick Start

Prerequisites

Docker and Docker Compose installed
Git for version control

Installation

Clone the repository:

git clone https://github.com/pkeffect/dev-server.git
cd dev-environment

Create an environment file:
```
cp .env.example .env
```

Set up Git hooks (optional but recommended):

chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

Build and start all services:
```
docker-compose up --build
```
Access the dashboard:
- Open your browser and navigate to http://localhost:8081

🔌 Service Access Points

Click to expand all service endpoints

Dashboard: http://localhost:8081
Live Server API: http://localhost:8081/api.html
Flask API: http://localhost:8082
FastAPI: http://localhost:8083
- OpenAPI Documentation: http://localhost:8083/docs
Node.js Express: http://localhost:8084
Unified Access (if using Nginx): http://localhost:8080
- Flask API: http://localhost:8080/flask
- FastAPI: http://localhost:8080/fastapi
- Node.js: http://localhost:8080/node

🎨 UI Features

Dark & Light Themes: Toggle between themes with persistent preferences that respect system settings
Modern UI Components: Buttons, cards, alerts, badges, dropdowns, forms and more
Loading Screen: Smooth page load experience with animated loading indicator
Responsive Layout: Mobile-friendly design with adaptive components
Interactive Dashboard: Real-time service status monitoring
API Testing Panel: Built-in interface for testing endpoints across all services
GitHub-Inspired Design: Familiar, clean interface for developers

💻 Development Workflow

Project Structure

dev-environment/
├── app_flask.py              # Flask application
├── app_fastapi.py            # FastAPI application
├── app_node.js               # Node.js Express application
├── Dockerfile                # Multi-stage Docker build
├── compose.yml               # Docker Compose configuration
├── requirements.txt          # Python dependencies
├── package.json              # Node.js dependencies
├── .env.example              # Environment variables template
├── .gitignore                # Git ignore patterns
├── .gitattributes            # Git attributes configuration
├── .githooks/                # Git hooks
│   └── pre-commit            # Pre-commit hook
├── .github/                  # GitHub configuration
│   ├── workflows/            # GitHub Actions
│   │   └── ci.yml            # CI workflow
│   ├── ISSUE_TEMPLATE/       # Issue templates
│   └── PULL_REQUEST_TEMPLATE.md # PR template
├── healthcheck.sh            # Health check script
├── nginx/                    # Nginx configuration
│   └── nginx.conf            # Reverse proxy setup
├── src/                      # Front-end source files
│   ├── index.html            # Dashboard HTML
│   ├── css/                  # CSS styles
│   │   ├── main.css          # Main shared styles
│   │   ├── components.css    # UI component styles
│   │   ├── dark-theme.css    # Dark theme styles
│   │   ├── light-theme.css   # Light theme styles
│   │   ├── dashboard.css     # Dashboard-specific styles
│   │   ├── utilities.css     # Utility classes
│   │   └── loading.css       # Loading screen styles
│   ├── js/                   # JavaScript files
│   │   ├── main.js           # Main functionality
│   │   ├── theme.js          # Theme switching logic
│   │   ├── dashboard.js      # Dashboard functionality
│   │   └── loading.js        # Loading screen manager
│   ├── img/                  # Images directory
│   │   └── icons/            # SVG icons
│   └── api.html              # Live Server API endpoint
└── tests/                    # Testing utilities
    ├── api_tests.sh          # Bash test suite
    ├── test_suite.py         # Python test suite
    ├── test_flask.py         # Flask-specific tests
    ├── conftest.py           # pytest configuration
    └── node-tests.js         # Node.js tests

Making Changes

All code is mounted as volumes in the Docker containers, so changes to files will automatically trigger server reloads:

HTML/CSS/JS: Edit files in the src/ directory
Python (Flask/FastAPI): Edit app_flask.py or app_fastapi.py
Node.js: Edit app_node.js

Adding Dependencies

Python: Add to requirements.txt and restart the containers
Node.js: Add to package.json and restart the containers

Environment Variables

Configure your development environment by editing the .env file:

View example environment configuration

# Server Configurations
FLASK_ENV=development
FLASK_DEBUG=1
NODE_ENV=development

# API Keys (for demonstration)
DEMO_API_KEY=your_api_key_here

# Database Configuration (if needed)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=devdb
DB_USER=devuser
DB_PASSWORD=devpassword

📝 API Documentation

All services implement the following standard endpoints:

View API endpoints

Root Endpoint

GET /

Returns basic service information:

{
  "message": "Hello from [Service]!",
  "service": "[Service Name]",
  "environment": "development",
  "version": "1.0.0"
}

Health Check

GET /health

Returns service health status:

{
  "status": "healthy",
  "service": "[Service Name]"
}

Echo Endpoint

POST /echo

Body:

{
  "message": "Hello world",
  "data": { "key": "value" }
}

Response:

{
  "echo": {
    "message": "Hello world",
    "data": { "key": "value" }
  },
  "service": "[Service Name]"
}

FastAPI Documentation

FastAPI automatically generates interactive API documentation:

Swagger UI: http://localhost:8083/docs
ReDoc: http://localhost:8083/redoc

🧪 Testing

Dashboard Testing

The dashboard provides an interactive way to test all services:

Open http://localhost:8081
Use the "Test" buttons for individual services
Click "Test All Services" for a comprehensive check
Use the API Testing panel for custom endpoint tests

View command line testing options

Command Line Testing

Bash Script

# Run the bash test suite
./tests/api_tests.sh

Python Script

# Run the Python test suite
python tests/test_suite.py

Node.js Tests

# Run the Node.js tests
npm test

Flask and FastAPI Tests

# Run the Flask tests
docker-compose exec flask-dev pytest tests/test_flask.py

# Run the FastAPI tests 
docker-compose exec fastapi-dev pytest

🐳 Managing Containers

View Docker management commands

Starting Services

# Start all services
docker-compose up

# Start in detached mode
docker-compose up -d

# Start a specific service
docker-compose up flask-dev

Stopping Services

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

Viewing Logs

# View logs from all services
docker-compose logs

# Follow logs
docker-compose logs -f

# View logs for a specific service
docker-compose logs flask-dev

🚄 Performance Optimization

This environment includes several performance optimizations:

FastAPI Resource Management

The FastAPI service includes CPU and memory limits to prevent resource contention:

deploy:
  resources:
    limits:
      cpus: '0.5'
      memory: 256M
    reservations:
      cpus: '0.25'
      memory: 128M

Optimized Asset Loading

The dashboard implements:

Progressive loading of resources
Efficient theme switching without page reloads
Preloading of critical JavaScript
Optimized SVG icons

Development vs. Production Settings

For development, use the included hot-reload settings. For production, consider:

Disabling hot-reload flags (--reload)
Adjusting worker counts based on available CPU cores
Setting appropriate logging levels

🔒 Security Considerations

Container Security

The Dockerfile includes options for running containers as non-root users:

# --- Create non-root user and group ---
RUN addgroup -S dev-group && adduser -S dev-user -G dev-group

# --- Change ownership of the application directory ---
RUN chown -R dev-user:dev-group /app

# --- Switch to the non-root user ---
USER dev-user

Uncomment these sections for improved container security in production.

Environment Variables

Ensure sensitive information is stored in .env files and never committed to version control. The .gitignore file excludes .env files by default:

# Environment variables
.env
.env.*
!.env.example

🔄 Git Configuration

This project includes a complete Git workflow setup:

.gitignore: Comprehensive ignore patterns for development files
.gitattributes: Line ending normalization and file handling
GitHub Workflows: Automated CI/CD with GitHub Actions
Issue & PR Templates: Standardized formats for contributions
Git Hooks: Pre-commit validation for code quality

View Git setup instructions

Setting Up Git Hooks

# Make git hooks executable
chmod +x .githooks/pre-commit

# Set hooks path
git config core.hooksPath .githooks

Branch Strategy

Follow the GitHub Flow branching strategy:

Create a feature branch from main
Make changes and commit
Push branch and create a Pull Request
After review, merge to main

For detailed instructions, see GIT_SETUP.md.

🔧 Troubleshooting

View common issues and solutions

Common Issues

Service Not Starting

Check the Docker logs:

docker-compose logs [service-name]

Hot Reloading Not Working

Ensure the correct volume mounts are in place and file permissions are correct:

docker-compose down
docker-compose up --build

Cannot Access Service

Verify the port mappings in compose.yml and check if the container is running:

docker-compose ps

Theme Switching Not Working

Check browser console for errors in theme.js. Local storage might be disabled or full.

Live Server Test Failing

Ensure the src/api.html file exists for the Live Server API endpoint. If the test still fails, check the browser console for CORS errors.

CI Pipeline Failing

Check the GitHub Actions logs for detailed error information. Common issues include:

Missing test files or incorrect paths
Import errors in Python tests
Timing issues with service startup

Health Checks

Each service has built-in health checks that Docker uses to monitor container status:

# View container health
docker ps

👥 Contributing

We welcome contributions to this project! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please read our Code of Conduct and Security Policy before contributing.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

_{Built with ❤️ for developers}

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🚀 Multi-Server Development Environment v1.2.0

📋 Table of Contents

✨ Features

🏗️ Architecture

🚀 Quick Start

Prerequisites

Installation

🔌 Service Access Points

🎨 UI Features

💻 Development Workflow

Project Structure

Making Changes

Adding Dependencies

Environment Variables

📝 API Documentation

Root Endpoint

Health Check

Echo Endpoint

FastAPI Documentation

🧪 Testing

Dashboard Testing

Command Line Testing

Bash Script

Python Script

Node.js Tests

Flask and FastAPI Tests

🐳 Managing Containers

Starting Services

Stopping Services

Viewing Logs

🚄 Performance Optimization

FastAPI Resource Management

Optimized Asset Loading

Development vs. Production Settings

🔒 Security Considerations

Container Security

Environment Variables

🔄 Git Configuration

Setting Up Git Hooks

Branch Strategy

🔧 Troubleshooting

Common Issues

Service Not Starting

Hot Reloading Not Working

Cannot Access Service

Theme Switching Not Working

Live Server Test Failing

CI Pipeline Failing

Health Checks

👥 Contributing

📜 License