Initial Commit
This commit is contained in:
Aodhan Collins
234
README.md
Normal file
234
README.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user