ConvertX on Ubuntu 24.04 on Azure User Guide

Overview

ConvertX is a self hosted online file converter with a clean, modern web interface. You sign in, upload a file, choose a target format, and ConvertX converts it for you, then lets you download the result or review a history of past conversions. It supports more than a thousand input and output formats across images, documents, audio, video, e books, vector graphics and 3D models, powered by a large bundle of open source converters. The cloudimg image runs ConvertX the officially supported way, as the upstream container with an embedded SQLite database and every conversion tool baked in, orchestrated by Docker Compose under systemd and fronted by nginx. The image is pinned by digest and captured into the VM, so your instance starts in seconds. A unique owner account and a unique session signing secret are generated for each VM on first boot, before the port is reachable, and open sign up and anonymous use are disabled, so nobody can seize your instance before you sign in. Backed by 24/7 cloudimg support.

ConvertX is a trademark of its respective owner. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by ConvertX. It ships the free and open source AGPL 3.0 licensed core, unmodified.

What is included:

• ConvertX v0.18.0 (the AGPL 3.0 licensed self hosted core), shipped as the official upstream container pinned by image digest
• A large bundle of open source converters baked into the image: FFmpeg, ImageMagick, GraphicsMagick, Vips, libheif, libjxl, LibreOffice, Calibre, Pandoc, Inkscape, XeLaTeX, resvg, Potrace, VTracer, Assimp and more
• Docker Engine (Docker CE) with the ConvertX app and API published to the loopback interface only, fronted by nginx on port 80
• An embedded SQLite database and a single data volume for uploads and converted files
• convertx.service, convertx-firstboot.service and nginx.service as systemd units, enabled and active on boot
• A unique owner account and a unique session signing secret generated per VM on first boot, never baked into the image
• A clean, empty instance on first boot: no default account, no shipped secret, no prior data
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point; increase the size for heavier media such as large video files. NSG inbound: allow 22/tcp from your management network and 80/tcp (and 443/tcp once you add TLS) for the web interface. ConvertX serves plain HTTP on port 80; for production, put it behind TLS with your own domain (see the final section).

Step 1 - Deploy from the Azure Marketplace

1. In the Azure portal, choose Create a resource and search the Marketplace for the cloudimg ConvertX offer.
2. Select the plan, then Create.
3. On the Basics tab pick your subscription, resource group and region, name the VM, and select Standard_B2s (or larger).
4. Choose SSH public key authentication with admin username azureuser and provide your public key.
5. On the Networking tab, allow inbound 22/tcp from your management network and 80/tcp for the web interface.
6. Review and create. When the VM is running, note its public IP address.

Step 2 - Deploy from the Azure CLI

Prefer the command line? Create the VM from the cloudimg ConvertX image, opening 22/tcp and 80/tcp:

az vm create \
  --resource-group my-convertx-rg \
  --name convertx \
  --image <cloudimg-convertx-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az vm open-port --resource-group my-convertx-rg --name convertx --port 80 --priority 900

Then browse to http://<vm-ip>/ once first boot has finished.

Step 3 - Connect to your VM

ssh azureuser@<vm-ip>

Step 4 - Confirm the services are running

ConvertX runs as a single container under Docker Compose, managed by convertx.service, with nginx fronting it on port 80:

sudo systemctl is-active docker convertx nginx
sudo docker compose --env-file /etc/convertx/convertx.env -f /etc/convertx/compose.yaml ps

Expected output:

active
active
active
NAME                  SERVICE    STATUS
convertx-convertx-1   convertx   Up 6 minutes

Step 5 - Secure by default: a unique owner, no default account

With stock ConvertX, the very first person to reach the page can register the owner account. This image closes that hole. On first boot, before the port was reachable, a unique owner account was pre seeded with a per VM password, a per VM session signing secret was generated, and open sign up was disabled. You can prove it: the default guess and a blank password are rejected, while your per VM owner password is accepted (HTTP 302, a redirect into the app):

EMAIL=$(sudo grep '^CONVERTX_ADMIN_EMAIL=' /root/convertx-credentials.txt | cut -d= -f2-)
PASS=$(sudo grep '^CONVERTX_ADMIN_PASSWORD=' /root/convertx-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'default admin@example.com -> HTTP %{http_code}\n' -X POST http://127.0.0.1/login --data-urlencode email=admin@example.com --data-urlencode password=password
curl -s -o /dev/null -w 'blank password           -> HTTP %{http_code}\n' -X POST http://127.0.0.1/login --data-urlencode "email=$EMAIL" --data-urlencode 'password='
curl -s -o /dev/null -w 'per-VM owner password     -> HTTP %{http_code}\n' -X POST http://127.0.0.1/login --data-urlencode "email=$EMAIL" --data-urlencode "password=$PASS"

Expected output:

default admin@example.com -> HTTP 403
blank password           -> HTTP 403
per-VM owner password     -> HTTP 302

Your per VM owner email and password are written to a root only file. Read them with:

sudo cat /root/convertx-credentials.txt

Step 6 - Sign in to ConvertX

Open http://<vm-ip>/ in your browser. ConvertX redirects you to the login page, because anonymous use is disabled. Sign in with the owner email and password from the credentials file above.

Step 7 - Convert a file

After signing in you land on the convert screen. Drag a file into the drop area (or click Choose a file), then type the format you want in the search box, for example jpg, pdf or mp4, and pick the converter offered. Click Convert to run it.

Step 8 - Download the result

When the conversion finishes, ConvertX shows the results page with each converted file, its status and a download link. Download individual files, or grab them all as a single archive.

Step 9 - Review your history

The History page lists your past conversion jobs so you can return to earlier results. Old jobs are cleaned up automatically after 24 hours by default.

Step 10 - Check the stack health from the command line

ConvertX exposes an unauthenticated liveness endpoint, and you can prove a real conversion end to end from the shell. The built in check logs in with your per VM owner, uploads a small image, converts it to JPEG and downloads the result:

curl -s -o /dev/null -w 'GET /healthcheck -> HTTP %{http_code}\n' http://127.0.0.1/healthcheck
curl -s http://127.0.0.1/healthcheck; echo
sudo /usr/local/sbin/convertx-roundtrip.sh

Expected output:

GET /healthcheck -> HTTP 200
{"status":"ok"}
OK round-trip: owner=admin@convertx.local (default+blank+wrong rejected; self-register blocked 403; anon 302; converted PNG->JPEG /download/1/2/cx_rt.jpg magic=ffd8ff)

Step 11 - Add more users

By default this image is a single owner appliance with open sign up disabled. To let more people register accounts, enable registration and restart:

# Enable open registration, then browse to http://<vm-ip>/register to add users
sudo sed -i 's/ACCOUNT_REGISTRATION: "false"/ACCOUNT_REGISTRATION: "true"/' /etc/convertx/compose.yaml
sudo systemctl restart convertx

New users can then register at http://<vm-ip>/register. Set it back to "false" and restart once your users have accounts.

Step 12 - Production: your own domain with TLS

ConvertX is served over plain HTTP on port 80. For production, front it with your own domain and a TLS certificate. Point a DNS record at the VM, open 443/tcp in the NSG, then install a certificate with a tool such as Certbot and configure nginx to serve HTTPS and redirect HTTP to HTTPS. Keep the app bound to the loopback interface so it is only reachable through nginx.

Support

Questions or issues with the image? Email support@cloudimg.co.uk. For ConvertX itself, see the upstream project on GitHub.