jandrop/file-manager-api repository overview

⁠File Manager API

A powerful RESTful API service for managing files and directories, designed for Unraid servers but works on any Linux system. Built with FastAPI and optimized for Docker deployment.

⁠Features

• 📁 File Browsing: Navigate directories with sorting and filtering options
• 📤 File Upload: Multi-file upload with size limits and validation
• 📥 File Download: Stream files directly through the API
• 📂 Directory Operations: Create, delete (with recursive option)
• ✏️ File Operations: Move, copy, rename, and delete files
• 🔍 Search: Search files with wildcard support
• 💾 Disk Usage: Real-time disk space information
• 🔒 Security: API key authentication and configurable permissions
• 🌐 CORS Enabled: Ready for web and mobile applications
• ⚡ Performance: Async/await for high-performance operations

⁠Quick Start

⁠Basic Usage

docker run -d \
  --name file-manager-api \
  -p 8000:8000 \
  -v /mnt/user:/mnt/user \
  -e BASE_PATH=/mnt/user \
  -e API_KEY=your_secret_key \
  jandrop/file-manager-api:latest

Access the API documentation at: http://localhost:8000/docs

⁠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_here
      - MAX_UPLOAD_SIZE=10737418240  # 10GB
      - ENABLE_FILE_DELETION=true
      - ENABLE_RECURSIVE_DELETE=true
    volumes:
      - /mnt/user:/mnt/user
    restart: unless-stopped

Then run:

docker-compose up -d

⁠Environment Variables

⁠API Endpoints

⁠File Browsing

• GET /api/v1/files/browse - List directory contents
• GET /api/v1/files/info - Get file/directory information

⁠File Operations

• GET /api/v1/files/download - Download a file
• POST /api/v1/files/upload - Upload files
• DELETE /api/v1/files/file - Delete a file
• PUT /api/v1/files/rename - Rename a file/directory
• POST /api/v1/files/move - Move a file/directory
• POST /api/v1/files/copy - Copy a file/directory

⁠Directory Operations

• POST /api/v1/files/directory - Create a directory
• DELETE /api/v1/files/directory - Delete a directory

⁠Utilities

• GET /api/v1/files/search - Search for files
• GET /api/v1/files/disk-usage - Get disk usage information
• GET /health - Health check endpoint

⁠Usage Examples

⁠Browse Directory

curl "http://localhost:8000/api/v1/files/browse?path=/mnt/user/documents"

⁠Upload File

curl -X POST \
  -H "X-API-Key: your_secret_key" \
  -F "file=@/path/to/file.pdf" \
  -F "destination_path=/mnt/user/uploads" \
  http://localhost:8000/api/v1/files/upload

⁠Download File

curl -H "X-API-Key: your_secret_key" \
  -O "http://localhost:8000/api/v1/files/download?path=/mnt/user/file.txt"

⁠Search Files

curl "http://localhost:8000/api/v1/files/search?path=/mnt/user&query=*.pdf"

⁠Authentication

To enable API key authentication, set the API_KEY environment variable:

docker run -d \
  -e API_KEY=your_secret_key \
  jandrop/file-manager-api:latest

Then include the key in your requests:

curl -H "X-API-Key: your_secret_key" \
  http://localhost:8000/api/v1/files/browse?path=/mnt/user

⁠Volumes

Mount your file system directories that you want to manage:

# For Unraid
-v /mnt/user:/mnt/user

# For specific directories
-v /path/to/files:/mnt/user

# Multiple volumes
-v /data:/data
-v /media:/media

⁠Ports

• 8000 - API HTTP port (default)

⁠Health Check

The API includes a health check endpoint at /health:

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "base_path": "/mnt/user",
  "base_path_exists": true
}

⁠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.

⁠Web UI (Optional)

Looking for a web interface? Use it together with the File Manager UI:

services:
  file-manager-api:
    image: jandrop/file-manager-api:latest
    # ... configuration

  file-manager-ui:
    image: jandrop/file-manager-ui:latest
    ports:
      - "8764:8764"
    depends_on:
      - file-manager-api

⁠Security Considerations

• Use API Keys: Always set an API key in production environments
• Configure CORS: Limit CORS_ORIGINS to only trusted applications
• Use HTTPS: Run behind a reverse proxy with SSL/TLS in production
• File Permissions: Ensure proper file system permissions
• Network Isolation: Use Docker networks to isolate containers
• Monitor Access: Regularly check logs for suspicious activity

⁠Troubleshooting

⁠Permission Errors

If you encounter permission issues:

# Check container logs
docker logs file-manager-api

# Verify mounted paths exist
docker exec file-manager-api ls -la /mnt/user

⁠Cannot Access Files

• Verify BASE_PATH is set correctly
• Check that volumes are mounted properly
• Ensure the directory exists and has proper permissions

⁠Health Check Fails

# Check if the API is responding
docker exec file-manager-api curl http://localhost:8000/health

# View detailed logs
docker logs file-manager-api

⁠Documentation

• API Documentation: Available at http://localhost:8000/docs (Swagger UI)
• Alternative Docs: Available at http://localhost:8000/redoc (ReDoc)

⁠Version Tags

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

Built with FastAPI • Powered by Docker • Optimized for Unraid