bmcgonag/filux repository overview

⁠Filux

A modern, self-hosted, open-source enterprise file storage and sharing application.

⁠Features

Implemented:

• Authentication & Identity (Epic 1) — Password auth (argon2id), TOTP 2FA, WebAuthn passkeys, and OpenID Connect SSO
• Directory architecture (Epic 2) — Unlimited N-level folder nesting, streaming uploads with checksum verification, breadcrumb + sidebar tree navigation, file/folder CRUD, sidebar folder creation with duplicate name prevention
• Granular sharing (Epic 3) — User-to-user RBAC (View/Download/Edit/Delete), public web links with expiration and usage limits, password-protected links, guest preview pages, email share links
• Responsive UI & themes (Epic 4) — Dark/light theme engine, mobile-first layout with a collapsible sidebar drawer, 44px touch targets, validated down to 320px
• Administration & user management (Epic 5) — Admin panel (user list with role badges, quota and status, promote/demote, enable/disable, per-user quota, delete), registration control with manual user provisioning, default and per-user storage quotas with 507 enforcement
• Password lifecycle (Epic 6) — Forgot-password email reset (SMTP), self-service change password, admin password reset with forced change on next login
• Bulk upload & archive management (Epic 7) — Multi-file upload queue with progress and retry, ZIP upload with optional safe extraction (decompression bomb and quota protected) and archive audit logging
• Reverse share (Epic 8) — Inbound "Request Files" links that let guests upload into a folder you choose, with password, expiry, and upload limits, sanitized filenames, and audit logging
• Internationalization (Epic 10) — English + Spanish locales, language selector in the navbar, auth screen and guest preview page, per-user locale persisted to the server, Intl-localized dates, numbers and file sizes, English fallback for missing translations

Planned (see Requirements.md⁠ for full specs and phased roadmap):

• Epic 9 — WebDAV protocol access

⁠Tech Stack

⁠Getting Started

⁠Production Deployment

For production, use the dedicated production compose file with the combined image:

cp .env.production.example .env.production
# Edit .env.production with your domain and secrets
docker compose -f docker-compose.prod.yml up -d

The production image (bmcgonag/filux:latest) runs migrations automatically on startup and serves both frontend and backend through Nginx on port 80.

First user registered becomes admin automatically.

⁠Docker Compose (development)

docker compose up --build -d

• Client: http://localhost:4001⁠
• Server API: http://localhost:3002⁠
• PostgreSQL exposed on 5434, Redis on 6380

⁠Local development

# 1. Start dependencies
docker compose up -d postgres redis

# 2. Backend (http://localhost:3001)
cd server
cp .env.example .env
npm install
npx prisma migrate dev
npm run dev

# 3. Frontend (http://localhost:5173)
cd client
npm install
npm run dev

Note: set CORS_ORIGIN, WEB_AUTHN_RP_ORIGIN, and WEB_AUTHN_RP_ID to http://localhost:5173 for local development (they default to http://localhost:5173).

⁠Project Structure

Filux/
├── Requirements.md              # Feature specs (epics 1-10) & roadmap
├── AGENT.md                     # Session notes & build log
├── docker-compose.yml           # Development: PostgreSQL + Redis + server + client
├── docker-compose.prod.yml      # Production: PostgreSQL + Redis + combined image
├── .env.production.example      # Production environment template
├── server/                      # Fastify + Prisma backend
│   ├── src/routes/              # API route modules (auth, items, share, ...)
│   ├── src/services/            # Business logic (permissions, audit, mailer, ...)
│   ├── src/config/              # Environment config, Prisma & Redis clients
│   ├── prisma/
│   │   ├── schema.prisma        # Data model
│   │   └── migrations/          # Database migrations
│   └── tests/                   # Vitest unit/API/E2E tests
└── client/                      # React + Vite frontend
    ├── src/components/          # UI components (Sidebar, FileList, modals, ...)
    ├── src/pages/               # AuthPage, FolderView, PublicPreview
    ├── src/hooks/               # useAuth, useTheme
    ├── src/i18n/                # Internationalization (en, es)
    └── tests/unit/              # Vitest + Testing Library tests

⁠Testing

cd server && npm run test     # 196 unit + API tests
cd client && npm run test     # 74 unit tests
cd client && npm run lint && npm run build

⁠Roadmap

Delivery phases and dependency notes are documented in Requirements.md⁠. Phases 1-7 (Epics 4-8, 10) are complete: Responsive UI, Administration & Roles, Password Lifecycle, Bulk Upload & Archive Management, Reverse Share (inbound file requests), and Internationalization. Phase 6 (Epic 9, WebDAV) is next.

⁠License

AGPL v3

Open source, self-hosted.