Skip to content

Commit a8164b1

Browse files
the78molethe78mole
committed
Add production-ready Docker configurations and examples for WebUIFlasher
1 parent f0d5300 commit a8164b1

11 files changed

+383
-4
lines changed

‎DOCKER_PRODUCTION.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# WebUIFlasher Production Deployment
2+
3+
This directory contains production-ready Docker Compose configurations that use the pre-built WebUIFlasher images from GitHub Container Registry.
4+
5+
## 🚀 Quick Start
6+
7+
### Standard Production Setup
8+
```bash
9+
# Download the compose file
10+
curl -O https://raw.githubusercontent.com/the78mole/WebUIFlasher/main/docker-compose.production.yml
11+
12+
# Start WebUIFlasher
13+
docker compose -f docker-compose.production.yml up -d
14+
15+
# Access at http://localhost:8000
16+
```
17+
18+
## 📋 Available Configurations
19+
20+
### 1. **docker-compose.production.yml** - Standard Setup
21+
- Uses `ghcr.io/the78mole/webuiflasher:latest`
22+
- Full USB device access (`/dev` mounted)
23+
- Privileged mode for maximum compatibility
24+
- Health checks included
25+
- **Recommended for:** Development and home use
26+
27+
### 2. **docker-compose.production-secure.yml** - Secure Setup
28+
- Specific TTY device mapping only
29+
- No privileged mode
30+
- Minimal permissions
31+
- **Recommended for:** Production servers
32+
33+
### 3. **docker-compose.production-pinned.yml** - Version Pinned
34+
- Uses specific version tag (e.g., `v1.0.0`)
35+
- Guarantees reproducible deployments
36+
- **Recommended for:** Production environments requiring stability
37+
38+
## 🔧 Customization
39+
40+
### Environment Variables
41+
```yaml
42+
environment:
43+
- TZ=Europe/Berlin # Timezone
44+
- WEBUI_TITLE=My Flasher # Custom title
45+
- WEBUI_THEME=dark # UI theme
46+
```
47+
48+
### Volume Mapping
49+
```yaml
50+
volumes:
51+
- ./my-firmware:/app/firmware # Custom firmware directory
52+
- ./my-sources:/app/sources # Custom source configurations
53+
```
54+
55+
### Port Mapping
56+
```yaml
57+
ports:
58+
- "9000:8000" # Run on port 9000 instead of 8000
59+
```
60+
61+
## 🛡️ Security Considerations
62+
63+
### Secure Setup (Recommended for Production)
64+
```bash
65+
# Use the secure compose file
66+
docker compose -f docker-compose.production-secure.yml up -d
67+
68+
# Adjust TTY devices as needed
69+
# Edit the file to match your hardware setup
70+
```
71+
72+
### Device Permissions
73+
```bash
74+
# Add your user to dialout group (host system)
75+
sudo usermod -a -G dialout $USER
76+
77+
# Or run container as root (already configured)
78+
```
79+
80+
## 📦 Available Image Tags
81+
82+
| Tag | Description | Use Case |
83+
|-----|-------------|----------|
84+
| `latest` | Latest stable release | Development, testing |
85+
| `v1.2.3` | Specific version | Production (recommended) |
86+
| `1.2` | Major.minor version | Compatible updates |
87+
| `1` | Major version | Long-term compatibility |
88+
89+
## 🔍 Health Checks
90+
91+
All configurations include health checks:
92+
```bash
93+
# Check container health
94+
docker compose ps
95+
96+
# View health check logs
97+
docker compose logs webuiflasher
98+
```
99+
100+
## 🚨 Troubleshooting
101+
102+
### USB Device Not Found
103+
```bash
104+
# List available devices
105+
ls -la /dev/tty*
106+
107+
# Update compose file with correct device paths
108+
# Restart container
109+
docker compose restart
110+
```
111+
112+
### Permission Issues
113+
```bash
114+
# Run with root privileges (already configured)
115+
# Or adjust host system permissions
116+
sudo chmod 666 /dev/ttyUSB0
117+
```
118+
119+
### Container Updates
120+
```bash
121+
# Pull latest image
122+
docker compose pull
123+
124+
# Restart with new image
125+
docker compose up -d
126+
```
127+
128+
## 📚 Examples
129+
130+
See the `examples/` directory for:
131+
- **Dockerfile.extended** - How to extend the base image
132+
- **docker-compose.extended.yml** - Custom build example
133+
- **custom-sources.yaml** - Custom firmware source configuration
134+
135+
## 🔗 Links
136+
137+
- **Docker Images:** https://github.com/the78mole/WebUIFlasher/pkgs/container/webuiflasher
138+
- **Source Code:** https://github.com/the78mole/WebUIFlasher
139+
- **Documentation:** https://github.com/the78mole/WebUIFlasher/blob/main/README.md

