No description
- Go 61%
- JavaScript 26%
- CSS 6.7%
- HTML 4.6%
- Dockerfile 1.7%
| internal | ||
| web | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| main.go | ||
| README.md | ||
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 toROOT_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/indexbuilds a full recursive snapshot ofROOT_DIRwithfilepath.WalkDir, stores it behind anatomic.Pointer, and swaps in a fresh snapshot on each rebuild — reads never block on rebuilds.internal/serverwires the Gin routes, the vhost guard, and the streaming file handler.web/embeds thefrontend/directory (index.html,assets/) viago:embedso the compiled binary is fully self-contained.