How d-a-s-h-o/droplets works
Project Type and Purpose
• Type: CLI-driven Docker orchestration tool for spinning up PHP web-hosting stacks (with Tor support) plus generic Ubuntu containers.
• Purpose: Automate building and running Docker containers (web + ubuntu) via a simple CLI (app.py), serve PHP sites over clearnet and Tor, and expose an optional API/QR/TOTP layer.
File Structure
• Top-level:
– app.py + shell scripts (ddd CLI entrypoint)
– api/ (PHP & Python API endpoints)
– webui/ (PHP-based UI helper)
– qr/ & totp.sh (QR code and TOTP support libraries)
– docker/ubuntu & docker/web (Dockerfiles + config dumps)
• Patterns:
– CLI invokes Docker builds and runs
– docker/web image bundles Nginx, PHP, Tor, site files under /var/www/html/.files
– docker/ubuntu provides a generic sandbox container
Key Insights from the README
• The CLI (app.py) named “ddd” builds and runs images with three simple commands.
• Two prebuilt images: ghcr.io/d-a-s-h-o/droplets/web and …/ubuntu.
• After “ddd -n <name>,” your container is live on clearnet and as a Tor hidden service.
Main Components
a. ddd CLI (app.py + support scripts)
b. Docker Engine (daemon on host)
c. Docker Images:
• droplets/web
• droplets/ubuntu
d. Running Containers:
• Web Container:
– Nginx (reverse proxy)
– Tor daemon (hidden-service)
– PHP interpreter + .files folder (index.php, config.php, UI assets)
• Ubuntu Container: generic environment for custom services
e. Volumes & Config Mappings:
– Host ↔ Container mounts for /etc/nginx, torrc, site files
f. API Layer (api/api.php, api/api.py, config.py)
g. QR & TOTP Modules (qr/*, totp.sh)
h. External Networks:
– Clearnet (HTTP/S on host port → Nginx)
– Tor Network (TCP 9050 → Tor daemon → hidden service)
Relationships and Data Flows
• The ddd CLI issues Docker build/run commands to Docker Engine.
• Docker Engine spins up containers from the two images.
• Web Container:
– Nginx listens on forwarded host ports.
– Nginx proxies PHP requests to the PHP-FPM interpreter reading .files.
– Tor daemon registers a hidden service pointing at the local Nginx port.
• Ubuntu Container: used for arbitrary workloads (NodeJS, Python, etc.) under the same orchestration flow.
• API Layer: inside the web container (or separate) exposes control endpoints for container management.
• QR/TOTP scripts: either invoked by web UI (webui/app.php) or CLI to generate codes.
Architectural Patterns & Principles
• Separation of concerns: CLI vs. orchestrator vs. runtime images.
• Immutable infrastructure: containers built from Dockerfiles with versioned configs.
• Plug-in flexibility: generic Ubuntu container alongside specialized web container.
• Single responsibility: one container = one service (web, tor, php under web image).