How hallotschuess/very-simple-upload-server works
Summary (project type & purpose)
• This is a minimal single-binary HTTP upload server written in Go. It exposes GET, PUT and DELETE over HTTP, uses an on-disk directory as its storage root, and is distributed as Docker images (standard and alpine). The runtime is configured via environment variables (tokens, root dir, base path, logging etc.). The codebase is intentionally tiny: main.go is the entrypoint and build/ contains Dockerfiles.
• Server as a lightweight containerized HTTP service that accepts client requests (browser/cli/other services), authorizes them (token via query or header), performs file operations (temp write → digest check → atomic rename for PUT, read for GET, recursive delete for DELETE), and persists data to a mounted host volume. Also show optional external responsibilities typically used in production (reverse proxy / TLS termination, load balancer, monitoring / logging agents).
Main components
• External clients
• curl / browser / other HTTP clients
• Network ingress / edge (optional, depending on deployment)
• Reverse proxy (nginx/traefik) or LB for TLS, host port mapping (Docker -p)
• Docker container / Process
• Go HTTP server (main binary) — label main.go as entrypoint
• HTTP router / URL base path handling
• Auth layer (token lookup: TOKEN_PUT / TOKEN_GET / TOKEN_DELETE; AUTH_HEADER + AUTH_HEADER_PREFIX; query param precedence)
• Upload handler (PUT):
• Accept formfile key "file" or raw body
• Create temporary file in same directory
• Digest verification (Digest header: md5, sha-256)
• Atomic replace (move/rename) to destination
• Download handler (GET): read file, stream to client
• Delete handler (DELETE): delete file or recursively remove directory, remove empty dirs
• CORS handling (always Access-Control-Allow-Origin: *)
• Logging subsystem (stdout; configurable format via LOG_FORMAT)
• Config via environment variables (LISTEN, ROOT_DIR, URL_BASE_PATH, DEBUG, FORCE_DIGEST, tokens, etc.)
• Persistent storage
• Mounted volume or host directory (Docker -v /uploads)
• Filesystem semantics (temp files in same dir; atomic rename)
• Build / Image artifacts
• build/Dockerfile(s) → image tags (latest, alpine, version)
• Optional external systems (if used in production)
• Volume provider (host disk, network storage)
• Monitoring / log aggregator (Fluentd / Elasticsearch / Prometheus exporters)
• Secrets manager (if tokens are placed securely instead of env)
• Backup / snapshot system
Important architectural patterns & design traits
• Single-process, single-binary service (no internal microservices)
• Filesystem-backed storage (no external DB)
• Token-based per-method authorization (stateless auth using environment-provided tokens)
• Atomic file operations: write to temp file then rename (lower risk of partial writes)
• Config-by-env (12-factor friendly), outputs logs to stdout (suitable for containerized log ingestion)
• Small surface area makes it suitable to be placed behind edge components for TLS and auth hardening.
• Go runtime / main.go (entry point)
• Docker images and Dockerfiles (build/Dockerfile and build/alpine.Dockerfile)
• Environment variables mapping (list the important ones: TOKEN_*, ROOT_DIR, URL_BASE_PATH, LISTEN, AUTH_HEADER, AUTH_HEADER_PREFIX, FORCE_DIGEST)
• Persistent volume mount (name example: my_volume:/uploads)
• HTTP (port 80) exposed by container
• Digest header support: md5 & sha-256
• C4 suggestion: Level 1 (system context): show clients, the upload server, storage, and optional ingress. Level 2 (container/component): show the internal components outlined above.
Detail to capture (do not omit)
• The temp file behavior and atomic rename (important for correctness)
• Which sources of token are supported and precedence (query param wins over header)
• That the server always sets Access-Control-Allow-Origin: *
• The environment variables that change behavior (base path, listen address, digest enforcement)
• Docker image variants and the approximate build path (source → build → image tag)
• Where logs go (stdout and format selection)
• That filename itself is irrelevant; only URL path determines storage location
• [ ] Show clients and ingress
• [ ] Show container with internal components (router, auth, handlers, digest checker)
• [ ] Show persistent volume with mount path
• [ ] Show env vars / config influencing behavior
• [ ] Show build artifacts (Dockerfile → image)
• [ ] Include a short sequence for PUT (temp-write → validate → rename) and mention cleanup on error
Minimal text to annotate directly from the repo
• Entrypoint: main.go
• Dockerfiles: build/Dockerfile, build/alpine.Dockerfile
• Config-by-env: TOKEN_GET/TOKEN_PUT/TOKEN_DELETE, ROOT_DIR, URL_BASE_PATH, AUTH_HEADER, AUTH_HEADER_PREFIX, LISTEN, FORCE_DIGEST
• Runtime behavior: Accepts formfile "file" or request body; uses URL path as storage key; overwrites existing files; supports Digest header; always returns CORS header.
Final advice