Custom Nodejs Upload Server

Image Upload Server – Secure, Fast, and Fully Customizable

This project is a custom-built Image Upload Server designed to provide secure, authenticated, and highly optimized delivery of user-generated images. It was built to support modern multi-tenant applications where each company or user has isolated upload permissions, safe storage, and real-time on-demand image transformations.

Core Features

Authenticated uploads using companyName + secret token.
Memory-based upload processing via multer.
Lossless and lossy optimization using sharp.
Dynamic transformations with URL parameters (resize, grayscale, invert, blur, quality, fit modes).
Automatic caching system for processed images.
Immutable cache headers for maximum performance (CDN-like behavior).
Per-company storage in isolated folders.

Technology Stack

Library / Tool	Purpose
Express.js	API server and routing
Multer (memoryStorage)	Handling file uploads directly from form-data
Sharp	Image optimization & transformation
Node.js FS & FS/Promises	File management and directory control
CORS	Cross-origin request support for external clients
MySQL (pool.query)	User validation and upload authentication

Authentication Logic

Every upload requires the company name as a URL parameter and a matching uploadServerSecret sent in form-data. The backend checks this against the database:

SELECT companyName, uploadServerSecret 
FROM users 
WHERE companyName = ? 
LIMIT 1;

Only if the provided secret matches, the image is accepted. Otherwise, the request is rejected with a professional 403 Forbidden response.

Upload Flow

Client sends multipart/form-data with the key image.
Server validates the company user via MySQL.
Original file is saved using its original extension.
The server logs the upload with timestamp, company name, and IP address.
API returns an accessible URL such as:
```
https://server.com/companyName/filename
```

Dynamic Image Transformations

The server can transform any uploaded image on the fly using URL parameters:

w - width
h – height
f – fit mode (cover, contain, fill, inside, outside)
grey – grayscale intensity
invert=1 – invert colors
blur – gaussian blur
q – quality level

Example request:

/company/image.webp?w=400&h=400&f=cover&grey=1&q=90

Automatic Caching System

Every unique transformation is saved inside:

/uploads/company/cache/

The next time the same parameters are requested, the server instantly returns the cached file:

Cache-Control: public, max-age=31536000, immutable

This makes the server extremely fast even with large images or heavy transformations.

Concurrency Safety

The system uses an in-memory promise map to prevent multiple requests from generating the same cache file simultaneously:

const generating = new Map();

This ensures:

No duplicated CPU work
No corrupted cache files
No race conditions

Folder Structure

/uploads
  /companyName
    original-image.png
    image-12345.jpg
    /cache
      transformed-image.webp

Use Cases

Profile images
CMS systems
Dashboard uploads
Portfolio image hosting
Multi-tenant SaaS applications

Final Thoughts

This upload server is lightweight, scalable, secure, and easy to integrate with any front-end or back-end application. It replaces third-party services like Cloudinary for projects that prefer full control, lower cost, or custom logic.

Work With Me

If you need a similar custom-built image upload server, or if you'd like to use this one as part of your system, I can develop or integrate it for you.

Contact me via my contact form