Veldoc

Minimal file browser for viewing a mounted directory in the browser. Designed for Docker: mount a folder, open the UI, read files and rendered Markdown.

Quick start

docker run -p 8080:8080 -v ./your-folder:/data ghcr.io/aredoff/veldoc

Open http://localhost:8080

Docker Compose

mkdir -p data
echo "# Hello" > data/readme.md
docker compose up --build

Configuration

Flag / Env	Default	Description
--root / VELDOC_ROOT	/data	Directory to serve
--addr / VELDOC_ADDR	:8080	Listen address
--auth / VELDOC_AUTH	none	none, basic, form, token
VELDOC_BASIC_USER		Basic auth username
VELDOC_BASIC_PASSWORD		Basic auth password
VELDOC_FORM_USER		Form auth username
VELDOC_FORM_PASSWORD		Form auth password
VELDOC_SESSION_SECRET		Form auth session secret
VELDOC_TOKEN		Bearer token
--poll-interval / VELDOC_POLL_INTERVAL	3s	UI poll interval
--max-preview-size / VELDOC_MAX_PREVIEW_SIZE	52428800	Max file size for preview in bytes (download is unlimited)

Excluding files (.docignore)

Place a .docignore file in the served root or any subdirectory. Syntax matches .gitignore: wildcards (*, ?, **), negation (!), directory patterns (trailing /), and comments (#).

Ignored paths are hidden from the file tree and cannot be read via the API. .docignore files themselves are always hidden.

Root example (data/.docignore):

# secrets
.env
private/

# build artifacts
*.log
dist/

# except this one
!important.log

Nested example (data/docs/.docignore):

drafts/
*.tmp

Patterns in a nested .docignore apply only to files under that directory, like Git.

Auth examples

Basic auth:

docker run -p 8080:8080 -v ./data:/data \
  -e VELDOC_AUTH=basic \
  -e VELDOC_BASIC_USER=admin \
  -e VELDOC_BASIC_PASSWORD=secret \
  veldoc

Form auth:

docker run -p 8080:8080 -v ./data:/data \
  -e VELDOC_AUTH=form \
  -e VELDOC_FORM_USER=admin \
  -e VELDOC_FORM_PASSWORD=secret \
  -e VELDOC_SESSION_SECRET=change-me \
  veldoc

Token auth:

curl -H "Authorization: Bearer my-token" http://localhost:8080/api/tree

Development

go run ./cmd/veldoc --root ./data
go test ./...

License

MIT