The two most important goals for us to accomplish while building our own homelab, is to save money on online services as well as protect our privacy by keeping our data at our own location, not the cloud. Something that most users need quite frequently is the ability to convert a file from one format to another. As an example, I have a video that was taken with a (fairly old) video recorder and the format is not a common format like MP4 or AVI. It would be easy to convert this video file online, but seeing as it includes a very special moment in the life of my child, I really don’t want to upload that file to a service that may or may not protect that privacy. Especially with a service that is free, and there are plenty online, one never knows what happens to your files. As such, keeping our data in our own hands is very important when it comes to converting files.
As another example, StirlingPDF can combine our PDF files, but what if we have a mixture of PDF files and image files? Let’s take a look at a tool that can help us convert files to another usable format while keeping our data local.
What is ConvertX?
ConvertX is an open-source, web-based application that allows you to perform a wide array of file conversions directly on your own server. Think of it as your personal, centralized conversion hub. No more uploading sensitive files to online converters or juggling multiple single-purpose desktop applications. With ConvertX, you host the power, ensuring privacy and convenience.
Its intuitive interface makes it easy to upload files and select your desired output format, putting powerful conversion capabilities at your fingertips.
Preview screen of ConvertX – Image Credit: https://github.com/C4illin/ConvertX
What Can You Do with ConvertX?
ConvertX aims to be a comprehensive solution for your conversion needs. At the time of writing, you can:
- Convert Images: Transform images between various formats, optimize them for web use, or prepare them for different devices.
- Convert Audio: Change audio file types, perhaps to a more universally compatible format or a compressed version to save space.
- Convert Video: Transcode video files, reduce their size, or change codecs for better compatibility with your media players.
- Convert Documents: Currently the project can convert a fair bit of documents, but also plans to incorporate more document conversion (via LibreOffice), which will further expand its utility.
- Convert Fonts: Change font file types to suit different operating systems or applications.
- Convert CAD Files: (Experimental) For those working with computer-aided design, ConvertX offers experimental support for CAD file conversions.
Essentially, ConvertX strives to eliminate the need for multiple, disparate conversion tools by offering a broad range of functionalities under one roof, and more conversions are on the way. ConvertX is still in an early stage, but the amazing contributors are doing a fantastic job of making ConvertX one of the first services any homelabber needs to install.
The Powerhouse Libraries Behind ConvertX
ConvertX leverages a suite of powerful, open-source libraries to perform its magic. Each library specializes in handling specific file types and conversion tasks:
- FFmpeg: This is the undisputed king of multimedia processing. FFmpeg is the backbone for audio and video conversions within ConvertX. It enables transcoding between a vast array of audio and video codecs and container formats. So, whether you need to turn a
.MOVinto an.mp4, or an.FLACinto an.mp3, FFmpeg is doing the heavy lifting. - Pandoc: (and upcoming LibreOffice) While not fully implemented for all document types yet, the integration of LibreOffice will enable ConvertX to handle even more document conversions. This will allow you to convert between formats like
.docx,.odt,.pdf, and others. - GraphicsMagick: A robust and feature-rich image manipulation toolkit, ImageMagick powers the image conversion capabilities of ConvertX. It allows you to convert between formats like JPEG, PNG, WEBP, GIF, TIFF, and many more. It can also handle resizing, compression, and other image processing tasks.
- libheif: libheif is an ISO/IEC 23008-12:2017 HEIF and AVIF (AV1 Image File Format) file format decoder and encoder. There is partial support for ISO/IEC 23008-12:2022 (2nd Edition) capabilities.
- Inkscape: With the ability to interpret vector graphics, Inkscape is a fantastic integration to convert to and from scalable graphics.
The Tech Stack: What Makes ConvertX Tick?
ConvertX is built with a modern and efficient technology stack:
- Frontend: Vue.js (specifically Vue 3) provides a reactive and user-friendly interface, making it easy to interact with the application. TypeScript is used for added type safety and improved developer experience. Vite serves as the fast build tool for the frontend.
- Backend: Node.js with Express.js forms the core of the backend, handling API requests, file processing, and communication with the conversion libraries. TypeScript is also used on the backend for consistency and robustness.
- Real-time Communication: Socket.IO is employed for real-time communication between the frontend and backend, providing instant feedback on conversion progress.
- Containerization: Docker is the recommended way to deploy ConvertX, simplifying installation and ensuring a consistent environment.
This combination of technologies results in a responsive, scalable, and maintainable application.
Getting Started: A Quick Rundown on Installing ConvertX
The developers of ConvertX primarily recommend installing it via Docker, which significantly simplifies the setup process. Here’s a general idea:
- Install Docker: If you don’t already have it, install Docker and Docker Compose on your server.
- Clone the Repository (Optional but Recommended for Customization):
git clone https://github.com/C4illin/ConvertX.gitcd ConvertX- Configuration (Important!): Before you can run ConvertX, you need to configure it. This is primarily done through a
.envfile (if building from source or customizing the Docker Compose) or by passing environment variables directly to your Docker run command. Key configurations include:
MAX_UPLOAD_SIZE: Sets the maximum size for uploaded files.
CONCURRENT_CONVERSIONS: Defines how many conversions can run simultaneously.
STORAGE_PATH: Specifies where uploaded and converted files will be stored.
JWT_SECRET: A secret key for securing communications.
DISABLE_AUTH: Allows you to disable authentication if running in a trusted environment (use with caution).
DEFAULT_USER_EMAIL / DEFAULT_USER_PASSWORD: If authentication is enabled, these set the initial admin credentials.- Using Docker Compose (Recommended): The
docker-compose.ymlfile provided in the repository is the easiest way to get ConvertX up and running.- Make sure you have configured your
.envfile in the same directory as thedocker-compose.yml.Then, simply run:
- Make sure you have configured your
docker-compose up -d- This command will pull the necessary Docker image (or build it if you’re working from a local clone and haven’t pulled the image) and start the ConvertX container in detached mode.
- Access ConvertX: Once the container is running, you should be able to access ConvertX by navigating to
http://your-server-ip:3000(or whichever port you’ve configured) in your web browser.
Always refer to the official ConvertX GitHub page for the most up-to-date and detailed installation instructions.
Tips for Running ConvertX in a Docker Container
- Volume Mapping for Persistent Storage: This is crucial. You’ll want to map a directory on your host machine to the
/app/storagedirectory (or your configuredSTORAGE_PATH) inside the Docker container. This ensures that your uploaded and converted files persist even if you stop or recreate the container. The provideddocker-compose.ymlusually handles this. Example snippet from adocker-compose.yml:
volumes: - ./data/convertx:/app/storage- Resource Allocation: File conversions, especially video, can be resource-intensive. Monitor the CPU and RAM usage of the ConvertX container. If you’re running other services on the same host, you might need to limit the resources available to the ConvertX container using Docker’s resource constraint options (e.g.,
cpus,mem_limitin yourdocker-compose.yml). - Port Configuration: Ensure the port mapped in your Docker configuration (e.g.,
3000:3000) is not already in use on your host system. If it is, change the host port (the first number inhost_port:container_port). - Reverse Proxy: For easier access (e.g., using a domain name) and to enable HTTPS, consider setting up a reverse proxy like Nginx Proxy Manager, Traefik, or Caddy in front of ConvertX. This also allows you to handle SSL termination at the proxy level.
- Check Logs: If you encounter issues, the first place to look is the container logs: Bash
docker logs <your_convertx_container_name_or_id> - Updating ConvertX: There are a few ways of keeping ConvertX up to date, to ensure that it always has the most conversion libraries. Our recommended way is to use WatchTower, as with the full tutorial.
Conclusion: Take Control of Your Conversions
ConvertX is a promising and valuable tool for any self-hoster dealing with diverse file formats. Its ability to bring a wide range of conversion capabilities under a single, self-hosted roof is a significant advantage for privacy, convenience, and control. By leveraging powerful open-source libraries and a modern tech stack, ConvertX offers a user-friendly way to tackle your image, audio, video, font, and (soon) document conversion needs.
While still under active development with features like CAD conversion being experimental and document conversion on the horizon, ConvertX is already a potent application. Give it a try, set it up in Docker, and simplify your self-hosted file management workflow!