# 07-convertx.md

kstack:
  book: Centerpoint Home Lab
  chapter: Utilities
  page: ConvertX
  tags: [convertx, file-conversion, utilities]
---

## Overview

ConvertX is a self-hosted file format conversion tool. It supports converting
between video, audio, image, document, and other file formats using a web
interface. Internal-only access. Account registration is enabled, allowing any
LAN user to create an account.

## Access

| Type     | URL                               | Auth                           |
|----------|-----------------------------------|--------------------------------|
| Internal | `https://convertx.home.local`     | ConvertX own auth (Step-CA TLS) |

## Configuration

**Image:** `ghcr.io/c4illin/convertx`

### Environment Variables

| Variable                     | Value  | Purpose                                      |
|------------------------------|--------|----------------------------------------------|
| `HTTP_ALLOWED`               | `true` | Allows HTTP connections (Traefik terminates TLS) |
| `ACCOUNT_REGISTRATION`       | `true` | Any LAN user can self-register               |
| `QTWEBENGINE_CHROMIUM_FLAGS` | `--no-sandbox` | Required for headless Chromium in container |

### Traefik Labels

```yaml
traefik.http.routers.convertx.rule: Host(`convertx.home.local`)
traefik.http.routers.convertx.entrypoints: websecure
traefik.http.routers.convertx.tls.certresolver: step-ca
traefik.http.services.convertx.loadbalancer.server.port: 3000
```

## Volumes / Bind Mounts

| Host Path                     | Container Path | Purpose              |
|-------------------------------|----------------|----------------------|
| `/data/compose/43/data`       | `/app/data`    | App data and SQLite  |

> The data directory is a Portainer-managed compose path
> (`/data/compose/<stack-id>/data`) — this stack is managed entirely via
> Portainer with no local compose file. The path is determined by the Portainer
> stack ID (43).

## Notes / Gotchas

- `ACCOUNT_REGISTRATION=true` allows any user on the LAN to self-register.
  Disable this if access should be restricted to a single admin account.
- Converted files are stored temporarily in the app data directory and deleted
  after download. Do not use this path for long-term storage.
- `--no-sandbox` is a Chromium security flag required when running in a
  container (no user namespace isolation). This is standard for containerised
  headless browser setups.
- ConvertX uses FFmpeg, ImageMagick, and other converters internally — available
  formats depend on the image build.

---
*Last Updated: 2026-06-17*