# 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`](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`](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:

   ```bash
   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:8180` 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:

```bash
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:

```json
{
  "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`:

```bash
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:

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

## Local development over HTTP

> **Warning:** `WEB_FILE_BROWSER_INSECURE_COOKIES=true` is for local
> development or isolated testing only. It lets browsers send an authentication
> cookie over unencrypted HTTP. Never set it for a real, production, or
> publicly exposed deployment.

Session cookies are `Secure` by default. If you need to test directly over
plain HTTP—for example through a LAN address where the browser will not keep a
secure cookie—set the opt-in variable explicitly. All other session behavior,
including `HttpOnly`, `SameSite=Lax`, sliding expiry, and the forced
password-change gate, remains enabled:

```bash
WEB_FILE_BROWSER_INSECURE_COOKIES=true \
  MEDIA_DIR=/srv/webfilebrowser/media \
  docker compose up --build
```

The included Compose file publishes port `8180`, so the local test URL is
`http://localhost:8180` (or `http://<host-ip>:8180` on a trusted test LAN).
For Docker Run, add the following flag to the command above only for the same
local-only purpose:

```bash
--env WEB_FILE_BROWSER_INSECURE_COOKIES=true
```

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

```bash
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:**

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

### Start a new development cycle

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

### Full profile quick start

```bash
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

```bash
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)

```bash
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

```text
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

```bash
aide pr
```

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