jandrop/file-manager-ui repository overview

⁠File Manager Web UI

A modern, production-ready web interface for the File Manager API. Built with React, Vite, and Material UI (Material Design 3) for a beautiful and responsive file management experience.

⁠Features

⁠🎨 Modern UI/UX

• Material Design 3 components with smooth animations
• Dark & Light mode with persistent theme preference
• Responsive design - works seamlessly on desktop, tablet, and mobile
• Professional aesthetic - production-ready appearance

⁠📁 File Management

• Browse directories with intuitive breadcrumb navigation
• Upload files with drag-and-drop and progress tracking
• Download files directly from the browser
• Create folders with validation
• Rename files/folders with inline editing
• Delete files/folders with confirmation dialogs
• Search files with real-time filtering
• File type icons for easy identification

⁠⚡ Performance

• Fast loading with optimized Vite build
• Cached API calls with React Query
• Smooth animations and transitions
• Real-time updates for all operations

⁠Quick Start

⁠Prerequisites

You need the File Manager API running. The UI container will connect to it automatically when using Docker Compose.

⁠Using Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'

services:
  file-manager-api:
    image: jandrop/file-manager-api:latest
    container_name: file-manager-api
    ports:
      - "8000:8000"
    environment:
      - BASE_PATH=/mnt/user
      - API_KEY=your_secret_key
      - CORS_ORIGINS=["http://localhost:8764"]
    volumes:
      - /mnt/user:/mnt/user
    restart: unless-stopped
    networks:
      - file-manager-network

  file-manager-ui:
    image: jandrop/file-manager-ui:latest
    container_name: file-manager-ui
    ports:
      - "8764:8764"
    depends_on:
      - file-manager-api
    restart: unless-stopped
    networks:
      - file-manager-network

networks:
  file-manager-network:
    driver: bridge

Then run:

docker-compose up -d

Access the UI at: http://localhost:8764

⁠Standalone Usage

If you already have the API running, you can run the UI separately:

docker run -d \
  --name file-manager-ui \
  -p 8764:8764 \
  --link file-manager-api:file-manager-api \
  jandrop/file-manager-ui:latest

Important: The UI container needs to communicate with the API container. Use --link or a Docker network.

⁠Configuration

⁠Network Configuration

The UI needs to reach the API. The default nginx configuration expects the API at http://file-manager-api:8000.

Using Docker Compose: The network is configured automatically.

Using docker run: Use the --link flag:

docker run -d \
  --link file-manager-api:file-manager-api \
  jandrop/file-manager-ui:latest

Using custom network:

# Create network
docker network create file-manager-network

# Run API
docker run -d \
  --name file-manager-api \
  --network file-manager-network \
  jandrop/file-manager-api:latest

# Run UI
docker run -d \
  --name file-manager-ui \
  --network file-manager-network \
  jandrop/file-manager-ui:latest

⁠API Key Configuration

If your API requires an API key:

1. The UI will prompt you for the key on first access
2. The key is stored in browser localStorage
3. It's automatically included in all API requests

You can also set it via browser console:

localStorage.setItem('api_key', 'your-api-key-here');

⁠Ports

• 8764 - Web UI HTTP port (default)

⁠Supported Architectures

This image supports multiple architectures:

• linux/amd64 (x86_64)
• linux/arm64 (ARM 64-bit, Apple Silicon, Raspberry Pi)

Docker will automatically pull the correct architecture for your platform.

⁠Features in Detail

⁠File Operations

Upload Files:

• Drag-and-drop files anywhere in the UI
• Click the upload button to browse files
• Multiple file selection supported
• Real-time progress tracking
• Size validation and error handling

Delete Files/Folders:

• Confirmation dialog prevents accidents
• Recursive delete option for folders
• Clear warning messages

Rename:

• Inline validation
• Conflict prevention
• Keyboard shortcuts (Enter to confirm, Esc to cancel)

Create Folder:

• Name validation
• Visual path display
• Parent directory handling

⁠Theme System

• Light Mode: Clean and professional
• Dark Mode: Easy on the eyes
• Persistent: Your choice is saved
• Smooth Transitions: Animated theme switching
• Accessible: WCAG compliant colors

⁠File Type Icons

Intelligent icons based on file extensions:

• 📁 Folders
• 🖼️ Images (jpg, png, gif, svg, webp)
• 🎬 Videos (mp4, avi, mkv, mov)
• 🎵 Audio (mp3, wav, flac, aac)
• 📄 Documents (doc, docx, txt, pdf)
• 📊 Spreadsheets (xls, xlsx, csv)
• 🗜️ Archives (zip, rar, 7z, tar, gz)
• 💻 Code files (js, py, java, go, rs)

⁠Responsive Design

• Desktop: Full-featured layout with all controls visible
• Tablet: Optimized touch targets and spacing
• Mobile: Compact navigation with drawer menus

⁠API Compatibility

This UI is designed to work with the File Manager API. Both containers are kept in sync and released together.

Recommended: Use matching version tags for both containers:

services:
  file-manager-api:
    image: jandrop/file-manager-api:1.0.0

  file-manager-ui:
    image: jandrop/file-manager-ui:1.0.0

⁠Troubleshooting

⁠UI Container Restarts Constantly

Problem: The container keeps restarting and shows errors in logs.

Solution: The UI cannot connect to the API. Make sure:

1. The API container is running
2. Both containers are on the same network
3. The API container is named file-manager-api OR you're using --link

Check logs:

docker logs file-manager-ui

⁠Cannot Access the UI

Solution:

1. Verify the container is running: docker ps | grep file-manager-ui
2. Check port mapping: docker port file-manager-ui
3. Verify no firewall is blocking port 8764

⁠API Connection Errors in Browser

Solution:

1. Check browser console for error messages
2. Verify API CORS settings allow http://localhost:8764
3. Test API directly: curl http://localhost:8000/health

⁠File Upload Fails

Solution:

1. Check file size limits in the API configuration
2. Verify destination folder permissions
3. Check browser Network tab for detailed errors
4. Ensure the API has write access to the destination path

⁠Theme Not Saving

Solution: Check browser localStorage is enabled. Some privacy modes disable localStorage.

⁠Unraid Setup

Access at: http://your-unraid-ip:8764

⁠Reverse Proxy

To run behind a reverse proxy (nginx, Caddy, Traefik):

Nginx example:

server {
    listen 80;
    server_name files.yourdomain.com;

    location / {
        proxy_pass http://localhost:8764;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /api/ {
        proxy_pass http://localhost:8000/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

⁠Version Tags

• latest - Latest stable release
• 1.x.x - Specific version tags
• main - Latest development build

⁠Health Check

The UI includes a health check that verifies nginx is running:

docker inspect --format='{{.State.Health.Status}}' file-manager-ui

⁠Documentation

• API Documentation: Available when API is running at http://localhost:8000/docs

⁠Technology Stack

• React 18.2
• Vite 5
• Material UI 5 (Material Design 3)
• TanStack Query (React Query)
• Nginx (for serving and API proxying)

⁠License

This project is licensed under the MIT License.

Built with React • Styled with Material UI • Optimized for Performance