- Go 61%
- JavaScript 26%
- CSS 6.7%
- HTML 4.6%
- Dockerfile 1.7%
|
|
||
|---|---|---|
| .forgejo/workflows | ||
| internal | ||
| web | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| main.go | ||
| README.md | ||
| renovate.json | ||
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.
- Optional read-only rsync daemon that mirrors the same directory, so it
can be synced with a standard
rsyncclient.
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. |
PAGE_DESCRIPTION |
(empty) | Optional subtitle shown under the page title. Hidden when empty. |
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. |
RSYNC_ENABLED |
false |
If true, also starts a read-only rsync daemon mirroring ROOT_DIR. |
RSYNC_ADDR |
:873 |
Address the rsync daemon listens on. Port 873 is the rsync default but requires binding as root (or CAP_NET_BIND_SERVICE) on Linux; use a high port otherwise. |
RSYNC_MODULE_NAME |
share |
The module name clients use, e.g. rsync://host/<RSYNC_MODULE_NAME>. |
RSYNC_PUBLIC_HOST |
(empty) | Overrides the hostname shown in the on-page rsync instructions. Defaults to the request's Host header. |
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
Mirroring with rsync
Set RSYNC_ENABLED=true to start a read-only rsync daemon alongside the
HTTP server. It serves the same ROOT_DIR as a single module (named by
RSYNC_MODULE_NAME) and only allows pulling files out — clients cannot
push, modify, or delete anything on the server.
RSYNC_ENABLED=true RSYNC_ADDR=:8873 RSYNC_MODULE_NAME=share go run .
Then, from any machine with rsync installed:
rsync -av rsync://host:8873/share/ ./local-mirror/
When enabled, the web UI also shows this command directly on the page (via
GET /api/stats), using the hostname from the incoming request's Host
header by default. If the rsync daemon is reachable under a different DNS
name than the web UI (e.g. a separate internal hostname or load balancer),
override it with RSYNC_PUBLIC_HOST:
RSYNC_ENABLED=true RSYNC_ADDR=:8873 RSYNC_PUBLIC_HOST=files.example.com go run .
With Docker, publish the rsync port too:
docker run -p 8080:8080 -p 8873:8873 \
-v /path/to/files:/data \
-e RSYNC_ENABLED=true \
-e RSYNC_ADDR=:8873 \
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.