PDF File Service

Welcome to the PDF File Service! 🎉 Tired of clunky, restrictive PDF converters? That's exactly why I built this! This service is your fast, powerful, and reliable backend engine designed to tackle PDF-to-image conversion with zero hassle. It provides a simple, robust API for turning PDF documents into high-quality image ZIP archives, giving you the freedom to build beautiful, user-friendly interfaces on top. Let's get converting!

This is a Node.js/Express service designed for converting PDF files to images and zipping the results. It uses pdf-to-img for the conversion and node-cron for scheduled cleanup of temporary files. The application is configured to run efficiently within a Docker container.

Prerequisites

Before you begin, ensure you have the following tools ready to go on your system:

1. Docker: Your ticket to a smooth, consistent launch using our provided Dockerfile and Compose setup.
2. Docker Compose: The easy way to manage and run the service.
3. (Optional for Local Development): Node.js (version 22 or higher) and npm/yarn, if you plan to jump into the code.

Project Structure

./  
├── docker-compose.yaml  
├── Dockerfile
├── package.json
└── src/  
    ├── app.ts
    └── file.service.ts

Getting Started (Docker)

Setting up Docker:

The fastest and most reliable way to launch this powerhouse service is with Docker Compose. It handles everything from building the image to setting up the environment—you'll be up and running in moments!

• Visit official Docker site to get started:

  https://docs.docker.com/get-started/introduction/get-docker-desktop/

1. Build and Run the Container

Navigate to the root directory of the project (where docker-compose.yaml is located) and run this single command:

docker compose up \--build \-d

Command Segment	Purpose
docker compose up	Effortlessly starts the services defined in docker-compose.yaml.
--build	Ensures you're using the latest image by rebuilding it using the Dockerfile.
-d	Runs the container in detached mode (quietly in the background).

2. Verify Service Health

The service should now be running strong and accessible on your host machine via port 5000.

• Service Check: Note that the root path (http://localhost:5000) is not explicitly defined in app.ts and will return a default 404 Not Found. Head straight to the API endpoints below!
• Check container logs: If you need to peek inside, use

docker compose logs \-f pdf-express

3. Stopping the Service

When you're ready to shut things down, gracefully stop and remove the container, network, and image volumes with:

docker compose down

Local Development (Optional)

If you prefer to dive into the code and run the application directly on your host machine, follow these simple steps.

1. Install Dependencies

You'll need the global PDF utility and all project dependencies.

• Install global utility (pdf-to-img is essential for our conversion magic)

  npm i \-g pdf-to-img@latest

• Install project dependencies

  npm install

2. Start the Development Server

The dev script uses nodemon and ts-node to provide real-time compilation and automatic reloading as you code.

npm run dev

The server will be happily running at http://localhost:5000 and will restart automatically whenever you save changes in src.

3. Build for Production

To compile the TypeScript source code into clean JavaScript output in the dist directory:
npm run build

API Endpoints

The service provides powerful and flexible endpoints for handling both direct file uploads and remote PDF URLs. Get ready to integrate seamless conversion capabilities into your application!

Method	Endpoint	Description	Request Body	Response Status
POST	/api/upload-pdf	Upload & Convert. Easily accept a PDF file, convert each page to a high-res image (at 3x scale), zip the results, and streams the zip file back for immediate download.	multipart/form-data with key file (the PDF file)	200 (Direct Zip File Download), 400 (No file/Wrong type), 500 (Conversion failed)
POST	/api/pdf	Remote Download & Stream. Send a URL, and the service will efficiently fetch that content and streams it back to the client. The Content-Type is set to application/zip for the stream.	application/json with field url: string	200 (Direct File Stream), 500 (Download/Fetch failed)

Scheduled Cleanup

To keep the service running smoothly and manage disk space, a cron job is configured within src/app.ts to automatically clear all temporary files from the upload directory (src/uploads) and the results directory (src/results) on the first day of every month at midnight (UTC).

Key Configurations

File	Setting	Value	Notes
docker-compose.yaml	Host Port Mapping	5000:5000	Maps the container port to the host machine.
Dockerfile	Base Image	node:22	Uses a modern, stable Node.js environment.
Dockerfile	Installed Utility	pdf-to-img	The core dependency for reliable PDF conversion.
app.ts	Environment Vars	.env	The application loads configuration settings from a .env file using dotenv.
app.ts	Cron Schedule	* * 1 * *	Runs the cleanup service on the first of every month at midnight UTC.
file.service.ts	Image Scale	-s 3	Converts pages at 3x scale for outstanding, high-quality images.