A modern, self-hosted file manager for your homelab
Features • Quick Start • Documentation • Tech Stack
| Feature | Description |
|---|---|
| Multi-Mount Browsing | Browse files across multiple mount points with a clean, intuitive interface |
| Chunked Uploads | Upload large files with resumable transfers and progress tracking |
| Real-time Updates | WebSocket-powered live updates for file changes and job progress |
| Background Jobs | Copy, move, and delete operations run asynchronously with monitoring |
| Fast Search | Recursive directory scanning with name filtering |
| Secure by Default | JWT auth, path traversal protection, configurable credentials, rate limiting |
| Configurable Access | Per-user credentials, read-only mounts, WebSocket origin restrictions |
# Clone the repository
git clone https://github.com/yourusername/homelab-filemanager.git
cd homelab-filemanager
# Copy environment file and configure
cp .env.example .env
# Start the services
docker compose up -dAccess the web interface at http://localhost:3000
See Development Guide for detailed instructions.
| Document | Description |
|---|---|
| API Reference | REST API endpoints and WebSocket events |
| Architecture | System design and component overview |
| Configuration | Environment variables and config options |
| Development | Local setup and development workflow |
| Docker | Container deployment and orchestration |
| Security | Authentication, authorization, and best practices |
Backend
- Go with Chi router
- JWT authentication
- WebSocket support (Gorilla)
- Afero filesystem abstraction
Frontend
- SvelteKit
- TypeScript
- Tailwind CSS
Infrastructure
- Docker & Docker Compose
- Nginx reverse proxy
- Multi-stage builds
homelab-filemanager/
├── backend/ # Go backend service
│ ├── cmd/server/ # Application entrypoint
│ ├── internal/
│ │ ├── config/ # Configuration loading
│ │ ├── handler/ # HTTP handlers
│ │ ├── middleware/ # Auth & security middleware
│ │ ├── model/ # Data models
│ │ ├── pkg/ # Shared utilities
│ │ ├── service/ # Business logic
│ │ └── websocket/ # WebSocket hub & clients
│ └── Dockerfile
├── frontend/ # SvelteKit frontend
│ ├── src/
│ │ ├── lib/
│ │ │ ├── api/ # API client modules
│ │ │ ├── components/ # Svelte components
│ │ │ ├── stores/ # Svelte stores
│ │ │ └── utils/ # Helper functions
│ │ └── routes/ # SvelteKit routes
│ └── Dockerfile
├── nginx/ # Reverse proxy config
├── docs/ # Documentation
└── docker-compose.yml # Container orchestration
Contributions are welcome! Please read the Development Guide before submitting a PR.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
