How to Deploy & Use FineUploader/fine-uploader

# FineUploader Deployment & Usage Guide

> **⚠️ Important Notice**: FineUploader is no longer maintained and the project has been effectively shut down. This guide is provided for legacy/archival purposes only. For more information, see [the official announcement](https://github.com/FineUploader/fine-uploader/issues/2073).

---

## 1. Prerequisites

### For Building from Source
- **Node.js** (any recent version) with `npm`
- **GNU Make** (available on Linux/macOS; Windows users may need WSL or MinGW)
- **Git** client
- **Unix-like environment** (Linux, macOS, or Windows 10+ with WSL/bash)
- **Firefox** (for running the test suite locally)

### For Using the Library
- A modern web browser (FineUploader supports all major browsers, including IE 10+)
- A web server to serve your static assets (for development, any simple HTTP server will suffice)
- If using cloud storage endpoints (S3/Azure):
  - **AWS S3**: An S3 bucket with appropriate CORS configuration and credentials
  - **Azure Blob Storage**: A storage container with CORS settings and access credentials

---

## 2. Installation

### Option A: Install via npm (Recommended for Production)
```bash
npm install fine-uploader

This installs the library into your node_modules directory. You can then copy the necessary files from node_modules/fine-uploader/ to your project's public assets.

Option B: Clone and Build from Source

# 1. Clone the repository
git clone https://github.com/FineUploader/fine-uploader.git
cd fine-uploader

# 2. Install development dependencies
npm install

3. Configuration

FineUploader is configured via a JavaScript options object when initializing. Key configuration areas:

Basic Endpoint Configuration

var uploader = new qq.FineUploader({
    element: document.getElementById('fine-uploader'),
    request: {
        endpoint: '/upload' // Your server endpoint OR S3/Azure configuration
    }
});

S3 Configuration (Client-Side Signing)

var uploader = new qq.FineUploader({
    request: {
        endpoint: 'https://your-bucket.s3.amazonaws.com',
        accessKey: 'YOUR_AWS_ACCESS_KEY', // Not recommended for production
        signature: {
            // See client/js/s3/request-signer.js for full options
            version: 4, // or 2
            customHeaders: {}, // optional custom headers
            drift: 0 // time drift in seconds
        }
    },
    signature: {
        // If using server-side signing
        endpoint: '/s3/signature' // Your server endpoint that returns signatures
    }
});

Azure Blob Storage Configuration

var uploader = new qq.FineUploader({
    request: {
        endpoint: 'https://your-account.blob.core.windows.net/your-container',
        customHeaders: {
            'x-ms-blob-type': 'BlockBlob'
        },
        // Azure-specific options
        azure: {
            container: 'your-container',
            storageKey: 'your-storage-key' // For client-side signing
        }
    }
});

Key Options (from source analysis)

chunking: Enable/configure chunked uploads ({enabled: true})
resume: Enable resume capability ({enabled: true})
scaling: Configure image scaling ({sizes: [{name: "large", maxSize: 800}]})
thumbnails: Placeholder settings ({placeholders: {waitingForThumbnail: "Loading..."}})
text: All UI text strings
classes: Custom CSS class names
validation: File size/type restrictions

4. Build & Run

Building the Library

# Build all endpoint types (S3, Azure, basic)
make build

# Build only specific endpoint (e.g., S3)
make build-s3

# Create distributable ZIP files
make zip

# Bump version number (for contributors)
make rev-version target=NEW_VERSION

Build artifacts output to the _build/ directory.

Running Tests & Linter

npm test

This builds the project and runs tests in Firefox.

Development Workflow

Make code changes
Run make build (or make build -j for parallel builds)
Include built files from _build/ in your test HTML page
Open your test page in a browser
Run npm test to ensure no regressions

5. Deployment

FineUploader is a client-side library. Deployment involves including the built JavaScript and CSS files in your web application.

Recommended Deployment Methods

A. Self-Hosted (Most Common)

After building, copy these files from _build/ to your project:
- fine-uploader.min.js (or .js for non-minified)
- fine-uploader-gallery.min.css (or other theme CSS)
Include in your HTML:

<link rel="stylesheet" href="/path/to/fine-uploader-gallery.min.css">
<script src="/path/to/fine-uploader.min.js"></script>

B. CDN (Quick Start)

FineUploader is available on CDNJS:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/fine-uploader/5.16.2/fine-uploader-gallery.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/fine-uploader/5.16.2/fine-uploader.min.js"></script>

(Check CDNJS for latest version)

C. npm + Bundler (Webpack/Rollup)

import 'fine-uploader/dist/fine-uploader-gallery.css';
import qq from 'fine-uploader';

Note: You may need to configure your bundler to handle CSS imports.

Server-Side Requirements

Your upload endpoint (/upload or cloud storage) must:

Accept POST requests with multipart/form-data
Return JSON responses with at least { "success": true } or { "success": false, "error": "message" }
For chunked uploads: handle qqpartindex, qqtotalparts, qqfilename parameters
For resumable uploads: persist chunk data and respond appropriately to ?retry requests

6. Troubleshooting

Common Issues & Solutions

CORS Errors (Especially with S3/Azure)

Symptom: Browser blocks requests with CORS errors.

Solution: Configure CORS on your storage bucket/container.

S3 Example CORS:

<CORSConfiguration>
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <AllowedMethod>POST</AllowedMethod>
        <AllowedMethod>PUT</AllowedMethod>
        <MaxAgeSeconds>3000</MaxAgeSeconds>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
</CORSConfiguration>

Azure: Set CORS rules in Azure Portal under "Blob service" → "CORS".

S3 Signature Issues

Symptom: 403 Forbidden, "SignatureDoesNotMatch" error.
Solution:
- Ensure clock synchronization (drift option in signatureSpec)
- Verify region matches your bucket's region
- For v4 signatures, check that all required headers are included
- See client/js/s3/request-signer.js for signature generation details

Thumbnail Generation Fails

Symptom: Image previews don't appear, "waitingForThumbnail" placeholder persists.
Solution:
- Check browser console for errors (CORS, MIME type)
- Ensure imageGenerator is properly configured if using server-side scaling
- Verify thumbnail.maxSize setting (default: large images may be skipped)
- For IE: The library includes a polyfill for Uint8ClampedArray (see client/js/util.js), but very old IE may still fail.

Chunking/Resume Not Working

Symptom: Large files fail or don't resume after interruption.
Solution:
- Server must persist chunk data between requests (store in temp directory)
- Server must respond correctly to ?retry queries with existing chunk info
- Check qqtotalparts and qqpartindex parameters are being received
- Ensure chunking option is enabled in client config

UI Not Updating / Template Issues

Symptom: File items don't appear in the list.
Solution:
- Verify template element exists (qq-template by default) or provide custom templateIdOrEl
- Check browser console for JavaScript errors in client/js/templating.js
- Ensure containerEl and fileContainerEl are correctly set if using custom DOM structure

Build Failures

Symptom: make build fails with errors.
Solution:
- Ensure Node.js and npm are properly installed (node --version, npm --version)
- Delete node_modules and run npm install again
- Verify GNU Make is available (make --version)
- Some Make recipes require specific environment variables; run make without targets to see available recipes

Debugging Tips

Enable logging in FineUploader options:

var uploader = new qq.FineUploader({
    request: { endpoint: '/upload' },
    callbacks: {
        onComplete: function(id, name, response) {
            console.log('Complete:', id, name, response);
        }
    }
});

Check network tab in browser DevTools for failed requests.
For S3/Azure, verify credentials have correct permissions (write access to bucket/container).
Test with a simple local endpoint first before configuring cloud storage.

Note: As an unmaintained project, no new features or fixes will be released. Consider migrating to actively maintained alternatives for new projects.