webFileBrowser

Overview

A lightweight, container-based file browser for named host folders mounted read-only into a container. It provides login-gated browsing, downloads, and native video streaming without server-side media processing.

Deploy with Docker Compose

Docker and the Docker Compose plugin are the only prerequisites for the included deployment configuration.

1. Update config/roots.example.json with each root's display name and its absolute path inside the container.

2. Mount the matching host folders at those paths. The included compose.yaml maps ${MEDIA_DIR:-./example-files} to /mnt/media as an example. Set MEDIA_DIR to an absolute host path for a production deployment.

3. Start the service in the background:

   MEDIA_DIR=/srv/webfilebrowser/media docker compose up --build -d
   

The Compose service restarts unless stopped explicitly. It persists SQLite data in the webfilebrowser-data named volume and mounts every configured browse root read-only. The server listens on http://localhost:8080 and logs every configured root at startup. /login is the only public application route; every other route redirects to login until it has a valid server-side session.

Deploy with Docker Run

To use the image without Compose, build it, create the persistent data volume, and mount both the roots configuration and the host folders named by it:

docker build --tag webfilebrowser:latest .
docker volume create webfilebrowser-data
MEDIA_DIR=/srv/webfilebrowser/media
docker run --detach --name webfilebrowser --restart unless-stopped \
  --publish 127.0.0.1:8080:8080 \
  --env WEB_FILE_BROWSER_ROOTS_FILE=/etc/webfilebrowser/roots.json \
  --volume "$PWD/config/roots.example.json:/etc/webfilebrowser/roots.json:ro" \
  --volume "$MEDIA_DIR:/mnt/media:ro" \
  --volume webfilebrowser-data:/var/lib/webfilebrowser \
  webfilebrowser:latest

The image runs as an unprivileged webfilebrowser user and contains only the compiled application and its Alpine runtime dependencies; Go and build tools remain in the multi-stage build image. Keep the data volume when recreating or upgrading the container so accounts and sessions persist.

Root configuration

Set WEB_FILE_BROWSER_ROOTS_FILE to a JSON configuration file containing a roots array. Each root has a human-readable name and an absolute path inside the container:

{
  "roots": [
    {"name": "Media", "path": "/mnt/media"},
    {"name": "Documents", "path": "/mnt/documents"}
  ]
}

Alternatively, set WEB_FILE_BROWSER_ROOTS to a JSON array of the same root objects. This environment variable takes precedence over WEB_FILE_BROWSER_ROOTS_FILE:

WEB_FILE_BROWSER_ROOTS='[{"name":"Media","path":"/mnt/media"}]' \
  docker compose up --build

Each configured container path must be supplied by a Docker volume mount. To add or remove a root, update both the configuration and the container's volume mounts, then restart the container. Roots are intentionally fixed at startup; they cannot be changed from the application.

Authentication and persistent data

The application stores users and server-side sessions in SQLite. By default, the database is /var/lib/webfilebrowser/webfilebrowser.db; set WEB_FILE_BROWSER_DATABASE_PATH to use another path. The Compose example uses a named volume for this directory, so users and active sessions survive a container restart.

On the first database initialization, webFileBrowser creates this temporary administrator account:

Email:    boss@zecevic-ninja.com
Password: Start1234!

That account must change its password immediately after the first successful login. It cannot access browsing, download, streaming, or administration routes until the new password differs from the temporary password. Sessions are stored server-side, use a seven-day sliding expiry, and are invalidated on logout.

The session cookie is always HttpOnly, Secure, and SameSite=Lax. Terminate TLS at a reverse proxy before exposing the service; browsers will not send the secure cookie over plain HTTP. Bind the application to loopback as in the Docker Run example, terminate TLS at the reverse proxy, and forward the original Host and Range request headers to the application.

User administration