‎Makefile

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
11
# WebUIFlasher Docker Operations
2-
.PHONY: help build up down logs clean secure dev restart release
2+
.PHONY: help build up down logs clean secure dev restart release prod prod-secure prod-pinned
33

44
help: ## Show this help message
5-
@echo "WebUIFlasher Docker Commands:"
5+
@echo "🐳 WebUIFlasher Docker Commands"
6+
@echo "==============================="
67
@echo ""
7-
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-15s\033[0m %s\n", $$1, $$2}'
8+
@echo "Development (build from source):"
9+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | grep -E '^(build|up|down|secure|logs|shell|clean):' | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-15s\033[0m %s\n", $$1, $$2}'
10+
@echo ""
11+
@echo "Production (pre-built images):"
12+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | grep -E '^(prod|prod-secure|prod-pinned):' | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-15s\033[0m %s\n", $$1, $$2}'
13+
@echo ""
14+
@echo "Utilities:"
15+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | grep -v -E '^(build|up|down|secure|logs|shell|clean|prod|prod-secure|prod-pinned):' | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-15s\033[0m %s\n", $$1, $$2}'
816

917
build: ## Build the Docker image
1018
docker compose build
@@ -30,7 +38,27 @@ dev: ## Start development service (alias for up)
3038
$(MAKE) up
3139

3240
clean: ## Remove containers and images
33-
docker compose down --rmi all --volumes --remove-orphans
41+
docker compose down --rmi all --volumes
42+
@echo "🧹 Cleanup completed"
43+
44+
# Production commands (using pre-built images)
45+
prod: ## Start production setup (latest image)
46+
docker compose -f docker-compose.production.yml up -d
47+
@echo "🚀 WebUIFlasher (production) started at http://localhost:8000"
48+
49+
prod-secure: ## Start secure production setup (selected devices)
50+
docker compose -f docker-compose.production-secure.yml up -d
51+
@echo "🔒 WebUIFlasher (secure production) started at http://localhost:8000"
52+
53+
prod-pinned: ## Start with pinned version
54+
docker compose -f docker-compose.production-pinned.yml up -d
55+
@echo "📌 WebUIFlasher (pinned version) started at http://localhost:8000"
56+
57+
prod-down: ## Stop production services
58+
docker compose -f docker-compose.production.yml down
59+
docker compose -f docker-compose.production-secure.yml down
60+
docker compose -f docker-compose.production-pinned.yml down
61+
@echo "⏹️ Production services stopped" --remove-orphans
3462

3563
shell: ## Open shell in running container
3664
docker compose exec webflasher /bin/bash

‎docker-compose.production-pinned.yml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
version: '3.8'
2+
3+
services:
4+
webuiflasher:
5+
image: ghcr.io/the78mole/webuiflasher:v1.0.0
6+
container_name: webuiflasher-pinned
7+
ports:
8+
- "8000:8000"
9+
volumes:
10+
- ./firmware:/app/firmware
11+
- ./sources:/app/sources
12+
- /dev:/dev
13+
privileged: true
14+
restart: unless-stopped
15+
environment:
16+
- TZ=Europe/Berlin
17+
healthcheck:
18+
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
19+
interval: 30s
20+
timeout: 10s
21+
retries: 3
22+
start_period: 40s

‎docker-compose.production-secure.yml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
version: '3.8'
2+
3+
services:
4+
webuiflasher:
5+
image: ghcr.io/the78mole/webuiflasher:latest
6+
container_name: webuiflasher-secure
7+
ports:
8+
- "8000:8000"
9+
volumes:
10+
- ./firmware:/app/firmware
11+
- ./sources:/app/sources
12+
# Specific TTY devices only (adjust as needed)
13+
- /dev/ttyUSB0:/dev/ttyUSB0
14+
- /dev/ttyUSB1:/dev/ttyUSB1
15+
- /dev/ttyACM0:/dev/ttyACM0
16+
restart: unless-stopped
17+
environment:
18+
- TZ=Europe/Berlin
19+
healthcheck:
20+
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
21+
interval: 30s
22+
timeout: 10s
23+
retries: 3
24+
start_period: 40s
25+
user: root
26+
group_add:
27+
- dialout

‎docker-compose.production.yml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
version: '3.8'
2+
3+
services:
4+
webuiflasher:
5+
image: ghcr.io/the78mole/webuiflasher:latest
6+
container_name: webuiflasher
7+
ports:
8+
- "8000:8000"
9+
volumes:
10+
- ./firmware:/app/firmware
11+
- ./sources:/app/sources
12+
- /dev:/dev
13+
privileged: true
14+
restart: unless-stopped
15+
environment:
16+
- TZ=Europe/Berlin
17+
healthcheck:
18+
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
19+
interval: 30s
20+
timeout: 10s
21+
retries: 3
22+
start_period: 40s

‎examples/Dockerfile.extended

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# WebUIFlasher Extended Example
2+
# This Dockerfile shows how to extend the WebUIFlasher base image
3+
# with custom firmware, configurations, or additional tools
4+
5+
FROM ghcr.io/the78mole/webuiflasher:latest
6+
7+
# Install additional tools (optional)
8+
RUN apt-get update && apt-get install -y \
9+
git \
10+
curl \
11+
wget \
12+
unzip \
13+
&& rm -rf /var/lib/apt/lists/*
14+
15+
# Copy custom firmware files
16+
COPY examples/custom-firmware/ /app/firmware/custom/
17+
18+
# Copy custom source configurations
19+
COPY examples/custom-sources.yaml /app/sources.yaml
20+
21+
# Copy custom web assets (optional)
22+
COPY examples/custom-site/ /app/scripts/site/custom/
23+
24+
# Set custom environment variables
25+
ENV CUSTOM_FIRMWARE_PATH=/app/firmware/custom
26+
ENV WEBUI_TITLE="Custom ESP Flasher"
27+
ENV WEBUI_THEME="dark"
28+
29+
# Create custom entrypoint script
30+
COPY examples/custom-entrypoint.sh /usr/local/bin/
31+
RUN chmod +x /usr/local/bin/custom-entrypoint.sh
32+
33+
# Use custom entrypoint that calls the original
34+
ENTRYPOINT ["/usr/local/bin/custom-entrypoint.sh"]
35+
CMD ["python", "/app/scripts/webflasher.py"]

‎examples/custom-entrypoint.sh

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#!/bin/bash
2+
# Custom entrypoint script for extended WebUIFlasher
3+
4+
echo "🚀 Starting Custom WebUIFlasher"
5+
echo "================================"
6+
7+
# Check if custom firmware directory exists
8+
if [ -d "$CUSTOM_FIRMWARE_PATH" ]; then
9+
echo "✅ Custom firmware found at $CUSTOM_FIRMWARE_PATH"
10+
ls -la "$CUSTOM_FIRMWARE_PATH"
11+
else
12+
echo "ℹ️ No custom firmware directory found"
13+
fi
14+
15+
# Apply custom configurations
16+
if [ -f "/app/sources.yaml" ]; then
17+
echo "✅ Using custom sources configuration"
18+
fi
19+
20+
# Set custom web UI title if provided
21+
if [ -n "$WEBUI_TITLE" ]; then
22+
echo "🎨 Setting custom title: $WEBUI_TITLE"
23+
fi
24+
25+
echo "🌐 WebUIFlasher will be available at: http://localhost:8000"
26+
echo ""
27+
28+
# Execute the original command
29+
exec "$@"

‎examples/custom-firmware/README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Example Custom Firmware
2+
# This would typically be your actual firmware files
3+
4+
esp32-custom-v1.0.bin
5+
esp32s3-sensor-v2.1.bin
6+
esp8266-iot-v1.5.bin

‎examples/custom-site/custom.css

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/* Custom site styling */
2+
body {
3+
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
4+
}
5+
6+
.custom-header {
7+
color: #ffffff;
8+
text-shadow: 2px 2px 4px rgba(0,0,0,0.3);
9+
}

‎examples/custom-sources.yaml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Example custom sources configuration
2+
# This file shows how to add custom firmware sources
3+
4+
github_sources:
5+
- name: "custom-esp32-firmware"
6+
repo: "your-username/esp32-custom-firmware"
7+
path: "build/firmware.bin"
8+
description: "Custom ESP32 firmware with additional features"
9+
targets:
10+
- esp32
11+
- esp32s2
12+
- esp32s3
13+
14+
- name: "iot-sensor-firmware"
15+
repo: "your-org/iot-sensor-project"
16+
path: "dist/"
17+
description: "IoT sensor firmware collection"
18+
targets:
19+
- esp32
20+
- esp8266
21+
22+
local_sources:
23+
- name: "development-builds"
24+
path: "/app/firmware/custom/dev-builds"
25+
description: "Local development firmware builds"
26+
27+
- name: "production-releases"
28+
path: "/app/firmware/custom/production"
29+
description: "Tested production firmware releases"
30+
31+
platformio_sources:
32+
- name: "custom-pio-project"
33+
path: "/app/firmware/custom/pio-projects/sensor-node"
34+
description: "PlatformIO sensor node project"
35+
board: "esp32dev"
36+
framework: "arduino"

0 commit comments

Comments
 (0)