ConvertX: A Self-Hosted Converter That Wraps Twenty-Two Converters Behind One Web App

What ConvertX Actually Solves

The project is written in TypeScript and runs on Bun with the Elysia framework, which is a modern stack but also a signal that the project is young and may have a smaller ecosystem than a Node.js or Python alternative. The core value is the aggregation: instead of installing and scripting twenty-two separate converters, you get one container that exposes them all. That is the problem it solves, and it solves it well for a single-user or small-team scenario.

The Converter Stack: Twenty Tools, One Container

The README lists twenty-two converters, each with a table of input and output counts. The counts are indicative, not exhaustive: FFmpeg alone is listed as converting from about 472 formats to about 199, and the note says many FFmpeg file formats are duplicates. That means the actual format coverage is less than the sum of the numbers, but the range is still broad. The tool selection reveals design choices: Inkscape and dvisvgm handle vector images, libjxl and libheif cover modern image codecs, Calibre manages e-books, and LibreOffice and Pandoc cover documents. There is also Assimp for 3D assets, which is an unusual inclusion and shows the author aimed for breadth. The use of Dasel for data files (like JSON to YAML) and a VCF to CSV converter for contacts shows attention to non-media formats. The key point is that ConvertX mostly orchestrates external tools, which the Dockerfile installs into the image. This means the quality of output depends on the underlying tools, and the format coverage is only as good as those tools' support. For example, converting a complex PDF to DOCX via LibreOffice will inherit LibreOffice's rendering fidelity, which can be imperfect.

Deployment: Docker First, with a Security Warning

The primary deployment method is Docker Compose. The README provides a minimal docker-compose.yml that pulls the image ghcr.io/c4illin/convertx, maps port 3000, and mounts a data volume to /app/data. The environment variables are all optional, but JWT_SECRET is recommended. If unset, the server generates a random UUID, which means tokens will invalidate on restart, breaking sessions. The warning about login is explicit: if you cannot log in, ensure you are accessing over localhost or HTTPS, or set HTTP_ALLOWED=true. That is a realistic constraint: the server refuses to issue tokens over plain HTTP except on localhost. For a home server behind a reverse proxy, you will need to either configure HTTPS or set that flag. The README also warns about first account registration: anyone can register the first account if the server is open, so you should deploy it and create your account immediately. There is also a note about database file permissions: if you get 'unable to open database file', run chown -R $USER:$USER on the volume path. These details are practical and show that the project expects a technically comfortable user. The environment variables include ACCOUNT_REGISTRATION (default false), which means by default new users cannot sign up after the first account, and ALLOW_UNAUTHENTICATED (default false), which locks the service down. That is a sensible default for a private tool.

Configuration and Customization: FFmpeg Args and Webroot

Beyond the basic variables, ConvertX exposes FFMPEG_ARGS, which passes additional arguments to FFmpeg; the repository's compose file shows -hwaccel vulkan as an example. The WEBROOT variable allows serving the app under a subpath like /convertx, which is useful behind a reverse proxy that already serves other apps. HIDE_HISTORY hides the history page, which is a privacy feature for shared servers. The configuration surface is small: apart from FFmpeg, none of the variables in the compose file target an individual converter. That is a trade-off: the aggregation saves setup time but limits control.

Limitations and Failure Modes

The most obvious limitation is that ConvertX is a web service, not a batch processing tool. You upload files through a browser or an HTTP client, and the server processes them. If you need to convert thousands of files in a pipeline, this is not the right tool; you would be better off calling FFmpeg or Pandoc directly. The auto-delete feature is another potential failure mode: AUTO_DELETE_EVERY_N_HOURS checks every n hours for files older than n hours and deletes them, and the repository's compose file sets it to 1. If you convert a file and do not download the result in time, it is gone. The compose file says set to 0 to disable, but if you forget, you lose data. Multiple accounts are supported; for a shared deployment, check how uploads and disk space are bounded before opening it to other users. The license, AGPL-3.0, is a real constraint for commercial use: if you modify the code and offer it as a network service, you must provide the source to users. That is a common choice for self-hosted apps, but it may be a dealbreaker for companies that want to embed ConvertX in a proprietary product.

Alternatives: What Else Is Out There

The most direct alternative is to use the underlying tools directly, such as FFmpeg, ImageMagick, and LibreOffice, and script them with a simple web framework. That gives you full control over each converter's arguments and avoids the AGPL license, but it requires significant setup and maintenance. Another alternative is a commercial API like CloudConvert, which offers a REST API and handles scaling, but you lose the self-hosted aspect and pay per conversion. The key difference is that ConvertX bundles all tools into one Docker image, so you do not need to install dependencies. A more comparable project might be 'LibreOffice Online' for document conversions, but that is focused on office formats. For video, you could use 'FFmpeg.wasm' in a browser, but that is client-side and not suitable for large files. The practical choice is between ConvertX and a scripted solution: if you need a quick, deployable service, ConvertX wins; if you need custom logic or have unusual formats, you will hit its limits.

Maintenance and Upgrade Considerations

The project is actively maintained, with releases in October 2026 (v0.20.0), September 2026 (v0.19.0) and June 2026 (v0.18.0), indicating a steady cadence. The Docker image is published to GitHub Container Registry and Docker Hub, so updates are as simple as pulling a new image. Since the data volume stores files and likely a database, you should back it up before upgrading. The use of Bun and Elysia is a maintenance consideration: these are less established than Node.js and Express, so finding developers or documentation may be harder. The AGPL license also has implications for upgrades: if you modify the code, you must share those modifications if you run it as a service. The README encourages opening issues or pull requests for missing converters, which is a sign of an open contribution model. For a production deployment, you will need to monitor disk usage and the auto-delete behavior, and you should test the FFmpeg hardware acceleration settings if you plan to handle large videos. The project is not a turnkey enterprise solution; it is a solid tool for a technical user who understands the underlying converters.

Editorial conclusion

Adopt ConvertX if you need a self-hosted conversion service with a web UI, especially if you already run Docker and want to avoid per-file cloud uploads. Do not use it if you require fine-grained per-converter control, a mature multi-tenant user system, or a permissive license, because the AGPL-3.0 and the all-in-one container may conflict with your distribution model. Before deploying, verify that your expected formats are covered by the listed converters, set JWT_SECRET, and decide on ACCOUNT_REGISTRATION and ALLOW_UNAUTHENTICATED based on who will access it. Also test the AUTO_DELETE_EVERY_N_HOURS setting to ensure your workflow tolerates automatic file removal.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes