Teedy con Docker Compose: archiviare documenti con OCR

Gestire documenti, ricevute, contratti e PDF può diventare complicato, soprattutto quando i file sono sparsi tra cartelle, cloud e dispositivi diversi. Teedy è una soluzione open source e self-hosted che permette di archiviare, organizzare e cercare documenti da un’interfaccia web.

Uno dei suoi punti di forza è l’OCR: dopo il caricamento, Teedy può estrarre il testo dai documenti supportati e renderlo ricercabile. In questa guida vediamo come installare Teedy con Docker Compose, configurare PostgreSQL e iniziare a gestire documenti in locale o su un server.

Cos’è Teedy

Teedy è un sistema di gestione documentale open source pensato per privati, professionisti e piccoli team. Permette di caricare documenti, aggiungere tag e metadati, organizzare file in modo ordinato e cercare testo all’interno dei documenti indicizzati.

Tra le funzioni disponibili ci sono OCR, ricerca full-text, gestione di PDF, immagini, file ODT, DOCX e PPTX, tag gerarchici, versioning, condivisione tramite URL, permessi per utenti e gruppi e autenticazione a due fattori.

Prerequisiti

Per seguire questa guida ti servono:

Un server Linux, un VPS, un NAS compatibile o un mini PC, magari con Debian 13 o Ubuntu 26.04.
Docker e Docker Compose installati.
Un dominio e un reverse proxy, facoltativi ma consigliati se vuoi esporre Teedy su Internet.
Una password robusta per PostgreSQL e una password iniziale per l’account amministratore.

1. Crea la cartella di lavoro

Inizia creando una cartella dedicata al progetto e spostati al suo interno:

mkdir -p ~/teedy
cd ~/teedy

2. Crea il file .env

Per evitare di inserire password direttamente nel file Compose, crea un file chiamato .env:

nano .env

Inserisci valori casuali e robusti, sostituendo l’esempio seguente:

POSTGRES_USER=teedy
POSTGRES_PASSWORD=SOSTITUISCI_CON_UNA_PASSWORD_LUNGA_E_CASUALE
POSTGRES_DB=teedy
TEEDY_ADMIN_EMAIL=admin@example.com
TEEDY_BASE_URL=http://127.0.0.1:8080

Se stai eseguendo Teedy solo nella rete locale e non hai ancora un dominio, puoi usare per il momento un indirizzo come http://192.168.1.10:8080 come valore di TEEDY_BASE_URL.

3. Crea il file docker-compose.yml

Nella stessa cartella crea un file chiamato docker-compose.yml:

nano docker-compose.yml

Incolla questa configurazione:

services:
  teedy:
    image: sismics/docs:v1.11
    container_name: teedy
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      DOCS_BASE_URL: ${TEEDY_BASE_URL}
      DOCS_ADMIN_EMAIL_INIT: ${TEEDY_ADMIN_EMAIL}
      DOCS_DEFAULT_LANGUAGE: ita
      DATABASE_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB}
      DATABASE_USER: ${POSTGRES_USER}
      DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
      DATABASE_POOL_SIZE: 10
    volumes:
      - ./data:/data
    depends_on:
      - postgres
    networks:
      - teedy-internal
      - teedy-public

  postgres:
    image: postgres:13.1-alpine
    container_name: teedy-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks:
      - teedy-internal

networks:
  teedy-internal:
    internal: true
  teedy-public:

La configurazione usa PostgreSQL invece del database H2 integrato. Il progetto raccomanda PostgreSQL per l’uso in produzione e indica il database integrato solo per test e prove iniziali.

4. Avvia Teedy con Docker Compose

Salva il file e avvia i container:

docker compose up -d

Puoi verificare che entrambi i container siano attivi con:

docker ps

Per leggere i log dell’applicazione, utile soprattutto al primo avvio, usa:

docker compose logs -f teedy

5. Accedi a Teedy

Quando il container è pronto, apri il browser e visita:

http://IP-DEL-SERVER:8080

Accedi usando l’username admin e la password admin. Al primo accesso conviene verificare le impostazioni dell’account e modificare subito le credenziali amministrative.

Teedy - Primo Accesso — Teedy – Primo Accesso

