DirForge

DirForge

A stateless, read-only web file browser for homelab and NAS power users. No database, no background workers, no disk writes - just point it at a mounted path and go.

Browse files in a clean web UI with search, previews, and archive inspection. Download individual files or entire folders as ZIP. Access the same data through a RESTful JSON API, an S3-compatible endpoint for tools like rclone, a read-only WebDAV mount for native OS file managers, or an MCP server for AI assistants. Everything runs in a single stateless container with no external dependencies.

Quick Start

Prerequisite: Docker or Podman (images are published for amd64 and arm64).

Docker run

docker run -d \
  --name dirforge \
  -p 8091:8080 \
  -e RootPath=/data \
  -v /srv/share:/data:ro \
  ghcr.io/dissimilis/dirforge:latest

Docker Compose

cp .env.example .env
# edit HOST_PATH, BasicAuthUser, and BasicAuthPass in .env
docker compose up -d

Warning: The default compose file falls back to admin/dirforge credentials if you don't set BasicAuthUser and BasicAuthPass in your .env. Change these before exposing the service on your network.

Podman

The same commands work with Podman. Replace docker with podman:

podman run -d \
  --name dirforge \
  -p 8091:8080 \
  -e RootPath=/data \
  -v /srv/share:/data:ro \
  ghcr.io/dissimilis/dirforge:latest

For Compose, use podman compose (Podman 4.1+):

cp .env.example .env
# edit HOST_PATH in .env
podman compose up -d

Notes for Podman users:

• podman compose is a built-in subcommand in Podman 4.1+, not the older third-party podman-compose Python package.
• DirForge uses ports above 1024, so rootless Podman works without extra configuration.
• On SELinux systems (Fedora, RHEL), add :z to volume mounts: -v /srv/share:/data:ro,z.

Standalone (Windows)

1. Download dirforge-win-x64.zip from the latest release
2. Extract to a folder (e.g. C:\DirForge)
3. Edit appsettings.json — set RootPath to the directory you want to share
4. Console mode: Double-click DirForge.exe to run interactively
5. Windows Service: Right-click install-service.bat → Run as administrator. DirForge will start on boot automatically. Use uninstall-service.bat to remove the service.

Standalone (Linux)

1. Download dirforge-linux-x64.tar.gz (or linux-arm64) from the latest release
2. Extract: tar -xzf dirforge-linux-x64.tar.gz -C /opt/dirforge
3. Edit appsettings.json — set RootPath to the directory you want to share
4. Run directly: ./DirForge
5. Install as systemd service:

   sudo useradd -r -s /usr/sbin/nologin dirforge
   sudo cp dirforge.service /etc/systemd/system/
   # Edit /etc/systemd/system/dirforge.service to adjust paths if needed
   sudo systemctl daemon-reload
   sudo systemctl enable --now dirforge

   Copy to clipboard

The tarball includes an example dirforge.service file with systemd hardening options.

Open http://localhost:8091. With the default config profile in this repository, sharing, dashboard, and metrics are enabled.

Features

Browsing

• List and grid view layouts
• Sortable columns (name, size, date)
• Light and dark themes (toggle or set default via DefaultTheme)
• File preview modal for text, images, video, audio, and PDF
• Inline archive browser for .zip, .tar, .tar.gz, .tgz, and .gz
• Image lightbox with navigation
• Recursive search with configurable depth and time budget
• Age badges on files and folders
• Custom site title via SiteTitle

Sharing & Downloads

• Direct file downloads
• Folder download as ZIP archive (with configurable max size)
• Signed share links with expiry
• One-time share links
• QR code generation for share links
• File hash calculation (CRC32, MD5, SHA-1, SHA-256, SHA-512)
• Sidecar checksum verification (.md5, .sha1, .sha256, .sha512, .sfv)

WebDAV

• Read-only WebDAV endpoint at /webdav/ (DAV Class 1)
• Supports OPTIONS, PROPFIND, GET, and HEAD methods
• Compatible with Windows Explorer, macOS Finder, and other WebDAV clients
• Same security policies as the web UI (hidden paths, denied extensions, auth)

S3-Compatible API

