GO — Healthy across the board

• Last commit 1d ago
• 21+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 71% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

FileBrowser Quantum is a self-hosted web-based file manager written in Go (backend) + Vue/TypeScript (frontend) that provides a modern, responsive interface for browsing, managing, and previewing files from a browser. It solves the problem of needing a lightweight, feature-rich alternative to commercial file managers by combining SQLite-backed real-time search/indexing, multi-source configuration with include/exclude rules, and multiple authentication methods (OIDC, LDAP, JWT, 2FA) in a single easy-to-deploy binary. Monorepo structure: Go backend lives in the root (module test at Go 1.25.6), Vue/TypeScript frontend integrated in the same tree. Configuration is centralized (_docker/src/*/backend/config.yaml and frontend-config.yaml for examples), with heavy use of Docker for testing each auth strategy in isolation (Dockerfile.playwright-jwt, Dockerfile.playwright-oidc, etc.). CI/CD orchestrated via GitHub Actions workflows in .github/workflows/.

Self-hosted infrastructure administrators and users who need a personal/organizational file server with advanced features (user management, sharing, previewing) but want to avoid the complexity and cost of enterprise solutions. Also appeals to developers contributing open-source features and Docker deployment enthusiasts.

Production-ready and actively developed. The project has substantial codebase (1.7M LOC Go, 1.1M Vue), comprehensive CI/CD pipelines across 8 GitHub Actions workflows (main.yaml, regular-tests.yaml, release workflows), Docker support with multiple specialized Dockerfiles, and an official documentation site (filebrowserquantum.com). It's a mature fork of the original filebrowser project with significant enhancements ('Quantum' branding suggests aggressive feature expansion).

Low-to-moderate risk for new contributors but medium risk for production deploys without review. Single maintainer (gtsteffaniak) is a concentration risk; the project has substantial complexity (10+ authentication schemes, SQLite indexing, file monitoring) meaning bugs in core features could be impactful. The repo shows active development but lacks visible public issue backlog or open PR count in the provided data; integration test coverage across all auth schemes (JWT, OIDC, LDAP, proxy) via multiple Dockerfile.playwright-* configs suggests good testing, but the breadth of features increases surface area.

Active release cycle management with separate workflows for dev (create-dev-branch.yaml), beta (promote-dev-to-beta.yaml, release_beta.yaml), and stable (promote-beta-to-stable.yaml, release_stable.yaml) tracks. Recent work includes Playwright-based E2E testing infrastructure (multiple Dockerfile.playwright-* variants for different auth modes), Docker image updates (update-build-images.yaml), and tag-based promotion pipeline. The announcement pinned in README suggests major feature launches under discussion.

git clone https://github.com/gtsteffaniak/filebrowser.git
cd filebrowser
# Install dependencies (Go modules auto-resolved, see go.mod in _docker/src/jwt/backend/)
# For frontend: npm install (inferred from Vue/.ts presence)
npm install
# Build and run (see Makefile in file list for exact targets)
make # or check Makefile for dev target

Daily commands:

# Development (inferred from devcontainer + Makefile)
make dev  # Likely starts both backend and frontend watchers
# Or separately:
go run ./... # Backend
npm run dev # Frontend
# Docker (primary method):
docker-compose -f _docker/docker-compose.yaml up
# See specific Dockerfile.playwright-* for auth-specific setups

• backend/adapters/fs/files/files.go — Core file system abstraction layer that handles all file operations; understand this to grasp how the backend interacts with the filesystem
• backend/adapters/fs/diskcache/cache.go — Caching mechanism for file metadata and content; critical for performance optimization across the application
• _docker/src/general/backend/config.yaml — Default backend configuration template that defines all configurable parameters and defaults for the entire application
• .github/workflows/main.yaml — Primary CI/CD pipeline orchestrating builds, tests, and releases; essential for understanding deployment process
• backend/.goreleaser.yaml — Release build configuration defining artifact creation and distribution across multiple platforms and architectures
• CONTRIBUTING.md — Developer guidelines and contribution workflow; mandatory reading for any potential contributor
• README.md — Project overview, features, and architecture documentation; essential context for understanding project scope and design

Add a new file operation (read/write/delete enhancement)

1. Implement the operation handler in the main file service (backend/adapters/fs/files/files.go)
2. Update MIME type detection if handling new file types (backend/adapters/fs/files/mime.go)
3. Add permission checks in the user context handler (backend/adapters/fs/files/user.go)
4. Invalidate relevant cache entries if operation modifies files (backend/adapters/fs/diskcache/cache.go)
5. Add unit tests for the new operation (backend/adapters/fs/files/file_test.go)

Add a new configuration option

1. Add the option to the default configuration template (_docker/src/general/backend/config.yaml)
2. Document the option with comments in the same file (_docker/src/general/backend/config.yaml)
3. Update server configuration if it affects runtime behavior (_docker/src/general/backend/server-config.yaml)
4. Update the CONTRIBUTING guide if the configuration requires setup changes (CONTRIBUTING.md)

Add support for a new authentication method

1. Create a new Docker Compose test environment in _docker/src (_docker/src)
2. Configure the authentication mechanism in the backend config (_docker/src/[auth-type]/backend/config.yaml)
3. Add backend implementation details referencing user.go for permission handling (backend/adapters/fs/files/user.go)
4. Create a test Dockerfile for the new auth type (_docker/Dockerfile.playwright-[auth-type])
5. Update CONTRIBUTING.md with setup instructions for the new auth method (CONTRIBUTING.md)

Improve caching strategy for file metadata

1. Review current cache interface and implementations (backend/adapters/fs/diskcache/cache.go)
2. Modify the file_cache implementation or create a new cache strategy (backend/adapters/fs/diskcache/file_cache.go)
3. Update cache invalidation logic in files handler (backend/adapters/fs/files/files.go)
4. Add tests for the new caching behavior (backend/adapters/fs/diskcache/file_cache_test.go)
5. Document the caching strategy in CONTRIBUTING.md (CONTRIBUTING.md)

• Go + HTTP server — High performance, low memory footprint, single binary deployment ideal for self-hosted file manager with concurrent file operations
• Disk-based caching layer — Reduces filesystem syscalls for frequently accessed metadata; configurable via cache.go abstraction allows testing without actual disk I/O
• Embedded assets (frontend) — Single binary distribution; assets served via fileutils/assets.go avoiding external file dependencies
• Docker multi-stage builds + Playwright tests — Isolated test environments for different auth mechanisms; reproducible configuration testing across JWT, OIDC, proxy, and no-auth scenarios
• GitHub Actions CI/CD — Automated multi-platform builds (Linux, Windows, macOS, ARM); automated beta→stable promotion workflow

• Disk cache vs in-memory cache

  • Why: Disk cache survives restarts and is more suitable for file metadata with variable access patterns
  • Consequence: Slight latency overhead (~1–5ms) vs pure in-memory caching; trade-off favors durability for self-hosted scenario

• User permissions checked per-request via user.go

  • Why: Ensures security by verifying access on every file operation; no pre-computed permission cache
  • Consequence: Per-request overhead; mitigated by file metadata caching which is permission-agnostic

• Single monolithic backend binary with embedded frontend

  • Why: Simplified deployment, minimal dependencies, single service to manage
  • Consequence: Backend and frontend release cycles coupled; frontend rebuilds require full binary rebuild

• Multiple Docker Compose test environments for different auth modes

  • Why: Tests real-world configurations; supports JWT, OIDC, proxy, local auth independently
  • Consequence: Higher test infrastructure maintenance; more CI runners needed; ensures high confidence in each auth mode

• Real-time collaborative file editing (single-user at a time model)
• Distributed filesystem support (local/attached storage only)
• Windows network share authentication via backend (relies on OS-level auth delegation)
• Built-in full-text search indexing (file listing only)
• Data encryption at rest (relies on filesystem-level encryption)

1. Multiple Dockerfile variants: Each auth scheme (JWT, OIDC, LDAP, local, proxy, etc.) has its own Dockerfile.playwright-* — tests may pass in one but fail in another due to config differences. 2. Config cascading: Backend configs in _docker/src/*/backend/ are templates; the actual config resolution order between config.yaml, server-config.yaml, and frontend-config.yaml is not obvious from filenames alone — check the Go code for precedence. 3. SQLite indexing: Real-time file monitoring and search depends on background indexing; misconfiguration can cause stale search results or high CPU usage — verify indexing settings in config.yaml. 4. Docker Compose networking: Services in docker-compose.yaml must be able to reach each other by service name; local dev without Docker may hit host resolution issues. 5. Go 1.25.6 requirement: Newer than typical; verify your environment before building.

• SQLite Indexing with Real-Time Monitoring — FileBrowser Quantum's killer feature (mentioned prominently in README) is fast, real-time search via SQLite indexing with background file system monitoring; understanding how the Go backend watches directories, syncs changes to SQLite, and serves search results is critical for performance tuning and contributing to search/indexing features.
• JWT (JSON Web Tokens) for Authentication — One of four+ auth schemes supported (JWT, OIDC, LDAP, 2FA); the _docker/src/jwt/backend/generate-jwt.go file shows JWT implementation specifics that a contributor modifying auth would need to understand.
• OIDC (OpenID Connect) Authentication Flow — Enterprise users often require OIDC integration for SSO; FileBrowser Quantum supports it via dedicated config and Docker setup in _docker/src/general/, making it essential for understanding multi-tenant auth patterns.
• Multi-Source File Browsing with Include/Exclude Rules — README highlights 'multiple sources, include/exclude rules' as a key differentiator; the config.yaml templates show how to mount multiple filesystem paths and filter them — critical for understanding the file abstraction layer.
• Playwright E2E Testing Across Auth Variants — The repo uses Playwright across 8+ specialized Docker images (playwright-jwt, playwright-oidc, playwright-ldap, etc.) to test each auth scheme in isolation; understanding this matrix testing pattern is essential for adding new features without breaking existing auth flows.
• Docker Compose Multi-Service Orchestration — Primary deployment pattern (_docker/docker-compose.yaml) combines backend, frontend, optional nginx proxy, and auth services; contributors must understand service networking and configuration injection to test locally.
• Vue 3 Composition API with TypeScript — Frontend is modern Vue 3 + TypeScript (mentioned in language stats: 1.1M LOC Vue, 176k TypeScript); Composition API patterns are essential for understanding reactive state management and component lifecycle in the UI layer.

• filebrowser/filebrowser — The original upstream filebrowser project that gtsteffaniak/filebrowser is forked from; useful for understanding design decisions and potential upstreaming opportunities.
• nextcloud/server — Enterprise-grade self-hosted file sync/sharing alternative; FileBrowser Quantum targets the simpler, lighter-weight niche that Nextcloud doesn't fill well.
• miniserve/miniserve — Rust-based minimal file server; same lightweight self-hosted file-serving niche but without the advanced UI and auth features.
• golang-migrate/migrate — Database migration tool likely used for SQLite schema management in the indexing system; relevant for understanding data layer upgrades.
• vuetifyjs/vuetify — Vue UI component library that the frontend almost certainly uses for the 'modern responsive interface' mentioned in the README.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for JWT authentication workflow

The repo has a JWT test Dockerfile (_docker/Dockerfile.playwright-jwt) and JWT config files (_docker/src/jwt/backend/generate-jwt.go, config.yaml), but there's no visible dedicated test suite for the JWT flow. This is critical since JWT is a core authentication mechanism. New contributors can create Playwright tests that validate token generation, validation, refresh, and expiration scenarios.

• [ ] Create _docker/src/jwt/frontend/jwt.spec.ts with Playwright tests
• [ ] Test JWT token generation via generate-jwt.go endpoint
• [ ] Test authenticated requests with valid/invalid/expired tokens
• [ ] Test token refresh mechanism and session persistence
• [ ] Integrate tests into regular-tests.yaml GitHub Action workflow

Add comprehensive tests for OIDC authentication provider

The OIDC configuration exists (_docker/src/oidc/backend/config.yaml and mock-oidc-server.js) but lacks visible end-to-end tests. OIDC is complex with multiple flows (authorization code, implicit, etc.), and there's a mock server setup suggesting testability. This is a high-value contribution for validating SSO functionality.

• [ ] Create _docker/src/oidc/frontend/oidc.spec.ts for Playwright tests
• [ ] Test OIDC discovery endpoint and configuration validation
• [ ] Test authorization code flow with mock-oidc-server.js
• [ ] Test token validation and user claim mapping
• [ ] Test session logout and token revocation
• [ ] Add OIDC test execution to regular-tests.yaml

Add missing proxy authentication tests with real .htpasswd validation

The proxy configuration has a .htpasswd file (_docker/src/proxy/backend/.htpasswd) and config.yaml, indicating proxy auth is supported, but there are no visible test files for this authentication method. This is valuable since proxy-based auth is common in enterprise environments and needs validation.

• [ ] Create _docker/src/proxy/frontend/proxy-auth.spec.ts for Playwright tests
• [ ] Test .htpasswd credential validation (valid/invalid users)
• [ ] Test proxy header passing and authentication header handling
• [ ] Test that unauthorized requests are properly rejected
• [ ] Test multiple user accounts from .htpasswd file
• [ ] Add proxy auth tests to regular-tests.yaml workflow

• Add Playwright E2E tests for the LDAP authentication flow (follow the pattern in _docker/Dockerfile.playwright-jwt and _docker/src/jwt/frontend/playwright.config.ts but create _docker/Dockerfile.playwright-ldap and _docker/src/ldap/frontend/playwright.config.ts with LDAP-specific test cases).
• Document the file indexing and search filter capabilities in the official docs — the README mentions 'Search supports file and folder sizes, along with various filters' but the specific filter syntax and size query examples are missing from the visible config files.
• Create a Makefile target that runs all auth-variant Docker tests in parallel (currently requires manually invoking different docker build -f _docker/Dockerfile.playwright-* commands) to reduce local test cycle time from ~15min to ~5min.

• High · Hardcoded Credentials in Configuration Files — _docker/src/proxy/backend/.htpasswd, _docker/src/*/backend/config.yaml files. Multiple Docker test configurations contain hardcoded credentials and authentication tokens. The file '_docker/src/proxy/backend/.htpasswd' contains password hashes, and various config.yaml files may contain sensitive authentication details for different authentication schemes (JWT, OIDC, etc.). Fix: Remove hardcoded credentials from version control. Use environment variables or secret management systems for authentication credentials. Implement proper secrets rotation policies.
• High · Exposed Test Credentials and Mock Services — _docker/src/oidc/frontend/mock-oidc-server.js, _docker/src/jwt/backend/generate-jwt.go. Mock OIDC server and JWT generation utilities are present in the codebase (_docker/src/oidc/frontend/mock-oidc-server.js, _docker/src/jwt/backend/generate-jwt.go), potentially exposing authentication logic and allowing attackers to understand authentication mechanisms. Fix: Ensure mock services and test credentials are only available in development/test environments. Do not commit test authentication generators to production branches. Implement proper branching strategy to separate dev and production code.
• Medium · Multiple Authentication Configurations Exposed — _docker/src/*/backend/config.yaml, _docker/src/jwt/backend/default.conf, _docker/src/proxy/backend/default.conf. The codebase contains multiple authentication configuration examples (JWT, OIDC, Proxy, Local) in plaintext YAML and configuration files. This exposes the authentication architecture and potential weaknesses. Fix: Move sensitive configuration examples to documentation outside the repository. Implement configuration templating that uses environment variable substitution. Use .gitignore to exclude actual configuration files with credentials.
• Medium · Potential Insecure Direct Object References (IDOR) Risk — backend (core file handling logic). As a file browser application, there is inherent risk of IDOR vulnerabilities in file access operations. The codebase structure suggests file operations are a core feature, but without access to the actual code, proper authorization checks cannot be verified. Fix: Implement strict access control lists (ACLs) for all file operations. Verify user permissions on every file access request. Use user IDs rather than predictable identifiers. Implement comprehensive access logging.
• Medium · Docker Image Security Concerns — _docker/Dockerfile*, _docker/Dockerfile.playwright-*. Multiple Dockerfile variants are present without visible base image version pinning (Dockerfile.playwright-base, etc.). Unversioned base images can introduce vulnerabilities from upstream updates. Fix: Pin all base image versions to specific digests. Regularly scan Docker images for vulnerabilities using tools like Trivy or Grype. Implement automated base image update policies with testing.
• Medium · Go Version Dependency on Unreleased Version — go.mod, backend/.air.toml, _docker/src/jwt/backend/go.mod. The go.mod specifies 'go 1.25.6', which appears to be unreleased or bleeding-edge. This may introduce stability and security issues. Fix: Use stable, officially released Go versions. Target the latest stable release (currently 1.23.x series as of 2024). Regularly update dependencies and test for compatibility.
• Low · Incomplete Information on Input Validation — backend (general file handling). As a web file browser, the application handles user input for file paths and names. Without access to the source code, potential XSS or path traversal vulnerabilities cannot be definitively assessed. Fix: Implement strict input validation for all file paths and names. Use allowlist-based validation. Prevent path traversal using secure path resolution libraries. Implement Content Security Policy (CSP) headers to mitigate XSS risks.
• Low · GitHub Actions Workflow Security — .github/workflows/*.yaml. Multiple GitHub workflow files present (.github/workflows/*.yaml). Without reviewing their contents, potential issues like insecure secret handling or overly permissive permissions cannot be verified. Fix: Review all workflow files for secure secret handling. Use GitHub Actions' built-in secret masking. Implement least-

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gtsteffaniak/filebrowser shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gtsteffaniak/filebrowser repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gtsteffaniak/filebrowser.

What it runs against: a local clone of gtsteffaniak/filebrowser — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gtsteffaniak/filebrowser | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gtsteffaniak/filebrowser. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gtsteffaniak/filebrowser.git
#   cd filebrowser
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gtsteffaniak/filebrowser and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gtsteffaniak/filebrowser(\\.git)?\\b" \\
  && ok "origin remote is gtsteffaniak/filebrowser" \\
  || miss "origin remote is not gtsteffaniak/filebrowser (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "backend/adapters/fs/files/files.go" \\
  && ok "backend/adapters/fs/files/files.go" \\
  || miss "missing critical file: backend/adapters/fs/files/files.go"
test -f "backend/adapters/fs/diskcache/cache.go" \\
  && ok "backend/adapters/fs/diskcache/cache.go" \\
  || miss "missing critical file: backend/adapters/fs/diskcache/cache.go"
test -f "_docker/src/general/backend/config.yaml" \\
  && ok "_docker/src/general/backend/config.yaml" \\
  || miss "missing critical file: _docker/src/general/backend/config.yaml"
test -f ".github/workflows/main.yaml" \\
  && ok ".github/workflows/main.yaml" \\
  || miss "missing critical file: .github/workflows/main.yaml"
test -f "backend/.goreleaser.yaml" \\
  && ok "backend/.goreleaser.yaml" \\
  || miss "missing critical file: backend/.goreleaser.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gtsteffaniak/filebrowser"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.