6. Come funziona l’OCR in Teedy

Teedy include OCR e strumenti di conversione direttamente nella sua immagine Docker. Quando carichi un documento supportato, l’applicazione può estrarre il testo e aggiungerlo all’indice di ricerca.

Questo significa che puoi cercare parole presenti all’interno di PDF acquisiti con scanner, immagini e altri documenti compatibili, senza dover rinominare manualmente ogni file. Per ottenere risultati migliori, è consigliato caricare scansioni leggibili e con testo ben contrastato.

Teedy - Ricerca nei Documenti — Teedy – Ricerca nei Documenti

7. Organizzare documenti e tag

Dopo aver caricato un documento, puoi aggiungere titolo, descrizione, tag, data, autore e altri metadati. I tag possono essere organizzati in modo gerarchico, una funzione utile per separare ad esempio documenti personali, bollette, ricevute, contratti, lavoro e materiale amministrativo.

Un’organizzazione iniziale semplice può essere questa:

Personale: documenti, certificati, ricevute e assicurazioni.
Casa: utenze, manutenzione, contratti e garanzie.
Lavoro: fatture, progetti, documentazione e note spese.
Archivio: documenti meno recenti ma da mantenere consultabili.

8. Reverse proxy e HTTPS

Se vuoi esporre Teedy su Internet, è consigliato usare un reverse proxy con HTTPS. In questo caso devi impostare TEEDY_BASE_URL con l’URL pubblico completo, ad esempio https://teedy.example.com.

Puoi usare Nginx Proxy Manager, Traefik, Caddy oppure la configurazione Nginx che preferisci. Il reverse proxy deve inoltrare le richieste verso la porta 8080 del container Teedy.

Se Teedy resta accessibile solo nella rete locale, puoi anche evitare di pubblicarlo su Internet e limitare l’esposizione della porta con questa sintassi nel file Compose:

ports:
  - "127.0.0.1:8080:8080"

In questo modo l’applicazione sarà raggiungibile direttamente solo dal server e potrà essere esposta all’esterno esclusivamente tramite reverse proxy.

9. Backup di Teedy

Per eseguire un backup corretto devi salvare sia la cartella data, che contiene i file e i dati dell’applicazione, sia la cartella postgres, che contiene il database PostgreSQL.

Prima di copiare i dati, per un backup consistente è preferibile fermare temporaneamente lo stack:

docker compose down

Dopo aver copiato le cartelle data e postgres in una posizione sicura, puoi riavviare i servizi:

docker compose up -d

Considerazioni finali

Teedy è una soluzione molto valida per chi vuole creare un archivio documentale personale o professionale, con ricerca OCR e pieno controllo sui propri dati. Con Docker Compose e PostgreSQL l’installazione è relativamente semplice, ma offre già funzioni avanzate come tag, versioning, permessi, condivisione e indicizzazione del testo.

Se cerchi un’alternativa self-hosted per archiviare PDF, scansioni, documenti e ricevute senza dipendere da servizi cloud esterni, Teedy merita sicuramente di essere provato.

FAQ

Cos’è Teedy?

Teedy è un software open source per la gestione documentale. Permette di caricare, classificare, cercare e condividere documenti da un’interfaccia web.

Teedy supporta l’OCR?

Sì. Teedy include strumenti OCR nella propria immagine Docker e può estrarre testo dai documenti supportati per renderlo ricercabile, supporta senza problemi l’italiano.

Teedy può gestire PDF e documenti Office?

Sì. Il progetto supporta PDF, immagini, ODT, DOCX, PPTX e altri formati, con ricerca full-text per i file compatibili.

È possibile installare Teedy con Docker Compose?

Sì. Docker Compose è un metodo pratico per avviare Teedy insieme a PostgreSQL e mantenere dati e database in volumi persistenti.

Serve PostgreSQL per usare Teedy?

Teedy può usare un database H2 integrato per prove e test, ma per un utilizzo in produzione il progetto raccomanda PostgreSQL.

Dove vengono salvati i documenti caricati?

Con la configurazione mostrata in questa guida, i documenti e i dati dell’applicazione vengono salvati nella cartella data, mentre il database viene salvato nella cartella postgres.