Mikochi

Mikochi is a lightweight, self‑hosted web file manager designed for remote servers and NAS devices. From a developer’s perspective, it functions as a thin HTTP gateway that exposes the local filesystem through a RESTful API while rendering a modern, single‑page interface. The backend is written in Go and leverages the Gin web framework to deliver high throughput, low latency endpoints for CRUD operations on files and directories. The frontend is a small Preact application that consumes these endpoints, providing features such as fuzzy search, bulk downloads (archived as .tar.gz), and media streaming to VLC or MPV via custom URI schemes.

• Backend: Go 1.22 + Gin. The application is compiled into a single binary, making it trivial to ship across platforms. It uses the standard os and io/fs packages for filesystem access, while JWT tokens (configurable via JWT_SECRET) guard the API. The code is organized into modular packages (api, auth, storage, stream) that expose clear interfaces, facilitating unit testing and future extensions.
• Frontend: Preact (a lightweight React alternative) bundled with a minimal build pipeline powered by Vite. The static assets are served from the ./static directory, which can be overridden via the FRONTEND_FILES environment variable. This separation allows developers to replace or extend the UI without touching the Go code.
• Containerization: A single Docker image (zer0tonin/mikochi) contains both the backend binary and the pre‑built static files. The Dockerfile follows best practices (multi‑stage build, scratch base image) to keep the final image under 30 MB. Kubernetes users can deploy via a Helm chart that exposes configurable values (username, password, persistence settings) and supports sidecar injection for TLS termination or auth proxies.
• Persistence: The application does not rely on a dedicated database; instead it reads directly from the filesystem. This design eliminates data migration headaches and makes it ideal for stateless or stateful pods that mount a host volume (e.g., /data).

• File Operations: GET /files, POST /upload, PUT /rename, DELETE /delete. All paths are relative to the configured DATA_DIR.
• Directory Management: Create (POST /mkdir), list, and archive directories (GET /download?path=).
• Streaming: GET /stream?file= returns a MIME type suitable for VLC/MPV, enabling instant playback without full download.
• Search: A fuzzy search endpoint (GET /search?q=) leverages Go’s strings.Contains with a simple scoring algorithm, returning results as JSON for the frontend to display.
• Authentication: JWT‑based auth with configurable USERNAME/PASSWORD. The /login endpoint issues a token that the frontend stores in memory; the token is required for all subsequent file operations.
• Webhooks & Extensibility: While not exposed by default, the API design permits adding hooks (e.g., on file upload) by wrapping the handler functions. Developers can also expose custom endpoints by adding new routes in api/routes.go.

• Self‑Hosting: Requires a Linux host with Docker or a container runtime. The DATA_DIR must be bind‑mounted into the container; otherwise, the app will read from its own image filesystem (read‑only).
• Scalability: Since Mikochi serves files directly from the host, scaling horizontally involves adding replicas behind a load balancer. Each replica must share the same underlying storage (e.g., NFS, Ceph) to maintain consistency.
• TLS & Reverse Proxy: The container can optionally load a TLS certificate via CERT_CA/CERT_KEY. For production, it’s common to terminate SSL at a reverse proxy (Traefik, Nginx) and forward plain HTTP to the container.
• Resource Footprint: The Go binary consumes ~10 MiB of RAM under load, and the Preact bundle is ~200 KiB. CPU usage stays below 5% even when streaming large media files, making it suitable for embedded devices.

• Plugin System: No formal plugin architecture exists, but the modular Go code allows developers to fork and extend functionality. For example, adding SFTP support or integrating with external authentication providers (OAuth2) can be achieved by replacing the auth package.
• Custom Frontend: By editing the Preact source or swapping out the FRONTEND_FILES directory, teams can tailor the UI to corporate branding or integrate with internal dashboards.
• Webhooks: The API can be wrapped in a sidecar that listens for events (e.g., after upload) and forwards them to external services like Slack or a CI pipeline.
• Metrics: Future versions could expose Prometheus metrics; the current code structure already separates request handling, making instrumentation straightforward.

• Configuration: All settings are exposed via environment variables, simplifying CI/CD pipelines and infrastructure as code. The defaults are sensible for local testing (HOST=0.0.0.0:80, DATA_DIR=/data).
• Documentation: The