www/README.md

# RedUnits Control Panel

A beautiful, lightweight service management dashboard for monitoring Docker containers and system resources.

## Features

- Real-time service monitoring
- Docker container status and metrics
- System resource usage (CPU, Memory, Disk)
- Auto-refresh every 30 seconds
- Responsive dark theme design
- Minimal dependencies (FastAPI + Alpine.js)

## Project Structure

```
~/repo/redunits/www/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI application
│   └── docker_monitor.py    # Docker monitoring module
├── static/
│   ├── css/
│   │   └── style.css        # Styles
│   └── js/
│       └── app.js           # Alpine.js frontend logic
├── templates/
│   └── index.html           # Main dashboard template
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md
```

## Installation

### Prerequisites

- Docker and Docker Compose installed
- Python 3.11+ (for local development)

### Quick Start with Docker

1. Build and run the container:
```bash
cd ~/repo/redunits/www
docker-compose up -d --build
```

2. Access the dashboard:
```
http://localhost:8000
```

### Local Development

1. Create virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Run the application:
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## Deployment on VPS

### 1. Copy files to VPS:
```bash
rsync -avz ~/repo/redunits/www/ vps:/opt/redunits/www/
```

### 2. SSH into VPS and deploy:
```bash
ssh vps
cd /opt/redunits/www
sudo docker-compose up -d --build
```

### 3. Add to Caddy configuration:

Edit `/etc/caddy/Caddyfile`:
```
www.redunits.net, redunits.net {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8000
}
```

Reload Caddy:
```bash
sudo systemctl reload caddy
```

## API Endpoints

- `GET /` - Main dashboard page
- `GET /api/services` - Get all services with status
- `GET /api/system` - Get system statistics
- `GET /api/health` - Health check endpoint

## Configuration

### Adding New Services

Edit `app/main.py` and add to the `SERVICES` list:

```python
{
    "id": "service-id",
    "name": "Service Name",
    "icon": "🔧",
    "description": "Service description",
    "url": "https://service.domain.com",
    "container_name": "docker-container-name",
    "port": 8080
}
```

## Security Notes

- The application requires read-only access to Docker socket
- Run with non-root user inside container
- Use reverse proxy (Caddy) for HTTPS in production
- Consider adding authentication for production use

## Monitoring

The dashboard automatically monitors:

- Container status (running/stopped)
- Container CPU usage
- Container memory usage
- Container uptime
- System CPU usage
- System memory usage
- System disk usage
- Total and running container count

## Tech Stack

- **Backend**: FastAPI (Python)
- **Frontend**: Alpine.js + Vanilla CSS
- **Monitoring**: Docker SDK for Python + psutil
- **Container**: Docker with multi-stage build

## Development

### Running tests:
```bash
# TODO: Add tests
pytest
```

### Code formatting:
```bash
black app/
```

## License

MIT

## Author

RedUnits Team