DEV Community

Fernando Paladini
Fernando Paladini

Posted on

Run Private PDF and Image Conversions with I Love Open Converter

If you regularly upload PDFs or images to an online converter, you are making a trust decision before you even choose a format. The file may contain invoices, scans, screenshots, or personal documents. A self-hosted converter gives you a different tradeoff: you operate the service, keep the files on your own server, and accept responsibility for access control and maintenance.

I Love Open Converter is a small open-source web application for local PDF and image operations. Its stable v0.1.0 release runs as two Docker Compose services: a FastAPI web service and a background worker. This tutorial deploys that release, exercises the supported workflow, and explains what the project does not protect you from.

TL;DR

Use Docker Compose to run ghcr.io/paladini/i-love-open-converter:v0.1.0, open the local web interface on port 8080, and upload an unencrypted PDF or a supported static image. The application queues the job, processes it on the server, and exposes the result for download. It has no built-in authentication, so keep it on a trusted network or place it behind a VPN and an authenticated reverse proxy.

Prerequisites

You need:

  • Docker Engine and Docker Compose v2.
  • A machine where you can create a persistent data directory.
  • A supported input file: JPEG, PNG, WebP, BMP, TIFF, or an unencrypted PDF.
  • A network plan. The default service is not suitable for direct public exposure.

The release currently documents Python 3.14 and uv for development, but Docker users do not need to install Python locally. The commands below use the published v0.1.0 image instead of the mutable latest tag.

Deploy the stable release

Clone the repository and switch the image to the stable release through .env:

git clone https://github.com/paladini/i-love-open-converter.git
cd i-love-open-converter
cp .env.example .env
mkdir -p data
printf 'IMAGE_TAG=v0.1.0\n' >> .env
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

On Windows PowerShell, the equivalent setup is:

git clone https://github.com/paladini/i-love-open-converter.git
Set-Location i-love-open-converter
Copy-Item .env.example .env
Add-Content .env "IMAGE_TAG=v0.1.0"
New-Item -ItemType Directory -Force data
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

The release's Compose file starts web and worker from the same image. The web service exposes port 8080, while the worker consumes queued jobs. Both services mount ./data at /data, which is where the SQLite database, job files, and results are stored.

Check that both containers are healthy:

docker compose ps
docker compose logs --tail=50 web worker
Enter fullscreen mode Exit fullscreen mode

Then open http://localhost:8080. The home page separates the available image and PDF operations from catalog entries marked as coming soon.

Try a complete local conversion

Choose an available operation, upload a file, and submit the job. The browser sends the file to your local web service. The API validates the input and creates a queued job in SQLite. The worker claims the job, writes the result under the data directory, and the browser polls for completion.

The release supports these image operations:

  • Convert JPEG, PNG, WebP, BMP, and TIFF images to JPEG, PNG, or WebP.
  • Resize by width, height, or both while preserving the aspect ratio.
  • Compress JPEG and WebP output with a quality setting.
  • Rotate an image by 90, 180, or 270 degrees.

For PDFs, the available operations include merge, split by page ranges, rotation, lossless structural optimization, PDF-to-JPG rendering, images-to-PDF conversion, text or image watermarks, and page numbers. PDF inputs must be unencrypted. Multi-file operations can return a ZIP archive.

To test the service without relying on the browser, first confirm the health endpoint:

curl -fsS http://localhost:8080/healthz
Enter fullscreen mode Exit fullscreen mode

An available service returns a small JSON object with a healthy status. For a real conversion, use the web interface so the operation-specific options match the current UI. This also makes it easy to inspect the generated download and confirm that the output format matches the selected operation.

Verify limits and persistence

The default configuration has three upload limits: 100 MB per file, 500 MB total per request, and 10 files per job. Completed and failed jobs are retained for 24 hours by default. These values come from .env.example and can be changed before starting the containers:

MAX_FILE_SIZE_MB=200
MAX_TOTAL_UPLOAD_MB=800
MAX_FILES_PER_JOB=20
JOB_RETENTION_HOURS=48
Enter fullscreen mode Exit fullscreen mode

Restart the stack after changing environment values:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

The important persistence check is simple: stop and start the containers, then confirm that the data directory still exists and contains the application state. Use docker compose down when you want to stop the services without deleting that directory. Back up data if the results or queue history matter to you.

For a reproducible project-level verification, check out the release and run its documented development checks. The tagged source uses Python 3.14 and uv:

uv sync --all-groups
uv run pytest
uv run ruff check .
uv run ruff format --check .
Enter fullscreen mode Exit fullscreen mode

These checks validate the source tree. They do not prove that your production host is secure, that Docker storage is backed up, or that an external reverse proxy is configured correctly.

Why the architecture works

The separation between web and worker keeps upload handling separate from CPU-heavy conversion work. FastAPI validates the multipart request and creates a job. SQLite provides a local queue. The worker reads the job, uses Pillow for image operations and PyMuPDF for PDF operations, then stores the result in the job directory.

This design is useful for a home server because it has a small operational footprint and does not require a hosted database. It also creates clear boundaries: the web process accepts input and exposes job status, while the worker handles the conversion. The Compose file drops all Linux capabilities and enables no-new-privileges for both containers, which reduces container privileges but is not a complete sandbox.

Failure modes and security boundaries

If a container is running but a job never finishes, inspect both service logs. The worker must be running and must be able to read and write the shared data mount. Permission mismatches are common when the configured PUID and PGID do not own the host directory.

If a file is rejected, check its format and size first. Encrypted PDFs are outside the documented input boundary. Unsupported image formats, invalid options, oversized files, oversized requests, and too many files are rejected by the API rather than silently converted.

The most important limitation is authentication. The project has no user accounts or built-in access control. Anyone who can reach the web service can submit jobs and access a job if they know its URL. Job IDs are described as unpredictable, but they are not an authorization boundary. Run the service on a trusted network. For remote access, use a VPN or an authenticated reverse proxy, and do not publish port 8080 directly to the internet.

The project is licensed under AGPL-3.0. Review that license and the project's dependency information before redistributing a modified service or image.

FAQ

Does this upload files to a third-party service?

The documented deployment processes files on the server where you run the application. The Compose file uses a published image, but the conversion workload and mounted data directory are local to your host.

Can I use the latest image tag?

You can, but a release tag such as v0.1.0 is easier to reproduce. Change IMAGE_TAG deliberately when you want to upgrade.

Is it safe for a public internet deployment?

Not by itself. There is no built-in authentication. Add an authenticated access layer and limit network exposure before allowing remote users.

Does it support every tool shown on the home page?

No. The home page includes a broader catalog, and entries marked as coming soon are not available for processing in this release.

Takeaway

I Love Open Converter is a practical local conversion stack when your priority is keeping everyday PDF and image processing on infrastructure you control. Pin the release, persist the data directory, verify both services, and treat the missing authentication layer as a deployment requirement rather than a detail.

Have you found a good pattern for putting an unauthenticated self-hosted utility behind a VPN or authenticated reverse proxy without making local use cumbersome?

AI assistance disclosure

This tutorial was prepared with AI assistance. The repository documentation, release metadata, configuration, source, and tagged test suite were checked against the claims and commands before publication.

Top comments (0)