• Read-only S3 endpoint at /s3/ for scripted and programmatic access
• Compatible with aws cli, rclone, MinIO client, and other S3-compatible tools
• AWS Signature V4 authentication (access key + secret key)
• Supports ListBuckets, GetBucketLocation, ListObjectsV2, GetObject, HeadObject
• HTTP Range requests for partial downloads
• Hidden paths, denied extensions, and auth enforced

Security & Operations

• HTTP Basic Auth (username + password)
• Bearer token auth via configurable header (for MCP clients, API consumers, automation)
• External auth via reverse proxy headers (e.g. Authelia, Authentik)
• Hide files by dotfile flag or glob patterns
• Deny downloads by file extension
• Fixed-window rate limiting (per-IP and global)
• Health endpoints (/health, /healthz, /readyz)
• In-memory dashboard at /dashboard with optional dedicated credentials
• Prometheus metrics at /metrics
• RESTful JSON API at /api/ (browse, search, share, archive)
• MCP server at /mcp/ (JSON-RPC 2.0, Streamable HTTP transport)
• Integration stats JSON at /dashboard/stats
• Distroless chiseled container image

Configuration

Defaults are defined in src/DirForge/appsettings.json. Override any value with an environment variable of the same name. Boolean values must be true or false. For the full list of options, see .env.example.

Security

Hardened example profile - copy into your .env and adjust:

BasicAuthUser=admin
BasicAuthPass=change-this
BearerToken=replace-with-long-random-token
ShareSecret=replace-with-long-random-value
ForwardedHeadersKnownProxies=10.0.0.2
DashboardAuthUser=metrics
DashboardAuthPass=change-this-too

• Mount only directories you want to expose; prefer read-only mounts (:ro).
• Baseline defaults are homelab-oriented, not internet-hardened.
• Set BasicAuthUser / BasicAuthPass when exposed outside a trusted network.
• Set BearerToken for token-based auth (useful for MCP clients, API consumers, and automation that poorly support Basic Auth). Both auth methods can be enabled simultaneously, either one grants access.
• When BearerTokenHeaderName is Authorization (default), the middleware accepts Authorization: Bearer <token> and Authorization: <token>. Set a custom header name (e.g. X-API-Key) to read the raw token from that header instead.
• Set ShareSecret to a long random value in production. If empty, DirForge uses an in-memory secret and share links reset on restart.
• For reverse proxy auth, set ExternalAuthEnabled=true and pin ForwardedHeadersKnownProxies. Bearer token auth is also bypassed when external auth is enabled.
• Hidden paths and denied extensions are enforced for both direct downloads and ZIP output.
• Dashboard and metrics data are in-memory only and reset on restart.
• If DashboardAuthUser / DashboardAuthPass are set, /dashboard and /metrics accept only those credentials.
• /dashboard/stats uses the same dashboard auth behavior: if dashboard credentials are configured, they are required.
• Static UI assets are served from /dirforge-assets/* (plus /favicon.ico) and are intentionally public.

WebDAV

DirForge includes a read-only WebDAV endpoint at /webdav/ (DAV Class 1), enabled by default. It supports OPTIONS, PROPFIND, GET, and HEAD. All write methods return 405 Method Not Allowed.

Client Access

Windows HTTP Limitation

Windows Explorer's WebDAV client (Mini-Redirector) refuses Basic Auth over plain HTTP by default. You must either:

• Use HTTPS (via reverse proxy, recommended)
• Set the registry key HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters\BasicAuthLevel to 2 and restart the WebClient service

Security

WebDAV requests follow the same auth and security pipeline as the web UI:

• Basic Auth or bearer token credentials are required when configured
• External auth headers are honored when ExternalAuthEnabled=true
• Hidden paths (HideDotfiles, HidePathPatterns) and denied extensions (DenyDownloadExtensions) are enforced
• Path traversal protection applies to all WebDAV paths

Set EnableWebDav=false to disable the endpoint entirely.

S3-Compatible API

DirForge includes a read-only S3-compatible endpoint at /s3/, disabled by default. It implements the minimal subset of the S3 API needed for listing and downloading files with standard S3 tools.

Supported Operations

…