No description
  • Go 61%
  • JavaScript 26%
  • CSS 6.7%
  • HTML 4.6%
  • Dockerfile 1.7%
Find a file
2026-09-18 15:56:45 +02:00
internal implement head requests 2026-09-18 15:56:45 +02:00
web add rsync instructions to page 2026-09-17 00:10:58 +02:00
.dockerignore add docker container 2026-09-16 23:29:27 +02:00
.env.example add rsync instructions to page 2026-09-17 00:10:58 +02:00
.gitignore add docker container 2026-09-16 23:29:27 +02:00
.gitlab-ci.yml add ci pipeline for docker 2026-09-16 23:30:11 +02:00
Dockerfile add docker container 2026-09-16 23:29:27 +02:00
go.mod add optional rsync server 2026-09-16 23:45:18 +02:00
go.sum add optional rsync server 2026-09-16 23:45:18 +02:00
main.go add optional rsync server 2026-09-16 23:45:18 +02:00
README.md add rsync instructions to page 2026-09-17 00:10:58 +02:00
renovate.json add renovate config 2026-09-16 23:31:30 +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.
  • Optional read-only rsync daemon that mirrors the same directory, so it can be synced with a standard rsync client.

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 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.