Integrations

Le Integrations sono i servizi che puoi installare e gestire direttamente dalla dashboard del container, senza entrare via SSH. Ogni integration è un software open source installato dentro il container: la dashboard ne legge lo stato reale dai file di configurazione e dai comandi del servizio, e ti permette di pilotarlo da UI.

Accanto alle integrations trovi i Server controls: non installano software applicativo ma governano il sistema stesso del container — il Firewall e l'accesso SFTP. Si installano e si usano allo stesso modo, ma vivono in una sezione dedicata della griglia.

Per ogni integration trovi qui sotto quale servizio usa, cosa puoi controllare e come viene gestita la configurazione sul container.

Firewall

Servizio usato. UFW (Uncomplicated Firewall), il frontend standard di iptables su Ubuntu/Debian.

Cosa puoi controllare.

La default incoming policy (allow, deny o reject): cosa succede al traffico in ingresso non coperto da una regola esplicita.
Le regole del firewall (porta, protocollo, sorgente/destinazione), con creazione e rimozione.
Lo stato del servizio: start, stop, reload e recover.

Alcune regole non le scrivi tu ma vengono proposte dalle altre integration in base alla loro configurazione attuale (per es. MariaDB propone l'apertura della sua porta: dal tailnet quando ascolta sulla rete VPN, da ovunque quando ascolta sulla rete pubblica): compaiono sotto la tabella come regole disponibili, attivabili con un click — utile con la default policy deny, per riaprire subito solo ciò che serve. Vengono proposte solo le regole che avrebbero effetto: con MariaDB in ascolto solo su localhost, per esempio, non c'è nulla da aprire e nessuna proposta. Queste regole gestite portano un commento strutturato hund:<servizio>:<chiave> (es. hund:mariadb:tailnet): la tabella del firewall le riconosce e ti mostra perché esistono, invece del tag grezzo. Quando cambi la porta del servizio dalle sue impostazioni di rete, le sue regole gestite vengono riallineate automaticamente alla nuova porta (mantenendo la stessa sorgente: la portata di una regola non si allarga mai da sola); se una regola risulta comunque disallineata (per es. dopo una modifica manuale nel container), ricompare tra le disponibili con l'opzione di aggiornarla.

Configurazione sul container. Le regole e lo stato sono persistiti nei file di UFW (/etc/ufw/, incluso user.rules); lo stato attivo/inattivo si legge da /etc/ufw/ufw.conf. La dashboard applica le modifiche tramite i comandi ufw e le rende leggibili anche a firewall spento.

SFTP

Servizio usato. Il server OpenSSH già presente nel container, con il subsystem internal-sftp e utenti confinati (chroot) — nessun software aggiuntivo.

Cosa puoi controllare.

Gli utenti SFTP: creazione e rimozione. La password viene generata automaticamente e mostrata una sola volta alla creazione; con Reset password ne generi una nuova in qualsiasi momento.
Le cartelle montate: per ogni utente puoi esporre cartelle del container (es. /var/www/html) dentro la sua radice SFTP, con il nome che preferisci.

Come funziona la chroot. Ogni utente è confinato nella propria radice (/srv/sftp/<utente>): non può risalire il filesystem né aprire una shell (niente SSH, solo SFTP). Nella radice trova sempre una cartella files/ scrivibile; le altre cartelle che vedi sono i mount configurati da te.

Nota sui permessi. Il mount espone la cartella, ma la scrittura dentro di essa dipende dai permessi Unix della cartella d'origine: se appartiene a un altro utente (es. www-data), l'utente SFTP potrà leggerla ma non scriverci finché i permessi d'origine non lo consentono.

Configurazione sul container. La configurazione sshd vive in /etc/ssh/sshd_config.d/hund-sftp.conf (validata con sshd -t prima di ogni reload); gli utenti appartengono al gruppo sftp; i mount sono bind-mount persistiti in /etc/fstab con un marker # hund:sftp:<utente> e opzione nofail (se una cartella d'origine sparisce, il container si avvia comunque e l'utente risulta degraded nella tabella).

Deploy

Servizio usato. Il server OpenSSH già presente nel container, con un utente dedicato deploy e la sua directory di release — nessun software aggiuntivo, nessuna porta nuova aperta.

A cosa serve. È un canale per caricare i file di un sito/app nel container da fuori e pubblicarli, senza passare da un repository. È pensato soprattutto per gli assistenti automatici (agenti), ma puoi usarlo anche a mano.

Cosa puoi controllare.

Le chiavi di deploy: ne generi una effimera (durata scelta da te, 1–168 ore); la chiave privata è mostrata una sola volta alla creazione. La scadenza è imposta dal server SSH stesso. Puoi revocarle in qualsiasi momento.
Le release: dopo aver sincronizzato i file in una nuova directory di release, la rendi corrente con un click — lo scambio è atomico, e la release precedente resta come rollback.

Come si usa la chiave. Con la chiave e l'host restituiti sincronizzi la tua cartella nel container, ad esempio:

tar czf - -C ./sito . | ssh -i chiave deploy@<host> 'tar xzf - -C /srv/deploy/releases/v1'

(oppure rsync -e "ssh -i chiave" se preferisci). Poi Rendi attiva la release v1. Un web server (es. Caddy) va puntato su /srv/deploy/current per servirla.

Configurazione sul container. L'utente deploy ha home /srv/deploy, con releases/ e il symlink current; le chiavi stanno in /srv/deploy/.ssh/authorized_keys, ognuna con expiry-time nativa (scadenza forzata da sshd). Non viene toccata la configurazione sshd esistente.

Node.js

Servizio usato. NVM per gestire le versioni di Node, e PM2 come process manager.

Cosa puoi controllare.

La versione di Node di default del container (tra quelle installate o scegliendo una release LTS da installare).
I processi gestiti da PM2: elenco, stato e versione di Node per singola app.

Configurazione sul container. NVM installa le versioni di Node richieste; PM2 mantiene e supervisiona i processi (l'elenco si legge con pm2 jlist). La configurazione di ogni app è salvata in un file dedicato <app>.json. È l'integration più invasiva: l'installazione (NVM + PM2) non è reversibile.

Caddy

Servizio usato. Caddy, web server e reverse proxy con HTTPS automatico (certificati Let's Encrypt out-of-the-box).

Cosa puoi controllare.

I virtual host (vHosts) serviti dal container: creazione e gestione dei siti.

Configurazione sul container. Ogni vHost è un file .conf dentro /etc/caddy/conf.d/, incluso dal Caddyfile principale; la web root di default è /var/www/html. La dashboard legge i siti disponibili e applica le modifiche scrivendo i rispettivi file di configurazione.

Nota. Caddy e NginX usano entrambi le porte 80/443: puoi installarli entrambi sul container, ma solo uno può essere attivo alla volta.

NginX

Servizio usato. NginX, web server e reverse proxy.

Cosa puoi controllare.

I virtual host (vHosts) del container: creazione e gestione dei siti.

Configurazione sul container. I vHost seguono la convenzione classica di NginX: i file stanno in /etc/nginx/sites-available/ e vengono attivati con un symlink in /etc/nginx/sites-enabled/; la web root di default è /var/www/html.

Nota. Conflitto soft con Caddy: condividono le porte 80/443, quindi tienine attivo solo uno alla volta.

PHP-FPM

Servizio usato. PHP-FPM, il process manager con cui un web server esegue codice PHP. È il runtime dei siti WordPress e, in generale, di ogni applicazione PHP servita da filesystem.

Versione. La scegli al momento dell'installazione, da PHP 7.4 a PHP 8.4: i pacchetti arrivano dal repository ondrej/php, perché Ubuntu ne distribuisce una sola versione e un sito con plugin datati spesso ne pretende una più vecchia. Puoi installare più versioni: convivono senza interferire, ognuna con il suo interprete e le sue pool. Tieni presente che le versioni che PHP non supporta più non ricevono correzioni di sicurezza.

Insieme all'interprete vengono installate le estensioni che WordPress e i plugin più diffusi danno per scontate: MySQL, GD, cURL, mbstring, XML, zip, intl, bcmath, SOAP e OPcache.

Cosa puoi controllare.

Le pool: gruppi di processi PHP, uno per sito. Ogni pool ha il suo utente, il suo socket e i suoi limiti (memoria, dimensione degli upload, numero di processi).

Perché una pool per sito. Con una pool sola, il sito che riempie tutti i processi blocca anche gli altri, e tutti girano con lo stesso utente — quindi un sito può leggere i file degli altri. Una pool per sito toglie entrambi i problemi.

Configurazione sul container. Ogni pool è un file .conf in /etc/php/<versione>/fpm/pool.d/. Prima di applicare una modifica la configurazione viene validata (php-fpm -t): se non è valida, la modifica viene annullata e il file torna com'era, così l'interprete resta sempre in grado di ripartire. L'ultima pool di una versione non è eliminabile: senza pool PHP-FPM non si avvia.

Collegamento al web server. Una pool si raggiunge tramite il suo socket (colonna Socket della tabella). Nel vHost di Caddy scegli il template WordPress / PHP e incolla lì quel percorso. Perché il server web possa aprire il socket, il campo Gruppo del socket della pool dev'essere il gruppo con cui gira il server: caddy per Caddy, www-data per NginX.

Headscale

Servizio usato. Headscale, un control server self-hosted compatibile con il protocollo Tailscale (alternativa open source al coordination server di Tailscale).

Cosa puoi controllare.

Le pre-auth key per far entrare nuovi device nella rete: creazione e revoca, con opzioni reusable, ephemeral (i nodi offline vengono rimossi) e scadenza.
I device (nodi) della tailnet: assegnazione di tag e rimozione.
I tag usati per organizzare e applicare policy ai device.
Il dominio del control server (server URL / base domain).

Configurazione sul container. Headscale gira nel container come control server; la rete (config.yaml, server URL e base domain) e le operazioni su chiavi e nodi sono gestite tramite i comandi headscale (preauthkeys, nodes, …). All'installazione il container fa self-join alla propria tailnet così da esserne subito parte.

MariaDB

Servizio usato. MariaDB Server, database relazionale compatibile con MySQL.

Cosa puoi controllare.

I database: creazione e rimozione, con scelta di character set e collation (default consigliato utf8mb4 / utf8mb4_unicode_ci).
Gli utenti: creazione e rimozione, con host di provenienza (usa % per consentire connessioni da qualsiasi host) e password.
Le impostazioni di rete: porta di ascolto e indirizzo di bind.

Configurazione sul container. Porta e bind del server sono configurabili da UI; l'apertura della porta nel firewall viene proposta tra le regole disponibili del Firewall e attivata da lì, come regola gestita (hund:mariadb:tailnet con bind sulla rete VPN, hund:mariadb:port negli altri casi). Database e utenti sono creati ed eliminati tramite i comandi del server MariaDB.

PostgreSQL

Servizio usato. PostgreSQL, database relazionale orientato alla correttezza e alle estensioni. Convive senza problemi con MariaDB: ascoltano su porte diverse.

Cosa puoi controllare.

I database: creazione e rimozione, con scelta della codifica (default consigliato UTF8) e del proprietario. Assegnare come proprietario il ruolo dell'applicazione è la strada più semplice: un owner non ha bisogno di alcun permesso aggiuntivo.
I ruoli (gli utenti di PostgreSQL): creazione con password e, in un colpo solo, i privilegi su un database a scelta. Quest'ultimo passaggio conta: da PostgreSQL 15 un ruolo senza privilegi sullo schema public si connette ma non può creare tabelle — è l'errore permission denied for schema public in cui inciampa quasi tutti quelli che arrivano da MySQL.
Le estensioni: si abilitano per singolo database, non per l'intero server. Oltre a quelle standard (pg_trgm, hstore, citext, pgcrypto, unaccent, uuid-ossp) trovi pgvector per la ricerca su embedding e PostGIS per i dati geografici: il pacchetto necessario viene scaricato e installato al momento, non serve fare nulla a mano.
Le impostazioni di rete: porta di ascolto e interfaccia di bind.

Configurazione sul container. Porta e bind sono configurabili da UI; oltre all'ascolto viene gestito anche il blocco corrispondente in pg_hba.conf (con autenticazione scram-sha-256), perché senza quello le connessioni remote verrebbero rifiutate comunque. Scegliendo "solo localhost" il blocco viene rimosso del tutto. L'apertura della porta nel firewall viene proposta tra le regole disponibili del Firewall e attivata da lì, come regola gestita (hund:postgresql:tailnet con bind sulla rete VPN, hund:postgresql:port negli altri casi).

Nota sull'eliminazione. Cancellare un database chiude anche le connessioni aperte su di esso: se un'applicazione ci stava lavorando, se ne accorgerà.

Redis

Servizio usato. Redis, archivio chiave/valore in memoria: cache, sessioni PHP, code di lavoro.

Cosa puoi controllare.

La memoria massima e la politica di eviction, cioè cosa succede quando quel limite viene raggiunto. La scelta dipende dall'uso: allkeys-lru scarta le chiavi più vecchie ed è quella giusta per una cache; noeviction rifiuta le nuove scritture ed è quella giusta per una coda, dove perdere un messaggio è peggio che rallentare. Con 0 non c'è limite, e Redis può arrivare a consumare tutta la RAM del container.
La persistenza AOF: ogni scrittura viene registrata su disco, così un riavvio non porta via quasi nulla. Senza, resta il solo snapshot periodico.
La password. Redis regge migliaia di tentativi al secondo: senza password è protetto solo dal fatto di ascoltare su localhost.
Le impostazioni di rete: porta di ascolto e interfaccia di bind.

Configurazione sul container. Le impostazioni vivono in due file gestiti da hund (/etc/redis/hund-network.conf e /etc/redis/hund-settings.conf) inclusi in coda alla configurazione della distribuzione, che non viene mai riscritta. Applicare una modifica riavvia Redis: i dati sopravvivono grazie allo snapshot, ma le connessioni aperte cadono. L'apertura della porta nel firewall viene proposta tra le regole disponibili del Firewall (hund:redis:tailnet o hund:redis:port).

Attenzione all'esposizione. Se metti Redis in ascolto sulla rete pubblica senza password, la modalità protetta di Redis rifiuterà comunque le connessioni dall'esterno — il servizio sembrerà irraggiungibile. Imposta prima una password.

Gitea

Servizio usato. Gitea, un server Git self-hosted con interfaccia web, issue, pull request e registry: l'equivalente di GitHub sul tuo container.

Cosa puoi controllare.

Gli utenti: creazione (con ruolo amministratore opzionale), cambio password ed eliminazione.
Le repository: elenco in sola lettura (proprietario, visibilità, se sono ancora vuote). Si creano da Gitea o con un push, non da qui.
L'accesso all'istanza: registrazione libera attiva o disattivata, e obbligo di login per vedere i contenuti.

La porta. Gitea ascolta su una porta interna al container (default 3000), mai esposta su internet: il traffico arriva da Caddy. Se su quella porta hai già qualcosa in ascolto — una app Node, per esempio — indicane un'altra all'installazione: la porta viene controllata prima di iniziare, e se è occupata l'installazione non parte affatto invece di lasciarti un servizio a metà.

Configurazione sul container. Gitea gira come utente git con database SQLite (nessun database server da gestire) e ascolta solo su 127.0.0.1: il traffico passa da Caddy, installato insieme a Gitea e configurato con un vhost sul dominio dell'istanza. Il dominio si sceglie all'installazione: finisce in ROOT_URL e negli URL di clone, quindi cambiarlo dopo li invalida. Git su SSH usa l'sshd del container (porta 22), non un secondo server SSH.

Il dominio. È obbligatorio e lo scegli tu: nessun nome viene assegnato d'ufficio, perché finisce in ogni URL di clone. All'installazione puoi

sceglierne uno tra i domini registrati sul container, oppure
scriverne uno qualsiasi, purché tu l'abbia già puntato al container con un record DNS (non serve registrarlo tra i tuoi domini).

Con un dominio pubblico il server è raggiungibile da internet e il certificato lo emette Caddy da sé. Con una tua zona VPN delegata il nome risolve sull'indirizzo tailscale del container e il vhost usa il certificato wildcard della zona: il server git è visibile solo dai device della tua rete, senza esporre nulla su internet.

L'installer da browser è disattivato (INSTALL_LOCK): il primo amministratore si indica nel form di installazione, così chi apre l'URL trova una pagina di login e non una procedura di configurazione da completare.