234 lines
6.3 KiB
Markdown
234 lines
6.3 KiB
Markdown
# Docker Dashboard
|
|
|
|
A modern, responsive web dashboard for managing and monitoring Docker containers with SQLite database integration and manual customization capabilities.
|
|
|
|
## Features
|
|
|
|
- **Dynamic Container Tiles**: Automatically discovers and displays all Docker containers
|
|
- **SQLite Database**: Persistent storage for custom tile configurations
|
|
- **Manual Customization**: Edit display names, icons, colors, descriptions, and URLs
|
|
- **Real-time Monitoring**: Live status updates and system metrics
|
|
- **Responsive Design**: Works on desktop, tablet, and mobile devices
|
|
- **Portainer Integration**: Optional enhanced functionality with Portainer API
|
|
- **Container Management**: Start, stop, and restart containers directly from the dashboard
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
- Docker installed and running
|
|
- Python 3.7+
|
|
- Docker socket access (typically requires sudo)
|
|
|
|
### Installation
|
|
|
|
1. **Clone or download the project**
|
|
2. **Install dependencies**:
|
|
```bash
|
|
pip3 install -r requirements.txt
|
|
```
|
|
|
|
3. **Configure environment**:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your specific settings
|
|
```
|
|
|
|
4. **Run the setup script** (recommended):
|
|
```bash
|
|
chmod +x setup.sh
|
|
./setup.sh
|
|
```
|
|
|
|
5. **Or run manually**:
|
|
```bash
|
|
sudo python3 api.py
|
|
```
|
|
|
|
6. **Access the dashboard**:
|
|
Open your browser to `http://localhost:5000`
|
|
|
|
### Manual Setup
|
|
|
|
If you prefer to set up manually:
|
|
|
|
1. **Install Python dependencies**:
|
|
```bash
|
|
pip3 install flask flask-cors docker requests python-dotenv
|
|
```
|
|
|
|
2. **Initialize database**:
|
|
```bash
|
|
python3 -c "import database; db = database.DatabaseManager(); db.init_db()"
|
|
```
|
|
|
|
3. **Start the application**:
|
|
```bash
|
|
sudo python3 api.py
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `PORT` | Server port | 5000 |
|
|
| `HOST` | Server host | 0.0.0.0 |
|
|
| `DEBUG` | Debug mode | False |
|
|
| `REFRESH_INTERVAL` | Auto-refresh interval (seconds) | 30 |
|
|
| `PORTAINER_URL` | Portainer URL (optional) | - |
|
|
| `PORTAINER_USERNAME` | Portainer username | - |
|
|
| `PORTAINER_PASSWORD` | Portainer password | - |
|
|
|
|
### Portainer Integration (Optional)
|
|
|
|
To use Portainer for enhanced container management:
|
|
|
|
1. Set up Portainer on your Docker host
|
|
2. Configure the environment variables:
|
|
```bash
|
|
PORTAINER_URL=https://your-portainer-instance.com
|
|
PORTAINER_USERNAME=your-username
|
|
PORTAINER_PASSWORD=your-password
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Dashboard Overview
|
|
|
|
- **Server Information**: CPU, memory, and disk usage
|
|
- **Container Tiles**: Visual representation of all Docker containers
|
|
- **Live Status**: Real-time container status (running/stopped)
|
|
- **Uptime Display**: Container uptime information
|
|
- **Quick Actions**: Open, edit, or manage containers
|
|
|
|
### Customizing Tiles
|
|
|
|
1. **Click the "Edit" button** on any container tile
|
|
2. **Modify the fields**:
|
|
- **Display Name**: Custom name shown on the tile
|
|
- **Icon**: Font Awesome icon class (e.g., `fas fa-cube`)
|
|
- **Color**: Tailwind CSS color (e.g., `blue`, `green`, `red`)
|
|
- **Description**: Additional description text
|
|
- **URL**: Custom URL for the application
|
|
3. **Save changes** - updates are immediately reflected
|
|
|
|
### Syncing Containers
|
|
|
|
- **Automatic**: Containers sync every 30 seconds
|
|
- **Manual**: Click "Sync Apps" button to force refresh
|
|
- **New containers**: Automatically appear as new tiles
|
|
- **Removed containers**: Tiles are removed from display
|
|
|
|
## API Endpoints
|
|
|
|
### System Information
|
|
- `GET /api/system` - System metrics and uptime
|
|
|
|
### Containers
|
|
- `GET /api/containers` - List all Docker containers
|
|
- `GET /api/health/<container_name>` - Check container health
|
|
|
|
### Applications (Database)
|
|
- `GET /api/applications` - Get all applications from database
|
|
- `GET /api/applications/<container_id>` - Get specific application
|
|
- `PUT /api/applications/<container_id>` - Update application data
|
|
- `DELETE /api/applications/<container_id>` - Delete application
|
|
- `POST /api/applications/sync` - Sync with current containers
|
|
|
|
### Portainer (Optional)
|
|
- `GET /api/portainer/containers` - Get containers via Portainer
|
|
- `POST /api/portainer/container/<action>/<container_id>` - Manage containers
|
|
|
|
## Database Schema
|
|
|
|
The SQLite database (`dashboard.db`) contains the following table:
|
|
|
|
```sql
|
|
CREATE TABLE applications (
|
|
container_id TEXT PRIMARY KEY,
|
|
container_name TEXT NOT NULL,
|
|
display_name TEXT,
|
|
image TEXT,
|
|
status TEXT,
|
|
ports TEXT,
|
|
uptime TEXT,
|
|
icon TEXT DEFAULT 'fas fa-cube',
|
|
color TEXT DEFAULT 'gray',
|
|
description TEXT,
|
|
url TEXT,
|
|
custom_data TEXT
|
|
);
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
├── api.py # Main Flask API server
|
|
├── database.py # SQLite database manager
|
|
├── template.html # Frontend dashboard
|
|
├── portainer_integration.py # Portainer API integration
|
|
├── setup.sh # Setup and launch script
|
|
├── stop.sh # Stop script (generated)
|
|
├── .env # Environment variables (create from .env.example)
|
|
├── .env.example # Environment template
|
|
├── requirements.txt # Python dependencies
|
|
├── .gitignore # Git ignore rules
|
|
├── dashboard.db # SQLite database (created automatically)
|
|
└── logs/
|
|
└── dashboard.log # Application logs
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Docker Permission Issues
|
|
If you see "Permission denied" errors:
|
|
```bash
|
|
# Add your user to docker group
|
|
sudo usermod -aG docker $USER
|
|
# Log out and back in
|
|
```
|
|
|
|
### Port Issues
|
|
If port 5000 is already in use:
|
|
```bash
|
|
# Edit .env file and change PORT
|
|
PORT=5001
|
|
```
|
|
|
|
### Database Issues
|
|
To reset the database:
|
|
```bash
|
|
rm dashboard.db
|
|
python3 -c "import database; db = database.DatabaseManager(); db.init_db()"
|
|
```
|
|
|
|
### View Logs
|
|
```bash
|
|
tail -f logs/dashboard.log
|
|
```
|
|
|
|
## Development
|
|
|
|
### Adding New Features
|
|
1. **Backend**: Modify `api.py` for new endpoints
|
|
2. **Database**: Update `database.py` for schema changes
|
|
3. **Frontend**: Edit `template.html` for UI changes
|
|
|
|
### Contributing
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Test thoroughly
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
This project is open source and available under the [MIT License](LICENSE).
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
1. Check the troubleshooting section above
|
|
2. Review the logs in `logs/dashboard.log`
|
|
3. Open an issue on the project repository |