After changing the seeded administrator password, use Manage users on the roots page to open /admin/users. Administrators can review every account, create either a user or administrator account, issue a replacement temporary password, disable an account, or delete it permanently. A newly created account and every password reset require the account holder to choose a new password before it can access the application.

Disabling an account immediately prevents further sign-ins and invalidates its active sessions; deleting an account also removes its sessions. Standard users can browse, download, and stream configured roots, but every administration route responds with 403 Forbidden for them without redirecting to an admin page.

Browsing folders

After changing the temporary password, select a configured root from the home page and enter folders by clicking their names. Breadcrumb links take you back through the current path. Each directory view shows the item name, type, size, and last-modified time; this interface is read-only.

Every requested folder is resolved against its configured root. Parent-path traversal and symlinks that resolve outside that root are rejected, so a mounted folder cannot be used to browse unrelated container paths.

Use the theme button in the page header to switch between light and dark modes. The preference is stored in the browser's local storage and is restored on the next visit from that browser.

Downloads and video streaming

Every listed file has a download link that returns its original bytes as an attachment. Recognized video files also have a streaming link. The application uses HTTP byte ranges for video seeking and resumable playback; it never transcodes, encodes, thumbnails, or otherwise transforms media.

Your TLS reverse proxy must pass the request Range header through to the application and preserve range responses such as 206 Partial Content, Content-Range, and Accept-Ranges. Do not buffer or replace these responses, or native browser seeking will not work.

Deployment smoke test

Run the documented end-to-end deployment smoke test after changing container packaging or before promoting an image:

bash scripts/test-production-deployment.sh

It builds the image, starts an isolated container with temporary configuration, media, and SQLite-volume mounts, verifies that the login page is public and the root page redirects unauthenticated requests, then removes the temporary container and volume.

AI Workflow

This project includes the persistent planner/implementer/reviewer workflow with file-based coordination, plus the PO orchestration layer. Manual and auto are two runtime modes for the same scaffold: they use the same generated files, task board, and review gate. Fewer role sessions means less coordination overhead and lower token cost.

Modes

This scaffold supports two workflow profiles that share the same generated files, task board, plan, review log, and handoff log.

• full keeps the planner, implementer, reviewer, and optional PO split.
• lite keeps the planner but replaces separate implementer/reviewer sessions with one aide dev session.

Profile	Sessions and launchers	Who drives work	Commit cadence	PO support	Recommended fit
full	aide plan, aide implement, aide review, optional aide po	Separate role sessions with explicit implement/review handoffs	One final task commit after reviewer approval	yes	Larger, riskier, or more review-heavy changes
lite	aide plan, aide dev	Planner plus one dev session that implements and reviews, then halts for human approval at ready_for_review	One real commit per task, including all_task	no	Smaller changes or lower-coordination work

How to switch

aide profile full
aide profile lite

Use aide profile full to return to the split workflow, or aide profile lite to switch to the dev-session flow.

full is the default for new scaffolds. When you switch to lite, aide implement, aide review, and aide po refuse and point you at aide dev. When you switch back to full, aide dev refuses and points you at aide implement and aide review.

Runtime modes

• Manual mode: start the planner, implementer, and reviewer in separate terminals, then drive each session yourself with the documented text commands.
• Auto mode: run aide po to start the PO session, which uses MCP tools to coordinate the post-planning implementer/reviewer workflow for you.

Concepts

Cycle — a unit of work on a feature branch. One cycle = one branch = one PR.

Roles and file ownership:

Role	Reads	Writes
PO	.ai/TASKS.md, .ai/PLAN.md, .ai/REVIEW.md, .ai/prompts/po.md	MCP session commands via aide po
Planner	ROADMAP.md	.ai/PLAN.md, .ai/TASKS.md
Implementer	.ai/PLAN.md, .ai/REVIEW.md	source code, .ai/TASKS.md
Reviewer	.ai/PLAN.md, commits	.ai/REVIEW.md, .ai/TASKS.md

Status flow:

in_planning → ready_for_implement → in_implementation → ready_for_review → in_review → ready_to_commit → done
                                          ↑                                     |
                                          └──── changes_requested ◄─────────────┘

Start a new development cycle

# Edit ROADMAP.md with your goals first, then:
aide cycle start feature/<scope>

Full profile quick start

aide plan          # terminal 1
aide implement     # terminal 2
aide review        # terminal 3

Launch each role once, then keep those sessions open for the rest of the cycle.

Role launchers read default agent/model settings from .ai/config.json. To override, pass the agent first, then any CLI flags. Example: aide review claude --model sonnet Claude starts interactively by default, and the Codex launcher uses interactive codex mode so the session stays open for role commands.

Lite profile quick start

aide profile lite
aide plan          # terminal 1
aide dev           # terminal 2

The dev session handles implementation and review, then halts for human approval at ready_for_review. In lite mode, aide implement, aide review, and aide po refuse and point you at aide dev.

Start the PO orchestrator (auto mode)

aide po

The PO session drives the post-planning task board flow through the aide MCP server. PO orchestration is available only in the full profile. By default, aide po launches Claude with --model haiku, and aide po codex launches Codex with -m gpt-5.4-mini. .ai/config.json can override those defaults, and an explicit CLI --model or -m flag takes precedence. If no tasks are in ready_for_implement or later, run the planner first. The normal MCP completion path is session_run followed by session_wait, then a re-read of .ai/TASKS.md; session_get_output is for debugging only. The MCP server appends structured debug logs to .ai/mcp-server.log, and the scaffold gitignore excludes that file.

Drive work inside the existing sessions

planner> start_plan
implementer> next_task T-001
reviewer> next_task T-001
implementer> commit_task T-001
dev> next_task T-001
dev> commit_task T-001
implementer> rework_task T-001
aide cycle end 0.7.0

Cross-platform CLI equivalents: aide cycle end [VERSION] closes the cycle outside the persistent role session, and aide pr [--dry-run] creates or updates the branch PR.

Planner commands:

Before start_plan, freeform conversation with the planner is the roadmap-refinement phase. Use it to sharpen scope, acceptance criteria, constraints, and trade-offs directly in ROADMAP.md. start_plan is the explicit handoff into formal planning.

Command	Description
start_plan	Read ROADMAP.md, write .ai/PLAN.md and .ai/TASKS.md
rework_plan [TASK_ID]	Revisit the plan when scope or approach changes

Implementer commands:

Command	Description
next_task [TASK_ID]	Pick up the next ready_for_implement task
commit_task [TASK_ID]	Turn a ready_to_commit task into one clean final commit, including task-specific .ai/ artifacts
rework_task [TASK_ID]	Address changes_requested findings from .ai/REVIEW.md
aide cycle end [VERSION]	Close the cycle after all tasks reach done, committing remaining .ai/ artifacts with a Release-As: footer
status_cycle [TASK_ID]	Show task status and recommended next action

Reviewer commands:

Command	Description
next_task [TASK_ID]	Pick up the next ready_for_review task and run review plus verification
status_cycle [TASK_ID]	Show task status and recommended next action

File map

File	Purpose	Tracked
.ai/PLAN.md	Current plan	yes
.ai/TASKS.md	Task board with status	yes
.ai/prompts/po.md	PO orchestration prompt for auto mode	yes
.ai/REVIEW.md	Review findings	yes (tracked cycle log)
.ai/HANDOFF.md	Runtime handoff log	yes (tracked cycle log)
.ai/config.json	Per-role launch defaults	yes
ROADMAP.md	Cycle goals (edit before planning)	yes
AGENTS.md	Project-specific and workflow-managed agent rules	yes
CLAUDE.md	Agent instruction entry point (@AGENTS.md)	yes
aide po	Launch the PO orchestration session	yes

Create a PR

aide pr

Full workflow details and session recovery rules are in AGENTS.md.