Skip to content

Latest commit

Β 

History

History
367 lines (266 loc) Β· 8.99 KB

README.md

File metadata and controls

367 lines (266 loc) Β· 8.99 KB

Docker Simple Panel

A modern, lightweight dashboard for managing Docker containers

Docker Simple Panel Go Svelte License

Quick Start Documentation


🌟 Overview

Docker Simple Panel is a sleek web application that provides a REST API and intuitive UI for managing Docker containers. Built with a Go backend and Svelte frontend, it offers authentication, real-time monitoring, and comprehensive container operations.

✨ Features

Feature Description
πŸ” Authentication Single-user JWT-based authentication with configurable session timeout
πŸ“¦ Container Management List, start, stop, restart containers with health status
πŸ“Š Real-time Logs WebSocket-powered log streaming with 30-minute history
πŸ’Ύ Volume Management View and manage Docker volumes with container associations
πŸ“± PWA Support Install on iPhone, Android, and desktop with offline capabilities
βš™οΈ Configuration YAML-based config with web UI updates
🐳 Docker Integration Direct Docker daemon access via socket

πŸ“‹ Requirements

  • Go 1.21+ (for building from source)
  • Docker daemon running
  • Node.js 18+ (for frontend development)

πŸš€ Quick Start with Docker

The easiest way to run Docker Simple Panel is using the pre-built Docker image:

# Pull the latest image
docker pull ghcr.io/dev-zapi/docker-simple-panel:latest

# Run the container
docker run -d \
  --name docker-simple-panel \
  -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./data:/app/data \
  ghcr.io/dev-zapi/docker-simple-panel:latest

# Verify it's running
curl http://localhost:8080/api/health

πŸ”‘ Default Credentials

Username Password
admin changeme

⚠️ Important: Change the default password immediately! Edit /app/data/config.yaml inside the container.

πŸ”’ Security Best Practices

  • πŸ›‘οΈ Mount Docker socket only when necessary
  • πŸ”‘ Change default password on first use
  • πŸ” Set a strong JWT_SECRET in production

πŸ’» Development

Dev Container (Recommended)

Use VS Code Dev Containers for a consistent development environment:

# Prerequisites: VS Code + Docker Desktop + Dev Containers extension
# Open project β†’ Press F1 β†’ "Dev Containers: Reopen in Container"

See .devcontainer/README.md for details.

Building from Source

# Clone repository
git clone https://github.com/dev-zapi/docker-simple-panel.git
cd docker-simple-panel

# Install dependencies
go mod download

# Build
go build -o docker-simple-panel .

Building Docker Image Locally

docker build -t docker-simple-panel:local .

docker run -d \
  --name docker-simple-panel \
  -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./data:/app/data \
  docker-simple-panel:local

βš™οΈ Configuration

Configuration is managed via YAML file (default: ./config.yaml or CONFIG_PATH env var).

Example Configuration

# Authentication
username: admin
password: changeme  # Auto-hashed with bcrypt

# Server settings
server:
  port: "8080"
  jwt_secret: "your-secret-key-change-in-production"
  session_max_timeout: 24  # hours

# Docker settings
docker:
  socket: "/var/run/docker.sock"
  volume_explorer_image: "ghcr.io/dev-zapi/docker-simple-panel:latest"

# Logging
logging:
  level: "info"  # error, warn, info, debug

# Static files (optional)
static_path: ""

Environment Variables

Variable Default Description
CONFIG_PATH ./config.yaml Path to YAML config file
STATIC_PATH (empty) Frontend static files directory
SERVER_PORT 8080 Server port
JWT_SECRET (required in prod) JWT signing secret
DOCKER_SOCKET /var/run/docker.sock Docker socket path
DISABLE_REGISTRATION false Disable user registration
LOG_LEVEL info Logging level
VOLUME_EXPLORER_IMAGE (see above) Volume explorer Docker image

πŸ”‘ Password Management

  • First startup: Creates default config with admin/changeme
  • Password auto-hashed with bcrypt on save
  • Change via web UI Settings page or edit config file
  • Critical: Always change default password in production!

▢️ Running

# Default (uses ./config.yaml)
./docker-simple-panel

# Custom config
CONFIG_PATH=/path/to/config.yaml ./docker-simple-panel

# With static files
STATIC_PATH=/path/to/frontend/dist ./docker-simple-panel

πŸ“‘ API Endpoints

Full OpenAPI v3 specification available at GET /api/openapi.json. Import into Swagger UI for interactive documentation!

Public Endpoints

Health Check

GET /api/health

Login

POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "changeme"
}

Response:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "username": "admin"
  }
}

Protected Endpoints (Require JWT)

Include header: Authorization: Bearer <token>

List Containers

GET /api/containers

Returns all containers with status and health info.

Container Operations

Method Endpoint Description
GET /api/containers/{id} Get container details
POST /api/containers/{id}/start Start container
POST /api/containers/{id}/stop Stop container
POST /api/containers/{id}/restart Restart container
GET /api/containers/{id}/logs/stream WebSocket log stream

WebSocket Log Streaming

GET /api/containers/{id}/logs/stream

Real-time log streaming with:

  • βœ… JWT authentication (header or query param)
  • βœ… 30-minute history
  • βœ… Timestamps included
  • βœ… stdout + stderr support

Example:

const ws = new WebSocket(
  `ws://localhost:8080/api/containers/${containerId}/logs/stream`,
  [],
  { headers: { Authorization: `Bearer ${token}` } }
);

ws.onmessage = (event) => {
  console.log(event.data);
};

Docker Health

GET /api/docker/health

Volume Management

Method Endpoint Description
GET /api/volumes List volumes with containers
DELETE /api/volumes/{name} Delete volume

Configuration

Method Endpoint Description
GET /api/config Get current config
PUT /api/config Update config

Update Example:

PUT /api/config
Content-Type: application/json

{
  "docker_socket": "/custom/path/docker.sock",
  "log_level": "debug",
  "session_max_timeout": 48
}

πŸ”’ Security

  • πŸ” Bcrypt password hashing
  • ⏰ JWT tokens expire (default: 24h)
  • 🚫 Single-user authentication only
  • ⚠️ Docker socket access grants full control
  • πŸ”‘ Must change default password & JWT secret in production

πŸ§ͺ Development

Run Tests

go test ./...

Project Structure

.
β”œβ”€β”€ main.go              # Entry point
β”œβ”€β”€ config/              # YAML config management
β”œβ”€β”€ database/            # SQLite operations
β”œβ”€β”€ docker/              # Docker client wrapper
β”œβ”€β”€ handlers/            # HTTP handlers
β”œβ”€β”€ middleware/          # Auth, CORS, logging
β”œβ”€β”€ models/              # Data models
β”œβ”€β”€ webui/               # Svelte frontend
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ components/
β”‚   β”‚   β”œβ”€β”€ pages/
β”‚   β”‚   β”œβ”€β”€ services/
β”‚   β”‚   └── stores/
β”‚   └── package.json
└── openapi.json         # API specification

🐳 Docker Image Building

GitHub Actions (Automated)

  1. Go to Actions tab
  2. Select "Build and Push Docker Image"
  3. Click "Run workflow"
  4. Optionally specify custom tag
  5. Builds multi-platform (amd64, arm64)

See .github/workflows/README.md for details.


πŸ“„ License

MIT License - See LICENSE file for details.


Built with ❀️ using Go and Svelte

Report Issue β€’ Request Feature β€’ Discussions