Guida a ConvertX con Docker - converti file in altri formati

ConvertX è un convertitore di file open source e self-hosted che permette di gestire conversioni direttamente sul proprio server, senza affidarsi a servizi esterni. In questa guida pratica vediamo come installarlo con Docker Compose, come salvare i dati in modo persistente e quali impostazioni conviene configurare subito.

Cos’è ConvertX

ConvertX è un software open source pensato per convertire file tramite interfaccia web, con supporto a oltre 1000 formati differenti. È una soluzione interessante per chi vuole gestire conversioni di documenti, immagini, audio, video ed ebook in locale o su un server dedicato.

Prerequisiti

Prima di iniziare ti servono pochi elementi:

Un server Linux o un VPS com almeno 2 GB di RAM;
Docker e Docker Compose già installati;
Almeno 10 GB di spazio libero su disco.

1. Crea la cartella di lavoro

Per prima cosa crea una directory dedicata a ConvertX e una sottocartella per i dati persistenti:

mkdir -p ~/convertx/data
cd ~/convertx

2. Crea il file docker-compose.yml

All’interno della cartella convertx, crea un file chiamato docker-compose.yml con questo contenuto:

services:
  convertx:
    image: ghcr.io/c4illin/convertx
    container_name: convertx
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      JWT_SECRET: cambia-questa-stringa-con-un-valore-lungo-e-casuale
      ACCOUNT_REGISTRATION: "false"
      AUTO_DELETE_EVERY_N_HOURS: "24"
      LANGUAGE: "it"
    volumes:
      - ./data:/app/data

Questa configurazione è sufficiente per partire con un’installazione semplice e con salvataggio persistente dei dati. Mi raccomando di impostare qualcosa di lungo nel JWT_SECRET, ad esempio generando una stringa di almeno 32 caratteri. Puoi sfruttare anche IT-Tools per farlo.

3. Avvia il container

Dopo aver salvato il file, avvia ConvertX in background con:

docker compose up -d

Se vuoi controllare che il container sia partito correttamente, puoi usare questo comando:

docker ps

4. Accedi all’interfaccia web

Una volta completato l’avvio, l’interfaccia web sarà raggiungibile dal browser all’indirizzo:

http://IP-DEL-SERVER:3000

Se stai lavorando in locale, puoi aprire anche http://localhost:3000 e dovresti visualizzare la schermata di registrazione:

ConvertX - registrazione account — ConvertX – registrazione account

La schermata di upload di un file per la conversione è semplicissima:

ConvertX - upload di un file — ConvertX – upload di un file

File finale convertito (nell’esempio da PNG a WebP):

ConvertX - File convertito — ConvertX – File convertito

5. Variabili d’ambiente utili da conoscere

ConvertX supporta diverse variabili ambiente. Alcune sono obbligatorie e inserite già dalla configurazione iniziale, le altre invece sono opzionali:

JWT_SECRET: default auto-generato casualmente, chiave usata per firmare i token di autenticazione. Conviene impostarne una lunga e casuale.
ACCOUNT_REGISTRATION: default false, permette di abilitare o disabilitare la registrazione di nuovi utenti.
AUTO_DELETE_EVERY_N_HOURS: default 24, elimina automaticamente i file più vecchi dopo il numero di ore indicato.
ALLOW_UNAUTHENTICATED: default false, consente l’uso senza autenticazione, ma ha senso soprattutto in ambienti locali o di test.
HTTP_ALLOWED: default false, opzione utile solo in contesti locali; in pubblico è meglio usare HTTPS dietro reverse proxy.
WEBROOT: default vuoto, utile se vuoi pubblicare ConvertX in una sottocartella, ad esempio /convertx.
HIDE_HISTORY: default false, permette di nascondere la cronologia dall’interfaccia.
LANGUAGE: default ‘en’, permette di definire la lingua con la quale formattare data e ora. Per l’italiano basta specificare ‘it’.
UNAUTHENTICATED_USER_SHARING: default false, permette di condividere la cronologia delle conversioni tra utenti non autenticati.
MAX_CONVERT_PROCESS: default 0, permette di impostare un limite sul numero massimo di processi di conversione eseguibili in parallelo, utile ad esempio se si hanno risorse limitate o non si vuole appesantire il sistema (0 = illimitato, 1 = 1 processo di conversione alla volta e così via).

6. Configurazione consigliata

Per un’installazione base, una buona idea è partire con registrazione disattivata, autenticazione attiva e cancellazione automatica dei file abilitata. In questo modo ottieni un ambiente più ordinato e riduci il rischio di lasciare file caricati troppo a lungo sul server, evitando che altri utenti non autorizzati utilizzino il tuo servizio.

7. A cosa serve ConvertX

Uno dei punti forti di ConvertX è la possibilità di gestire conversioni di file direttamente sul proprio server, con maggiore controllo rispetto ai classici servizi online. Può essere utile in ambienti self-hosted, in piccoli team o semplicemente per chi vuole evitare di caricare file su piattaforme esterne.

Succede spesso infatti di avere la necessità di convertire immagini, documenti e altri tipi di file da un formato all’altro e avere un servizio online, sotto il nostro controllo, è molto più sicuro anche per proteggere i dati caricati, soprattutto se sensibili. Poterlo fare direttamente online, da qualsiasi dispositivo connesso alla rete, senza software aggiuntivi, è un vantaggio notevole.

Considerazioni finali

ConvertX è una soluzione molto interessante per chi cerca un convertitore di file self-hosted semplice da installare e da usare. Con Docker Compose bastano pochi minuti per avere un’interfaccia web pronta all’uso, con dati persistenti e alcune opzioni di configurazione già sufficienti per un utilizzo pratico.

FAQ

Cos’è ConvertX?

ConvertX è un convertitore di file open source e self-hosted che permette di trasformare diversi tipi di file tramite interfaccia web, direttamente sul proprio server.

Quanti formati supporta ConvertX?

Il progetto dichiara il supporto a oltre 1000 formati differenti, includendo documenti, immagini, audio, video ed ebook.

ConvertX si può installare con Docker?

Sì, Docker è uno dei metodi più pratici per installarlo, specialmente su VPS, mini server e ambienti homelab.

Quale porta usa ConvertX?

Nella configurazione più comune il servizio espone la porta 3000, che può essere esposta direttamente oppure gestita dietro reverse proxy (ad esempio con nginx, traefik o più semplicemente con caddy). Se hai seguito altri nostri tutorial, magari esponendo già servizi sulla porta 3000, ti consigliamo di cambiarla, per esempio mettendo 3001 e così via.