No description
  • Go 61%
  • JavaScript 26%
  • CSS 6.7%
  • HTML 4.6%
  • Dockerfile 1.7%
Find a file
2026-09-16 23:29:27 +02:00
internal initial commit 2026-09-16 23:26:08 +02:00
web initial commit 2026-09-16 23:26:08 +02:00
.dockerignore add docker container 2026-09-16 23:29:27 +02:00
.env.example initial commit 2026-09-16 23:26:08 +02:00
.gitignore add docker container 2026-09-16 23:29:27 +02:00
Dockerfile add docker container 2026-09-16 23:29:27 +02:00
go.mod initial commit 2026-09-16 23:26:08 +02:00
go.sum initial commit 2026-09-16 23:26:08 +02:00
main.go initial commit 2026-09-16 23:26:08 +02:00
README.md initial commit 2026-09-16 23:26:08 +02:00

pretty-directorylist

A fast, self-hosted directory listing server. It serves a folder from disk as a single-page app with search across all subdirectories, sortable columns, and direct file downloads — backed by a Gin API and a cached, in-memory file index so it stays fast with thousands of files.

Features

  • Gin-based HTTP server, frontend and API served from a single Go binary.
  • Frontend is a single-page app: folder navigation and search happen client-side against a JSON API, with real, bookmarkable URLs (browser back/forward works).
  • Files are streamed straight from disk via http.ServeContent (supports HTTP Range requests) — never buffered fully into memory, so large files don't spike RAM usage.
  • The file listing is cached in memory and rebuilt on a configurable interval, plus opportunistically when filesystem changes are detected. Directory listings and recursive search are served from that cache, not from disk, so they stay fast even with a few thousand files.
  • Frontend (HTML/CSS/JS) is embedded into the binary at build time via go:embed — the Docker image only needs the compiled binary.
  • Optional virtual-host restriction so the listing only answers on a specific hostname.

Configuration

All configuration is via environment variables (a .env file is loaded automatically if present). See .env.example.

Variable Default Description
LISTEN_ADDR :8080 Address the HTTP server binds to.
ROOT_DIR ./data Directory on disk that is listed and served.
PAGE_TITLE File List Title shown in the page header and browser tab.
FILES_VHOST (empty) If set, only requests whose Host header matches this value are served; others get a 404.
CACHE_REFRESH_INTERVAL_SECONDS 30 How often the in-memory file index is fully rebuilt from disk.
MAX_SEARCH_RESULTS 500 Maximum number of results returned by a single search request.
GIN_MODE release Gin mode: release, debug, or test.
LOG_FOLDER (empty) If set, logs are also written to <LOG_FOLDER>/application.log (rotated).
LOG_LEVEL INFO DEBUG, INFO, WARN, or ERROR.

Running locally

go run . 

By default this serves ./data on http://localhost:8080.

Running with Docker

docker build -t pretty-directorylist .
docker run -p 8080:8080 -v /path/to/files:/data pretty-directorylist

Or with environment overrides:

docker run -p 8080:8080 \
  -v /path/to/files:/data \
  -e PAGE_TITLE="My Files" \
  -e FILES_VHOST=files.example.com \
  pretty-directorylist

API

The frontend talks to the backend exclusively through this JSON API:

  • GET /api/dir?path=<relative/path> — list the direct children of a directory (path relative to ROOT_DIR, empty for the root).
  • GET /api/search?q=<term>&limit=<n> — search file/folder names recursively across the whole tree (served from the cached index).
  • GET /api/stats — total file count, total size, page title, and when the index was last rebuilt.
  • GET /files/<relative/path> — streams the file's contents from disk (supports Range requests, conditional GET, and does not buffer the file in memory).

Any other path is served the SPA shell, which reads the current URL and drives navigation through the API above.

Architecture notes

  • internal/index builds a full recursive snapshot of ROOT_DIR with filepath.WalkDir, stores it behind an atomic.Pointer, and swaps in a fresh snapshot on each rebuild — reads never block on rebuilds.
  • internal/server wires the Gin routes, the vhost guard, and the streaming file handler.
  • web/ embeds the frontend/ directory (index.html, assets/) via go:embed so the compiled binary is fully self-contained.