![ConvertX]()
ConvertX
Container
File converter for over a thousand formats, covering images, documents, audio, video and ebooks. Source: https://github.com/C4illin/ConvertX
Image details
Source details
Configuration
TypeContainerlinuxghcr.io/c4illin/convertx:latest3000:3000/tcp/app/dataHTTP_ALLOWED=trueAUTO_DELETE_EVERY_N_HOURS=24TZ=UTCunless-stoppedTemplate by NotAFlightRisk
Report issueNotes
http://<your-host>:3000 and create your account straight away, since the first visitor gets it and sign-ups close after that. Uploads and the database live in the /app/data volume. It's a big image (LibreOffice, TeX and Calibre are all in there), so the first pull takes a while. You'll be logged out whenever the container restarts, unless you add a JWT_SECRET env var holding a long random string (openssl rand -hex 32). Docs: github.com/C4illin/ConvertXStandalone Install
Select an install method, to see config/commands for deploying ConvertX
Install on Portainer
Import all app templates into your Portainer instance, for easy 1-click deploys
- Ensure both Docker and Portainer are installed, and up-to-date
- Log into your Portainer web UI
- Under Settings → App Templates, paste the below URL
- Head to Home → App Templates, and the list of apps will show up
- Select ConvertX, fill in any config options, and hit Deploy
Template Import URL
https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me
More install options in our documentation, or see C4illin/ConvertX for app-specific guidance.
ConvertX
A self-hosted online file converter. Supports over a thousand different formats. Written with TypeScript, Bun and Elysia.
Features
- Convert files to different formats
- Process multiple files at once
- Password protection
- Multiple accounts
Converters supported
| Converter | Use case | Converts from | Converts to |
|---|---|---|---|
| Inkscape | Vector images | 7 | 17 |
| libjxl | JPEG XL | 11 | 11 |
| resvg | SVG | 1 | 1 |
| Vips | Images | 45 | 23 |
| libheif | HEIF | 2 | 4 |
| XeLaTeX | LaTeX | 1 | 1 |
| Calibre | E-books | 26 | 19 |
| LibreOffice | Documents | 41 | 22 |
| Dasel | Data Files | 5 | 4 |
| DjVuLibre | Documents | 2 | 2 |
| Pandoc | Documents | 43 | 65 |
| msgconvert | Outlook | 1 | 1 |
| VCF to CSV | Contacts | 1 | 1 |
| dvisvgm | Vector images | 4 | 2 |
| ImageMagick | Images | 245 | 183 |
| GraphicsMagick | Images | 167 | 130 |
| Assimp | 3D Assets | 77 | 23 |
| FFmpeg | Video | ~472 | ~199 |
| Potrace | Raster to vector | 4 | 11 |
| VTracer | Raster to vector | 8 | 1 |
| Markitdown | Documents | 6 | 1 |
| pdftops | Documents | 1 | 2 |
Any missing converter? Open an issue or pull request!
Deployment
!WARNING If you can't login, make sure you are accessing the service over localhost or https otherwise set HTTPALLOWED=true
# docker-compose.yml
services:
convertx:
image: ghcr.io/c4illin/convertx
container_name: convertx
restart: unless-stopped
ports:
- "3000:3000"
environment:
- PUID=1000 # user id for file permissions (should match your host user id)
- JWT_SECRET=aLongAndSecretStringUsedToSignTheJSONWebToken1234 # will use randomUUID() if unset
# - HTTP_ALLOWED=true # uncomment this if accessing it over a non-https connection
volumes:
- ./data:/app/dataor
docker run -p 3000:3000 -e PUID=1000 -e PGID=1000 -v ./data:/app/data ghcr.io/c4illin/convertxEnsure
PUID and PGID match your host user (id -u and id -g) to avoid permission issues on the mapped ./data volume. If you get unable to open database file, verify the directory permissions or run chown -R $USER:$USER path on the path you choose.Then visit
http://localhost:3000 in your browser and create your account. Don't leave it unconfigured and open, as anyone can register the first account.Environment variables
All are optional, JWTSECRET is recommended to be set.!WARNING Never expose the service to the internet with ALLOWUNAUTHENTICATED or ACCOUNTREGISTRATION true. Only allow users you trust to access the service.
| Name | Default | Description |
|---|---|---|
| JWTSECRET | when unset it will use the value from randomUUID() | A long and secret string used to sign the JSON Web Token |
| PUID | 0 (root) | User ID to run the application process as (it first uses root to chown the files) |
| PGID | PUID if unset, root if both unset | Group ID to run the application process as |
| UMASK | 002 (when PUID is set) | File creation mask for processes and created files |
| ACCOUNTREGISTRATION | false | Allow users to register accounts |
| HTTPALLOWED | false | Allow HTTP connections, only set this to true locally |
| ALLOWUNAUTHENTICATED | false | Allow unauthenticated users to use the service, only set this to true locally |
| AUTODELETEEVERYNHOURS | 24 | Checks every n hours for files older then n hours and deletes them, set to 0 to disable |
| WEBROOT | The address to the root path setting this to "/convert" will serve the website on "example.com/convert/" | |
| BRANDING | ConvertX | Custom string that allows you to change the display name of the website in the header (max 26 characters) |
| FFMPEGARGS | Arguments to pass to the input file of ffmpeg, e.g. -hwaccel vaapi. See https://github.com/C4illin/ConvertX/issues/190 for more info about hw-acceleration. | |
| FFMPEGOUTPUTARGS | Arguments to pass to the output of ffmpeg, e.g. -preset veryfast | |
| HIDEHISTORY | false | Hide the history page |
| LANGUAGE | en | Language to format date strings in, specified as a BCP 47 language tag |
| UNAUTHENTICATEDUSERSHARING | false | Shares conversion history between all unauthenticated users |
| MAXCONVERTPROCESS | 0 | Maximum number of concurrent conversion processes allowed. Set to 0 for unlimited. |
| PORT | 3000 | Application listen port |
Docker images
There is a:latest tag that is updated with every release and a :main tag that is updated with every push to the main branch. :latest is recommended for normal use.The image is available on GitHub Container Registry and Docker Hub.
| Image | What it is |
|---|---|
image: ghcr.io/c4illin/convertx | The latest release on ghcr |
image: ghcr.io/c4illin/convertx:main | The latest commit on ghcr |
image: c4illin/convertx | The latest release on docker hub |
image: c4illin/convertx:main | The latest commit on docker hub |
Tutorial
!NOTE These are written by other people, and may be outdated, incorrect or wrong.
Tutorial in french:
Tutorial in chinese:
Tutorial in polish:
Screenshots
Development
- Install Bun and Git
- Clone the repository
bun installbun run dev
Pull requests are welcome! See open issues for the list of todos. The ones tagged with "converter request" are quite easy. Help with docs and cleaning up in issues are also very welcome!
Use conventional commits for commit messages.
Contributors
Star History
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=C4illin/ConvertX&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=C4illin/ConvertX&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=C4illin/ConvertX&type=Date" />Serve ConvertX on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.
Proxying convertx.example.com to http://convertx:3000
Add this to your Caddyfile
convertx.example.com {
reverse_proxy http://convertx:3000
}Check the logs first
Nine times out of ten the logs tell you exactly what went wrong.
- In Portainer, go to Containers, click the container, then Logs. Or run
docker logs convertx - Exit codes help too:
137means killed, usually out of memory.126or127means the command inside the image is broken.
Port already in use
If deployment fails with "Bind for 0.0.0.0:3000 failed: port is already allocated", something else on your server is using that port.
- Find what's using it:
sudo ss -tlnp | grep :3000 - Stop the other service, or pick a different host port. In
3000:3000only the left number is yours to change, the right one belongs to the app.
Running but the page won't load
The container is up but nothing appears in your browser.
- Use your server's real IP:
http://your-server-ip:3000. The 0.0.0.0 link Portainer shows isn't a real address. - Give it a minute after first deploy, convertx can take a while to initialise.
- Make sure your firewall allows the port, e.g.
sudo ufw allow 3000
Image won't pull
Test the pull directly on the host: docker pull ghcr.io/c4illin/convertx:latest
- "manifest unknown" means the tag no longer exists. This template uses
latest, so try pinning a specific version instead. - "toomanyrequests" is the Docker Hub rate limit. Log in with
docker loginto raise it. - "no space left on device" means a full disk. Reclaim space with
docker system prune
"exec format error"
This means the image was built for a different CPU architecture than your server.
- This image supports:
amd64, arm64 - Check yours with
uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.
Container keeps restarting
The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.
- Check the logs right after a restart, the last few lines before it died are the useful ones.
- Get the exit code with
docker inspect convertx --format '{{.State.ExitCode}}' - Still stuck? Redeploy once with the restart policy set to
noso the failure stays visible.
Raise an issue
Found something which isn't working as it should? Here's how to report it.
- Bug within the app: Open an issue on C4illin/ConvertX
- Template not working: Open an issue on NotAFlightRisk/portainer-templates-extras
- This website not working: Open an issue on lissy93/portainer-templates
A single container
ConvertX runs as one container, the simplest kind of app here. Just the one image to pull and nothing else wired up alongside it.
The app image
An image is the app packed up ready to go, everything ConvertX needs bundled into one download. This template pulls ghcr.io/c4illin/convertx:latest, which Docker fetches once (about 1.4 GB) and then starts your own copy from.
Where the image comes from
Docker pulls its images from registries, public libraries of ready-built apps. ConvertX's comes from the GitHub Container Registry, published by c4illin.
Version tags
The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Pin a specific tag if you would rather stay on one version.
Which machines it runs on
Every image is built for particular CPU types. This one ships for amd64, arm64, so it runs on both regular x86 servers and ARM boards like a Raspberry Pi.
Ports
A port is the door the app answers on. A mapping like 3000:3000 means it's reachable on port 3000 of your server, where the left number is yours to change and the right one belongs to the app. Once it's running, open http://your-server-ip:3000 in a browser. It opens:
3000:3000, likely the web interface
Volumes
A volume is where ConvertX keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:
/app/dataas a volume Docker manages for you
Environment variables
Environment variables are the settings you hand over when you deploy, things like a password or a timezone. ConvertX takes 3 of them, all with defaults you can leave alone or tweak:
HTTP_ALLOWED, pick one oftrue, false. ConvertX only sends its login cookie over HTTPS unless this is on. Switch it off once it's behind a reverse proxy with HTTPS.AUTO_DELETE_EVERY_N_HOURS, defaults to24. Delete converted files after (hours)TZ, defaults toUTC. Like Europe/London
Restart policy
The restart policy here is unless-stopped, so Docker restarts ConvertX after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).
Networking
Nothing custom is set, so ConvertX sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.
Container name
Once it's deployed, Portainer names the container convertx. That's what you'll spot in the containers list and use in commands like docker logs convertx.
Platform
The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.
Open source license
ConvertX is open source, released under the AGPL-3.0 license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.
Portainer app templates
Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set ConvertX up. Add the template list to Portainer once, then deploying ConvertX is a click rather than a wall of config.