Self-host a file converter with HRConvert2
Run HRConvert2 on your own VPS so client files never touch a free converter site. Docker or Apache install, bubblewrap sandboxing, upload limits and cleanup.
Why self-host a file converter
A self-hosted file converter keeps the file on your own disk. That is the entire reason to run one. A free converter site takes the upload and gives you no way to know what happened to it afterwards, and when the file is a signed client contract or a scanned medical record, the upload itself is the incident. HRConvert2 is a drag and drop file conversion server written in PHP and licensed under the GPLv3. This guide was written against version 3.7.4, released on 18 August 2026. The project has moved fast since then: the newest release as of 8 November 2026 is v4.0.0, published on 6 November 2026, and the project claims over 490 supported formats. That release includes security fixes, so review it before exposing an older installation.
It has no database, no accounts and no cookies. A user is a temporary directory. Every conversion is a local command line tool doing the work: LibreOffice for documents, FFmpeg for audio and video, ImageMagick for images, Tesseract for optical character recognition (OCR), and a long tail of smaller tools behind the rest. HRConvert2 is the upload page, the pipeline and the cleanup around them.
It converts a file from one format to another. It is not a browser office suite, so if what you want is people editing documents in a tab, compare self-hosted OnlyOffice and Collabora instead. It is also not storage. Converted output is meant to be deleted, so if files need to live somewhere, that job belongs to a self-hosted file manager.
What it needs
Debian or Ubuntu, Apache 2.4, PHP 8 or later, and bubblewrap. Bubblewrap (bwrap) is the sandbox: with $RequireSandbox = TRUE, the v3.7.4 manual installation refuses conversions that need a sandbox when it cannot build one. Document conversions use a persistent listener outside that sandbox. The upstream README says a Raspberry Pi Model B+ is enough, which is true of the PHP part. The converter binaries set your real hardware budget, and that is covered further down.
There are two ways in. The Docker image works tonight. The Apache and PHP install takes an evening and shows you exactly what is on the box.
Run it tonight with Docker
The image ships every converter binary, so it is large: about 3 GB compressed for the pinned amd64 image. Check free disk before you pull.
Tags matter here. This guide pins v3.7.2. v3.7.4 followed on 18 August. As of 8 November 2026 the newest GitHub release is v4.0.0 (6 November 2026), and Docker Hub's latest tag points to the same images as v4.0.0. The latest tag moves under you, and this application is a large parser surface, so pin a version and upgrade on purpose.
docker pull zelon88/hrconvert2:v3.7.2
docker run -d --name hrconvert2 \
-p 127.0.0.1:8080:80 \
--security-opt seccomp=unconfined \
zelon88/hrconvert2:v3.7.2docker ps
curl -I http://127.0.0.1:8080/A healthy container stays in Up state and the curl returns HTTP/1.1 200 OK. A container that keeps restarting has a startup problem, so read docker logs hrconvert2 before changing anything else.
Two flags carry weight. -p 127.0.0.1:8080:80 publishes the port on the host's loopback address, so the Docker host can reach the converter directly without a proxy. Docker releases older than 28.0.0 also allow hosts on the same L2 segment, such as the same network switch, to reach ports published to localhost. Use Docker 28.0.0 or later before relying on that binding for external isolation. The project's current example maps -p 8080:80, which listens on every interface, including the public one. --security-opt seccomp=unconfined is there because bubblewrap builds its sandbox using user namespace and mount system calls that Docker's default seccomp profile blocks. The 3.7 config.php comments add that some hosts also need --security-opt apparmor=unconfined. Without the flags, the container cannot build the sandbox; whether affected conversions fail depends on $RequireSandboxOnDocker.
That flag is a real trade. You relax the container's syscall filter so the application can build its own tighter sandbox inside it. The two settings that decide the behaviour are $RequireSandbox and $RequireSandboxOnDocker in Resources/config.php. The v3.7.4 release ships them as TRUE and FALSE. The v3.7.2 tag pinned here ships both as FALSE, because its comments say a container must leave $RequireSandbox off and let $RequireSandboxOnDocker decide. Because the Docker requirement is off by default, a container without the seccomp flag can convert with no sandbox at all. Once the flag is in place, set $RequireSandboxOnDocker = TRUE; to refuse conversions that require an unavailable sandbox. This does not sandbox the 3.7 document listener.
Newer images start differently. The project changed its Docker process in v3.8.0 (25 August 2026). Its current README and Docker Hub page run the container with --cap-add SYS_ADMIN instead of the seccomp option and state that conversions are refused without it. If you move your pin to a newer tag, use the flags that image documents. That capability is broad, so keep the 127.0.0.1 port binding.
If Docker is new on this machine, set the daemon up first. Running Docker on a VPS covers the install, the storage driver and the way Docker writes its own firewall rules.
Install it on Apache and PHP instead
Up to v3.7.4, the file Documentation/INSTALLATION_INSTRUCTIONS.txt in the repository laid this out as a manual install in nine steps, and this section follows that install. Since v3.8.0 the same file describes a setup script instead. Run sudo bash Documentation/Build/hrconvert2-setup.sh from the cloned repository and it installs the dependencies, writes the PHP settings as a drop in file instead of editing php.ini, and installs an application-specific AppArmor profile for its own copy of bubblewrap. Then php convertCore.php -v and sudo php convertCore.php --status verify the result. The manual route takes longer, and you know exactly what it put on the box. This is the shape of it. Start with the web server, the language and the sandbox:
sudo apt update
sudo apt install -y apache2 php libapache2-mod-php php-all-dev php8.3-zip php8.3-gd bubblewrapThe php8.3-* names match Ubuntu 24.04. Run php -v and use the prefix that matches your version, because those package names change with every PHP release and the wrong one gives you Unable to locate package.
Then the converters. This covers documents, images, audio, video and OCR, which is most of what people actually convert:
sudo apt install -y imagemagick ffmpeg libreoffice-common libreoffice-java-common \
default-jre ghostscript poppler-utils libgxps-utils tesseract-ocr inkscape \
xvfb clamav curl tar libxcb-cursor0Archive formats, 3D models, ebooks and bootable ISO images need more packages than this, and some of them live in Ubuntu's multiverse component. At v3.7.4, Step 3 of the official instructions carried the full apt list and Step 5 the source builds. The current guide has no package lists. The installer reads the manifest Resources/Contract/depends.php, and php convertCore.php --setup --check-depends prints the current list and its state. Two dependencies can also be built from source. The repository ships Documentation/Build/ffmpeg-build.sh for encoders that the packaged FFmpeg lacks, and Documentation/Build/build-imagemagick-v7.sh for ImageMagick 7 on Ubuntu 22.04 or 24.04, which still package the 6.9 branch. Ubuntu 25.10 and 26.04 LTS package ImageMagick 7.1. Ebook support comes from calibre's own installer, which the 3.7 instructions gave as one line:
sudo -v && wget -nv -O- https://download.calibre-ebook.com/linux-installer.sh | sudo sh /dev/stdinThat is a vendor script piped into a shell as root. It is the upstream method, and it is optional: skip it and ebook conversion is the only thing you lose.
Next, PHP's limits. Conversions are slow and files are big, so the stock values are too small. The 3.7 instructions set these in php.ini:
max_execution_time = 1200
max_input_time = 90
memory_limit = 512M
post_max_size = 5000M
upload_max_filesize = 5000M
max_file_uploads = 100
display_errors = Off
zlib.output_compression = OnThose numbers assume a machine with room. Lower them before you go anywhere near a small VPS. post_max_size = 5000M caps the entire POST body at approximately 4.88 GiB, including all uploaded files and form overhead; max_file_uploads = 100 does not multiply that allowance. Concurrent requests, temporary files and conversion output still need additional disk space. Restart Apache and inspect the command line PHP settings; Apache can load a different configuration:
sudo service apache2 restart
php -i | grep -E "upload_max_filesize|post_max_size|memory_limit"Now the working directory. $ConvertLoc in Resources/config.php names it, and the default is /DATA/HRConvert2. The web server user has to own it:
sudo mkdir -p /DATA/HRConvert2
sudo chmod -R 0755 /DATA/HRConvert2
sudo chown -R www-data:www-data /DATA/HRConvert2Unpack the release under your Apache document root. The default layout puts it in a HRProprietary/HRConvert2 folder, and $InstLoc in Resources/config.php has to name wherever you actually put it. Then run the built in diagnostic, which is the fastest way to find a missing dependency before a user does:
sudo php /path/to/HRConvert2/convertCore.php -v-v walks the whole install: core versions, dependency checks, sandbox status and language packs. File conversions are not supported from the command line, so this argument set is administrative only.
Why does every conversion fail on a fresh Ubuntu 24.04 install?
Ubuntu 24.04 restricts unprivileged user namespaces by default through AppArmor. Bubblewrap needs a user namespace to build its sandbox, so a blocked bwrap causes conversions that require it to fail. In v3.7.4, document conversions use a persistent listener outside that sandbox and are exempt from this requirement.
Check it directly:
bwrap --ro-bind / / --dev /dev /bin/true && echo sandbox okA permission denied error means the namespace was blocked. The fix is an AppArmor profile for the bwrap binary. First list the ABI files and note the highest number present:
ls /etc/apparmor.d/abi/Then write /etc/apparmor.d/bwrap, replacing 4.0 with that highest number:
abi <abi/4.0>,
include <tunables/global>
profile bwrap /usr/bin/bwrap flags=(unconfined) {
userns,
include if exists <local/bwrap>
}Load it:
sudo apparmor_parser -r /etc/apparmor.d/bwrapNo output means the profile loaded. Run the bwrap check again and it should print sandbox ok. Conversions work from that point.
Debian 12 does not have this problem. Its kernel permits unprivileged user namespaces, and the bubblewrap package sets kernel.unprivileged_userns_clone to 1 at boot, so the check above passes there without a profile. The current setup script installs an application-specific AppArmor profile for its own copy of bubblewrap.
A public converter is a parser exposed to strangers
This is the section the rest of the post exists for. A file converter reachable from the internet accepts an arbitrary file from an anonymous person and hands it to LibreOffice, ImageMagick, FFmpeg or Ghostscript. Those are large C and C++ codebases with a long history of parser bugs. The person uploading picks the format, which means the person uploading picks which parser runs and which code path inside it.
HRConvert2 v3.7.4 sandboxes Tesseract, pdftotext, ImageMagick and other conversion tools, but its document conversion engine uses a persistent LibreOffice listener outside that sandbox. Sandboxed commands receive a read only input directory and a writable output directory; when both files share a directory, that directory is mounted writable. Network access is unshared unless the caller explicitly enables it. That matters more than it sounds. ImageMagick and Ghostscript both accept references that fetch a URL, which is how a converter turns into a server side request forgery (SSRF) tool for reaching a cloud metadata endpoint from inside your network. With no network in the namespace, the fetch cannot happen.
The refusal is the other half: with sandboxing required, a server that cannot build a sandbox refuses conversions that depend on it. Document conversions are exempt in the versions pinned here. It is also why the AppArmor step above is not optional, and why $RequireSandboxOnDocker deserves a look before you expose the container.
Harden ImageMagick with policy.xml
ImageMagick's own policy file is a second layer under the sandbox, and it is worth setting. On Ubuntu 24.04 with ImageMagick 6 the file is /etc/ImageMagick-6/policy.xml. Print what is currently active:
identify -list policyThe project ships a policy at Documentation/Build/policy.xml and it is a good model. It denies the PS, PS2, PS3, EPS, XPS and MVG coders, and it denies the URL, HTTPS, HTTP and gs delegates, while allowing PDF:
<policy domain="coder" rights="none" pattern="PS" />
<policy domain="coder" rights="none" pattern="MVG" />
<policy domain="delegate" rights="none" pattern="URL" />
<policy domain="delegate" rights="none" pattern="gs" />
<policy domain="coder" rights="read|write" pattern="PDF" />The gs line is the important one. ImageMagick does not parse PostScript itself. It shells out to Ghostscript. Denying that delegate also prevents standard PDF to image conversions that need Ghostscript, even when the PDF coder is allowed.
The same policy sets resource caps, which is how one crafted image is stopped from eating the machine:
<policy domain="resource" name="memory" value="256MiB"/>
<policy domain="resource" name="map" value="512MiB"/>
<policy domain="resource" name="disk" value="1GiB"/>
<policy domain="resource" name="width" value="16KP"/>
<policy domain="resource" name="height" value="16KP"/>
<policy domain="resource" name="area" value="128MP"/>A decompression bomb is a tiny file that declares enormous dimensions. The width and height limits reject images that exceed those dimensions. The area limit controls how much image area is cached in memory; larger images use disk cache instead of being rejected solely for exceeding it.
There is a trap in the other direction. If the active policy denies the PDF coder outright, PDF work fails with attempt to perform an operation not allowed by the security policy 'PDF'. That string is the policy doing its job. Allowing the coder back is a decision you make deliberately, and you keep the gs delegate denied when you do.
What the dependency chain costs on a small VPS
Idle, none of this is expensive. The document listener can remain running between conversions, so the converter binaries are not all absent at idle. The main cost arrives when a file lands.
A document conversion uses LibreOffice through the persistent listener. An image conversion has pixel cache limits of 256 MiB of memory and a 512 MiB memory map under the policy above; those are caps, not fixed allocations. FFmpeg's video thread count depends on the codec and its support for multithreading. PHP's own memory_limit is 512M in the project's configuration. Those numbers stack during a single job, on top of the operating system and the web server.
Avoid a 1 GB VPS for document conversions. Check for an out of memory kill after the fact with dmesg -T | grep -i "killed process".
This is sizing guidance rather than a benchmark: 4 GB of RAM and two cores is comfortable for a small team, and 2 GB with a swap file works if the load is documents and images and you accept the wait. A swap file does not make a conversion faster. It makes a burst slow instead of fatal, which is the difference between a stalled page and an outage. Give the disk more room than feels necessary, because the 3 GB image, a large upload limit and the converted output together fill a disk long before you run out of anything else.
Conversions are bursty by nature. Two people uploading video at the same moment compete for CPU with each other and with other requests. There is no job queue in front of this in v3.7.4, so the only control you have is limits.
Set the limits that stop one upload from filling the disk
Cut the PHP values first. Something like upload_max_filesize = 512M, post_max_size = 512M and max_file_uploads = 20 is a sane starting point for a shared 4 GB box. The POST limit includes all files and multipart overhead, so an individual file must fit below it. max_execution_time = 1200 sets a twenty minute script execution limit, not an upload timeout; in a standard non ZTS PHP build on Linux, time spent in external conversion commands is excluded too. The v3.7.4 core also calls set_time_limit(0), removing that execution limit. Input processing and web server timeouts are separate controls.
Then enforce size and rate at the proxy, before the request ever reaches PHP:
limit_req_zone $binary_remote_addr zone=convert:10m rate=6r/m;
server {
listen 443 ssl;
server_name convert.example.com;
client_max_body_size 512M;
client_body_timeout 300s;
location / {
limit_req zone=convert burst=4 nodelay;
proxy_pass http://127.0.0.1:8080;
proxy_read_timeout 1200s;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}client_max_body_size limits the entire request body, including multipart overhead, so leave room above the biggest file you want converted or nginx answers 413 Request Entity Too Large and PHP never sees the upload. proxy_read_timeout must accommodate the longest interval without upstream response data. A conversion that sends data periodically can run longer than that timeout in total; a silent upstream that exceeds it loses the connection. client_body_timeout likewise measures the interval between reads of the request body, not the total upload duration. The rest of that server block, including TLS (transport layer security) termination, is covered in an nginx reverse proxy config explained line by line.
Delete the converted files
Every conversion leaves a copy of a sensitive file in a directory the web server can read. Cleanup is what separates a converter from an archive of everything anyone has ever converted on it.
$DeleteThreshold in Resources/config.php is the age in minutes at which a session expires, and it defaults to 60. Lower it to 15 when the content is sensitive. The sweep itself is a command line argument on the core, and the v3.7.4 implementation requires root:
sudo php /path/to/HRConvert2/convertCore.php -c
sudo php /path/to/HRConvert2/convertCore.php -c=15-c clears expired sessions from both data locations using the configured threshold. -c=15 uses fifteen minutes for that run only. -c=now deletes every session regardless of age, including the one a user is converting at that moment, so keep it for maintenance. The same arguments work inside the container through docker exec.
Put the sweep on a timer so that cleanup never depends on someone loading a page. A line in /etc/cron.d/hrconvert2 is enough:
*/10 * * * * root php /path/to/HRConvert2/convertCore.php -cCheck it a few minutes later with ls /DATA/HRConvert2 and watch old session directories disappear. Because the web server user owns that directory, that account is exactly what an exploited parser would get, so it should own nothing else worth having. Least privilege user accounts on a VPS is the general pattern, and it applies here more than usual.
Put it behind authentication unless public is the goal
The default install has no accounts, by design. Anyone who can reach the page can upload a file and run your converter binaries, and rate limits only slow that down. So decide which situation you are in.
If it is for you and a few colleagues, do not expose it at all. Bind the container to loopback as shown above and reach it over a private network or an SSH tunnel. With Docker 28.0.0 or later and no public proxy, that loopback publication keeps remote hosts from reaching the converter directly. If those colleagues need to open it in a browser without you publishing a hostname or opening a port, serving it as a v3 onion service keeps the converter bound to loopback and still gives them an address to visit.
If it has to be reachable from a browser, put authentication in front of the proxy. Basic auth is two commands and it keeps the upload form away from strangers:
sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd alicelocation / {
auth_basic "Converter";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8080;
}Reload nginx and load the page. A prompt means it is working, and no prompt means the location block you edited is not the one handling the request. For real accounts rather than a shared password, terminate at a single sign-on provider: a self-hosted Authentik SSO server gives you forward authentication in front of an application that has no login of its own.
If a genuinely public converter is the goal, then accept what that means and plan for it. Assume the sandbox will be probed. Keep the image tag pinned, keep the ImageMagick policy tight, keep the upload limits small, and run it on a VPS that holds nothing else you care about.
Failure modes and the strings you will see
Conversions that require a sandbox fail immediately. The sandbox cannot be built. On Ubuntu 24.04, check the AppArmor profile. In the pinned 3.7 Docker image, check --security-opt seccomp=unconfined and, where needed, --security-opt apparmor=unconfined. Refusal depends on $RequireSandbox or $RequireSandboxOnDocker; the pinned container defaults to allowing unsandboxed conversions. Document conversions are exempt from the sandbox requirement in these versions.
Only image conversions fail. Bubblewrap is missing or non functional, so this image conversion cannot be isolated! means bwrap is absent or not reachable on the path the web server user has.
One format fails and the rest work. A missing binary, reported plainly: ImageMagick may not be installed, or may not be reachable on the system path used by the web server user. The same message exists for FFmpeg and for LibreOffice. Run convertCore.php -v to see what the install can find, and remember that the Apache worker's PATH is not your login shell's PATH.
PDF work fails with a policy error. attempt to perform an operation not allowed by the security policy 'PDF' comes from ImageMagick's policy.xml, not from HRConvert2.
Large uploads return 413. nginx client_max_body_size is smaller than the request body. There are three limits in the chain, one in nginx and two in PHP, and the smallest one wins.
Conversions stop and nothing obvious changed. The device where data is stored has an insufficient amount of storage space available. Check free space and check that the cleanup sweep is actually running.
Cleanup complains in the log. Could not clean the temporary location! and Could not clean the convert location! indicate a path or permissions problem. Check both the temporary location and $ConvertLoc; the web server user needs read and write access to them.
FAQ
Is it safe to expose a self-hosted file converter to the internet?
It is safe enough only if you treat it as a parser exposed to strangers. Every upload is handed to LibreOffice, ImageMagick, FFmpeg or Ghostscript, and the person uploading chooses which one. In v3.7.4, bubblewrap isolates many conversion tools, but the persistent document listener runs outside that sandbox. Requiring sandboxing refuses affected conversions when isolation is unavailable; it does not cover the document listener. It is still better to require authentication, keep upload limits small, and run it on a VPS that holds nothing else of value.
Why does every conversion fail on a fresh Ubuntu 24.04 install?
Ubuntu 24.04 restricts unprivileged user namespaces through AppArmor, and bubblewrap needs one to build its sandbox. Conversions that require it fail when it cannot start; v3.7.4 document conversions are exempt. Write an AppArmor profile for /usr/bin/bwrap with flags=(unconfined), load it with sudo apparmor_parser -r /etc/apparmor.d/bwrap, then confirm with bwrap --ro-bind / / --dev /dev /bin/true. Debian 12 permits unprivileged user namespaces by default and does not need this step.
Why do conversions fail in Docker but work on a normal install?
Docker's default seccomp profile blocks the system calls bubblewrap uses, so the sandbox cannot be created inside the container. For the 3.7 image pinned here, start it with --security-opt seccomp=unconfined, which is what that release's config.php comments prescribe. From v3.8.0 the project documents --cap-add SYS_ADMIN instead. Note that $RequireSandboxOnDocker is FALSE by default in the pinned 3.7 image, so an unflagged container may convert with no sandbox at all. Set it to TRUE once the seccomp flag is in place.
How much RAM does a file conversion server need?
Idle it is small, but a live conversion is not. LibreOffice uses a persistent listener, ImageMagick's pixel cache is capped at 256 MiB of memory and a 512 MiB map under the shipped policy, and PHP's own limit is 512M. Those limits are not fixed allocations or a benchmark for total memory use. Plan on 4 GB and two cores for a small team, and check dmesg -T | grep -i "killed process" whenever a conversion dies without a message.
Where do converted files go, and when are they deleted?
They go to the working directory named by $ConvertLoc in Resources/config.php, which defaults to /DATA/HRConvert2. $DeleteThreshold sets the age in minutes at which a session expires, and it defaults to 60. The sweep runs from the command line as root: sudo php convertCore.php -c clears expired sessions, and -c=now clears every session immediately, including active ones. Put -c on a root cron entry or a systemd timer so that deletion does not depend on anyone visiting the site.