ConvertX/README.md

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
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

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 HTTP_ALLOWED=true

# docker-compose.yml
services:
  convertx:
    image: ghcr.io/c4illin/convertx
    container_name: convertx
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - JWT_SECRET=aLongAndSecretStringUsedToSignTheJSONWebToken1234 # will use randomUUID() if unset
      # - HTTP_ALLOWED=true # uncomment this if accessing it over a non-https connection
    volumes:
      - ./data:/app/data

or

docker run -p 3000:3000 -v ./data:/app/data ghcr.io/c4illin/convertx

or, to keep configuration in a single .env file instead of inline in the compose file, copy .env.example to .env, fill in what you need, and run:

docker compose -f docker-compose.prod.yml up -d

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.

If you get unable to open database file run chown -R $USER:$USER path on the path you choose.

Environment variables

All are optional, JWT_SECRET is recommended to be set.

Name	Default	Description
JWT_SECRET	when unset it will use the value from randomUUID()	A long and secret string used to sign the JSON Web Token
ACCOUNT_REGISTRATION	false	Allow users to register accounts
HTTP_ALLOWED	false	Allow HTTP connections, only set this to true locally
ALLOW_UNAUTHENTICATED	false	Allow unauthenticated users to use the service, only set this to true locally
AUTO_DELETE_EVERY_N_HOURS	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/"
FFMPEG_ARGS		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.
FFMPEG_OUTPUT_ARGS		Arguments to pass to the output of ffmpeg, e.g. -preset veryfast
HIDE_HISTORY	false	Hide the history page
LANGUAGE	en	Language to format date strings in, specified as a BCP 47 language tag
UNAUTHENTICATED_USER_SHARING	false	Shares conversion history between all unauthenticated users
MAX_CONVERT_PROCESS	0	Maximum number of concurrent conversion processes allowed. Set to 0 for unlimited.
OIDC_ISSUER		The OIDC provider's issuer URL, e.g. https://authentik.example.com/application/o/convertx/. Setting this along with OIDC_CLIENT_ID, OIDC_CLIENT_SECRET and OIDC_REDIRECT_URI enables "Login with SSO".
OIDC_CLIENT_ID		OAuth2/OIDC client ID issued by the provider
OIDC_CLIENT_SECRET		OAuth2/OIDC client secret issued by the provider
OIDC_REDIRECT_URI		The public callback URL registered with the provider, e.g. https://convertx.example.com/login/oidc/callback
OIDC_SCOPES	openid profile email	Space-separated scopes requested from the provider
OIDC_NAME	SSO	Display name used on the "Login with ..." button
OIDC_ONLY	false	Hide the local email/password login and registration forms entirely, only allow login via OIDC

Single sign-on with Authentik (OIDC)

ConvertX can authenticate users against any standards-compliant OIDC provider using the authorization code flow with PKCE. To use Authentik:

1. In Authentik, create a new Provider of type "OAuth2/OpenID Provider":
   • Client type: Confidential
   • Redirect URI: https://convertx.example.com/login/oidc/callback (strict, must match OIDC_REDIRECT_URI exactly)
   • Note the generated Client ID and Client Secret
2. Create an Application in Authentik and bind it to that provider.
3. Note your provider's issuer URL, shown on the provider page, usually https://authentik.example.com/application/o/<application-slug>/.
4. Set the following in your environment:

environment:
  - OIDC_ISSUER=https://authentik.example.com/application/o/convertx/
  - OIDC_CLIENT_ID=your-client-id
  - OIDC_CLIENT_SECRET=your-client-secret
  - OIDC_REDIRECT_URI=https://convertx.example.com/login/oidc/callback
  # - OIDC_NAME=Authentik # optional, changes the button label
  # - OIDC_ONLY=true # optional, hides local password login entirely

The first user to sign in via SSO is automatically created locally (matched/linked by email to any existing local account) and JWT sessions work exactly as with password login. If OIDC_ONLY is not set, both the local login form and the SSO button are shown, so existing local accounts keep working alongside SSO.

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: https://belginux.com/installer-convertx-avec-docker/

Tutorial in chinese: https://xzllll.com/24092901/

Tutorial in polish: https://www.kreatywnyprogramista.pl/convertx-lokalny-konwerter-plikow

Screenshots

Development

0. Install Bun and Git
1. Clone the repository
2. bun install
3. bun 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