Sito in costruzione. Questa guida descrive un kit che finora è stato verificato solo in modo statico e non è ancora stato eseguito su un Cloud Computer reale (rilievo F-12). La prima installazione è quindi anche il suo primo collaudo.

Kit Cloud Computer · revisione d20f7bb · aggiornata al 3 novembre 2026

Installare DanAivatar su un Cloud Computer e attivare il primo owner

Otto fasi, dal computer vuoto al primo accesso dal telefono. Ogni comando si copia con un tocco e ogni fase si chiude con un controllo: sai sempre se puoi andare avanti.

Il percorso in breve

Le fasi da 2 a 5 si svolgono nel terminale del Cloud Computer; la 6 e la 8 nel browser del telefono.

  1. Controlla di avere tuttoTaglio della macchina, accesso a GitHub, e-mail dell'owner
  2. Crea il Cloud Computer e apri il terminaleImpostazioni Manus, poi SSH
  3. Scarica il codice di DanAivatarGitHub CLI e repository privato
  4. Scegli l'indirizzo del sitoNomi automatici sslip.io oppure un tuo dominio
  5. Lancia l'installerUn solo comando, rieseguibile
  6. Attiva il primo ownerLink monouso, password, spazio di lavoro
  7. Controlla che tutto funzioniServizi, HTTPS, revisione installata
  8. Consenso e primo videoModulo online, approvazione del Titolare

Prima di iniziare

Nessun comando: solo controlli
Cosa serve per l'installazione
Cosa serveDettagli
Cloud Computer Manus, taglio Advanced8 GB di RAM, 2 vCPU, 120 GB di disco, Ubuntu 24.04, IP pubblico. Il prezzo indicato dalla documentazione Manus è di 50 $ al mese: verificalo nella pagina di creazione.
Accesso al repositoryUn account GitHub con accesso al repository privato ArabianLove/DanAivatar.
E-mail dell'ownerDiventa il nome utente del primo account ed è l'unico indirizzo autorizzato a creare spazi di lavoro. L'istanza non invia e-mail: i link li consegni tu.
Un browserSul telefono o sul computer, per creare la password e usare DanAivatar.
Un dominio (facoltativo)Senza dominio l'installer usa nomi automatici basati sull'IP (fase 4).
Perché non basta il taglio Standard

Durante un video l'animatore JoyVASA da solo ha occupato fino a 3,45 GiB, e l'intero worker 3,58 GiB (misura sulla revisione 196d916). A questi si aggiungono database, storage e API: su 4 GB la macchina esaurirebbe la memoria. L'Advanced da 8 GB lascia margine.

Cosa non otterrai su questa macchina

  • Video lenti. Il Cloud Computer non ha GPU. In sviluppo l'animazione ha richiesto 42–45 secondi per fotogramma con 5 thread: una frase di circa 1,6 secondi ha impiegato circa mezz'ora. Con le 2 vCPU del Cloud Computer sarà più lenta; la velocità esatta non è ancora stata misurata.
  • Niente voce clonata. Il motore di clonazione ha bisogno di oltre 7 GiB da solo e di almeno 16 GB di RAM: l'installer non lo installa. Restano le voci predefinite.
  • Solo valutazione. La voce predefinita (Kokoro) ha un vincolo di licenza (rilievo F-01) e la firma di provenienza C2PA usa un certificato di sviluppo (rilievo F-03). L'istanza parte quindi in modalità valutazione, non adatta a un servizio commerciale.

Crea il Cloud Computer e apri il terminale

Impostazioni Manus, poi terminale
  1. Apri la pagina Impostazioni → My Computer → Crea, scegli il taglio Advanced e conferma. Se hai già un Cloud Computer Advanced puoi usare quello.
  2. Nella stessa sezione delle impostazioni trovi i dati di accesso SSH: IP pubblico, utente ubuntu, password e il comando SSH già pronto.
  3. Apri un terminale sul Cloud Computer in uno di questi due modi:
    • SSH dal tuo computer (Terminale su macOS e Linux, PowerShell su Windows) o da un'app SSH per iPhone, incollando il comando SSH delle impostazioni;
    • tramite Manus: in un'attività con il Cloud Computer collegato, chiedi di eseguire per te i comandi di questa guida, uno per fase.

Il testo evidenziato in giallo nei comandi è un esempio da sostituire con i tuoi dati prima di premere Invio.

Controlla la macchina

Terminale del Cloud Computer
lsb_release -ds; dpkg --print-architecture; nproc; free -h; df -h /
sudo ufw status
Cosa devi vedere

Ubuntu 24.04…, un'architettura amd64 o arm64, 2 CPU, circa 7–8 GiB nella colonna total di Mem e oltre 100 GB liberi sul disco. Se ufw risulta Status: active, l'installer aprirà da solo le porte 80 e 443; se è inactive non devi fare nulla.

Scarica il codice di DanAivatar

Terminale del Cloud Computer

Il repository è privato: per scaricarlo autentichi la macchina con la GitHub CLI.

Installa git, GitHub CLI e tmux
sudo apt-get update
sudo apt-get install -y git gh tmux
Collega GitHub
gh auth login

Rispondi alle domande: GitHub.com → HTTPS → Authenticate Git with your GitHub credentials? Yes → Login with a web browser. Il terminale mostra un codice di 8 caratteri: aprilo su github.com/login/device dal telefono, inserisci il codice e autorizza.

Scarica il repository
gh repo clone ArabianLove/DanAivatar ~/DanAivatar
cd ~/DanAivatar
git checkout manus/danaivatar-implementation
git log -1 --oneline
Cosa devi vedere

L'ultima riga mostra il commit d20f7bb o uno più recente dello stesso ramo.

Quando il codice arriverà su main

Il kit si trova sul ramo manus/danaivatar-implementation della pull request #1. Quando la pull request sarà unita, usa git checkout main al posto di quel ramo.

Scegli l'indirizzo del sito

Una decisione, nessun comando obbligatorio

DanAivatar usa due nomi: uno per il sito e uno per lo storage da cui il browser carica e scarica i file con link firmati. Caddy ottiene da solo i certificati HTTPS di Let's Encrypt per entrambi.

Opzione A, consigliata per iniziare: nessun dominio

Non passare opzioni. L'installer ricava i nomi dall'IP pubblico tramite il servizio sslip.io, sostituendo i punti con trattini. Con l'IP 203.0.113.10, ad esempio, ottieni:

  • sito: danaivatar.203-0-113-10.sslip.io
  • storage: s3.203-0-113-10.sslip.io

Opzione B: un tuo dominio

Crea presso il tuo provider DNS due record A che puntano all'IP pubblico del Cloud Computer, per esempio avatar.tuodominio.it e s3.avatar.tuodominio.it. Prima di installare, controlla che entrambi rispondano con l'IP giusto:

Controlla i nomi
getent hosts avatar.tuodominio.it s3.avatar.tuodominio.it

I due nomi vanno passati sempre insieme e devono essere diversi (fase 5).

Lancia l'installer

Terminale del Cloud Computer

L'installazione scarica pacchetti, ambienti Python e pesi dei modelli: dura a lungo, e quanto esattamente non è ancora stato misurato su questa macchina. Lanciala dentro tmux, così continua anche se la connessione SSH cade.

Apri una sessione che sopravvive alle disconnessioni
tmux new -s danaivatar

Se la connessione si interrompe, ricollegati con SSH e torna alla sessione con tmux attach -t danaivatar.

Senza dominio (opzione A)

Installa DanAivatar
cd ~/DanAivatar
sudo deploy/cloud-computer/install.sh --owner-email tua@email.it

Con un tuo dominio (opzione B)

Installa DanAivatar con il tuo dominio
cd ~/DanAivatar
sudo deploy/cloud-computer/install.sh --owner-email tua@email.it \
  --domain avatar.tuodominio.it --s3-domain s3.avatar.tuodominio.it

Le opzioni dello script

Opzioni di install.sh
OpzioneEffetto
--owner-emailObbligatoria. E-mail del primo owner: è l'unico account che potrà creare spazi di lavoro.
--domain e --s3-domainIl tuo dominio per il sito e per lo storage: vanno usati insieme e devono essere diversi.
--skip-modelsSalta il download dei pesi, il riscaldamento dei motori e la creazione del manifest. Usala solo rieseguendo l'installer quando pesi e manifest sono già presenti: il worker li verifica comunque a ogni avvio.
--no-startNon avvia né riavvia API, worker e pulizia periodica, e non emette il link dell'owner. PostgreSQL e storage vengono comunque avviati, e i servizi già in esecuzione non vengono fermati.
--with-voice-cloneAggiunge la clonazione vocale. Non usarla sul Cloud Computer: richiede almeno 16 GB di RAM.

Cosa compare a schermo, in ordine

  • == system packagesPostgreSQL, Caddy, ffmpeg e le altre dipendenze di sistema.
  • == service users and directoriesUtenti di servizio separati per API, worker e storage.
  • == pinned binaries (uv 0.13.6, SeaweedFS 4.51)Binari scaricati con impronta SHA-256 verificata.
  • == application codeCopia del codice in /opt/danaivatar/app, con la revisione registrata.
  • == upstream sources (pinned commits, …)Sorgenti dei motori a commit fissati.
  • == Python environments (…)Un ambiente per il nucleo e uno per ciascun motore.
  • == configuration and secrets (/etc/danaivatar)Password e chiavi generate una sola volta e mai sovrascritte.
  • == database (roles, migrations)Ruoli separati e migrazioni dello schema.
  • == object storage credentialsCredenziali dello storage compatibile S3.
  • == C2PA signing material (…)Certificato di sviluppo per la firma di provenienza (rilievo F-03).
  • == systemd units and reverse proxyServizi che ripartono da soli al riavvio e HTTPS automatico con Caddy.
  • == model weights (…)L'unica fase con accesso alla rete per i modelli: i pesi vengono verificati e poi bloccati da un manifest SHA-256.
  • == starting servicesAvvio di API, worker, pulizia periodica e proxy.
  • == first ownerEmissione del link monouso dell'owner (fase 6).
  • == done: https://… (revision …)Indirizzo del sito e revisione installata.
Puoi rilanciarlo senza rischi

L'installer è rieseguibile: segreti e password già creati non vengono rigenerati e le migrazioni già applicate vengono saltate. Se si ferma con un errore, correggi la causa (problemi comuni) e rilancia lo stesso comando.

Attiva il primo owner

Terminale, poi browser del telefono

Alla fine dell'installazione il terminale mostra il link dell'owner in una riga di testo. Questo è un esempio, con un IP di documentazione:

Esempio di output, da non copiare
== first owner
Single-use link for the owner's password (a secret: open it yourself, do not forward it):
{"link_id": "…", "email": "tua@email.it", "purpose": "register", "expires_in_hours": "72", "url": "https://danaivatar.203-0-113-10.sslip.io/#account=…"}

== done: https://danaivatar.203-0-113-10.sslip.io  (revision …)
  1. Copia solo il valore di url, da https:// fino alla fine, compresa la parte #account=…. In tmux puoi scorrere l'output con Ctrl+b e poi [; esci con q.
  2. Aprilo nel browser del telefono. Compare la schermata «Crea il tuo account», con la tua e-mail già compilata e non modificabile.
  3. Scegli la password nei campi Password e Ripeti la password: da 15 a 128 caratteri. Va benissimo una frase di più parole con gli spazi; non servono simboli o maiuscole, ma evita password comuni, ripetitive o legate al servizio o alla tua e-mail. Con «Mostra password» controlli cosa hai scritto. Poi tocca «Crea account ed entra».
  4. Lo spazio di lavoro si crea da solo. Al primo accesso l'app crea il tuo spazio e te ne nomina Titolare. Compare il messaggio «Abbiamo creato il tuo spazio di lavoro “…”. Puoi rinominarlo e invitare colleghi dalla scheda Team.» Per cambiare nome apri la scheda Team, modifica il nome nella sezione «Nome dello spazio di lavoro» e tocca «Salva il nome».
Il link è un segreto

Funziona una sola volta e scade dopo 72 ore: aprilo tu, non inoltrarlo e non incollarlo in chat. Se hai fatto eseguire i comandi a Manus, il link compare anche nell'attività: usalo subito, così chi lo leggesse dopo troverebbe un link già usato.

Gli accessi successivi

Apri l'indirizzo del sito e usa «Accedi» con e-mail e password. La sessione dura 12 ore. Dopo 10 tentativi sbagliati l'account resta bloccato per 15 minuti.

Link perso, scaduto o già usato

Emetti un nuovo link dal terminale del Cloud Computer. Il comando stampa la stessa riga di testo dell'installer.

Nuovo link per creare l'account
sudo -u danaivatar-worker bash -c 'set -a; . /etc/danaivatar/danaivatar.env; . /etc/danaivatar/worker.env; set +a; cd /var/lib/danaivatar/work && exec /opt/danaivatar/venvs/core/bin/python -m danaivatar.worker account-link "$@"' _ --email tua@email.it

Password dimenticata

Stesso comando, con lo scopo reset. Il link apre la schermata «Imposta una nuova password»; quando salvi, le sessioni aperte sugli altri dispositivi si chiudono. Aggiungi --revoke-sessions se vuoi chiuderle subito, già all'emissione del link.

Link per reimpostare la password
sudo -u danaivatar-worker bash -c 'set -a; . /etc/danaivatar/danaivatar.env; . /etc/danaivatar/worker.env; set +a; cd /var/lib/danaivatar/work && exec /opt/danaivatar/venvs/core/bin/python -m danaivatar.worker account-link "$@"' _ --email tua@email.it --purpose reset

Controlla che tutto funzioni

Terminale del Cloud Computer
Servizi e pulizia periodica
systemctl is-active danaivatar-api danaivatar-worker danaivatar-seaweed caddy
systemctl list-timers danaivatar-janitor.timer --no-pager
Cosa devi vedere

Quattro righe active e il timer danaivatar-janitor.timer con la prossima esecuzione in programma.

Database e storage raggiungibili
curl -fsS http://127.0.0.1:8000/readyz; echo
Cosa devi vedere

{"status":"ready","checks":{"database":true,"storage":true}}. Se uno dei due è false, il comando termina con errore 503: guarda i problemi comuni.

HTTPS pubblico e revisione installata
curl -fsS -o /dev/null -w '%{http_code}\n' https://danaivatar.203-0-113-10.sslip.io/readyz
cat /opt/danaivatar/app/REVISION
Cosa devi vedere

200, che conferma certificato e proxy funzionanti, e lo stesso commit mostrato da git log -1 nella fase 3. Sul telefono, l'indirizzo del sito apre DanAivatar con l'avviso di sito in costruzione.

Consenso e primo video

Browser
Il consenso: un modulo, nessuna firma

La persona ritratta riceve un link personale, legge il modulo, sceglie che cosa autorizzare e lo invia: non serve alcuna firma. La dichiarazione arriva in «Da verificare» come PDF stampabile e tu, come Titolare, decidi se accettarla. Anche un personaggio sintetico richiede un consenso verificato all'uso dell'immagine.

  1. Prepara il soggetto. Nella scheda Soggetti registra la persona reale o il personaggio sintetico («Registra soggetto») e carica il ritratto.
  2. Chiedi il consenso. Nella scheda Consensi, sezione «Fai compilare il modulo di consenso», tocca «Crea il link del modulo», poi «Copia link» o «Condividi» e mandalo alla persona come preferisci, per esempio via WhatsApp o e-mail. Il link è personale e si usa una volta sola. Se hai già un modulo compilato, puoi caricarlo dalla stessa scheda.
  3. Valuta e approva. Quando la persona ha inviato il modulo, la dichiarazione compare in «Da verificare»: apri il PDF e, se ti va bene, tocca «Verifica». Il Titolare può approvare da solo; un Amministratore invece non può approvare un consenso caricato da lui.
  4. Crea il video. Per la prima prova scrivi una frase breve (il limite è di 300 caratteri) e tocca «Crea il video». Puoi chiudere la pagina e tornare più tardi: lo stato del lavoro resta salvato.
Quanto aspettare

In sviluppo una frase di circa 1,6 secondi ha richiesto circa 30 minuti con 5 thread. Sul Cloud Computer, con 2 vCPU, conta su tempi più lunghi. Se vuoi seguire l'elaborazione, usa sudo journalctl -u danaivatar-worker -f (esci con Ctrl+c).

Backup e aggiornamenti

Terminale del Cloud Computer

Backup

Crea un backup e conserva gli ultimi 7
sudo ~/DanAivatar/deploy/cloud-computer/backup.sh --keep 7

Lo script crea in /var/backups/danaivatar una cartella con il dump del database (db.dump), la configurazione con tutti i segreti (etc.tar.gz), i file dello storage (storage.tar.gz) e le impronte SHA256SUMS. Per copiare lo storage in modo coerente lo ferma durante la creazione di storage.tar.gz e poi lo riavvia: il fermo dura tanto più quanti più file ci sono. Fai i backup quando nessuno sta usando l'app. I pesi dei modelli non vengono copiati: si riscaricano con l'installer.

Due avvertenze

Il backup resta sullo stesso disco e contiene i segreti: portane una copia cifrata fuori dalla macchina. Il ripristino non è ancora stato provato su una macchina reale. In aggiunta, attiva le istantanee del Cloud Computer dalle impostazioni Manus: giornaliere, fino a 10.

Aggiornare a una nuova revisione

Scarica le novità e reinstalla
cd ~/DanAivatar
git pull
sudo deploy/cloud-computer/install.sh --owner-email tua@email.it

Nella riesecuzione l'account dell'owner esiste già: l'installer segnala l'errore account_exists e scrive (no link issued: …), ed è il comportamento atteso. Fai un backup prima di ogni aggiornamento.

Dove leggere i log

Ultime 100 righe di ciascun servizio
sudo journalctl -u danaivatar-api -n 100 --no-pager
sudo journalctl -u danaivatar-worker -n 100 --no-pager
sudo journalctl -u caddy -n 100 --no-pager

Problemi comuni

Messaggi reali dell'installer e dell'app
error: run as root (sudo)

Rilancia lo stesso comando con sudo davanti.

error: --owner-email is required

Manca l'opzione o l'indirizzo non è valido: aggiungi --owner-email tua@email.it con un'e-mail completa.

error: --domain and --s3-domain go together and must differ

Hai passato un solo nome, oppure due nomi uguali. Servono entrambi, diversi tra loro (fase 4), oppure nessuno dei due.

error: run from a checkout of the repository

Lo script non si trova dentro il repository scaricato. Usa quello in ~/DanAivatar/deploy/cloud-computer/, rifacendo la fase 3 se necessario.

warning: the checkout has uncommitted changes

Nel repository ci sono file modificati a mano, e la revisione registrata non corrisponderà al codice installato. Controlla con git status e ripristina con git stash, oppure riscarica il repository.

error: cannot determine the public IPv4; pass --domain/--s3-domain

La macchina non è riuscita a ricavare il proprio IP pubblico (servizio api.ipify.org). Controlla la connessione con curl -4 https://api.ipify.org, oppure usa un tuo dominio (opzione B).

error: checksum mismatch for …

Un file scaricato non corrisponde all'impronta attesa: download interrotto o alterato. Rilancia l'installer. Se l'errore si ripete, fermati: non aggirare il controllo, e segnala il nome del file.

error: unsupported architecture …

Il kit supporta solo amd64 e arm64, come i Cloud Computer Manus.

error: API not ready: journalctl -u danaivatar-api

L'API non ha risposto entro un minuto circa. Leggi la causa con sudo journalctl -u danaivatar-api -n 100 --no-pager; spesso database o storage non sono partiti, e systemctl is-active danaivatar-seaweed te lo conferma.

Il sito non si apre o il browser segnala un certificato non valido

Le porte 80 e 443 devono essere raggiungibili: controlla con sudo ufw status. Leggi i log di Caddy con sudo journalctl -u caddy -n 100 --no-pager. Con un tuo dominio, verifica che i due nomi puntino all'IP giusto (getent hosts …) e attendi la propagazione del DNS.

(no link issued: if the account already exists …)

Il link non è stato emesso. Se subito prima compare l'errore account_exists, l'account dell'owner esiste già, per esempio perché hai rilanciato l'installer: per entrare senza password usa il link di reimpostazione. Altrimenti leggi l'errore stampato subito prima, perché la stessa riga compare anche per altri problemi.

«Link non valido o già usato» oppure «Il link è scaduto»

Ogni link funziona una volta sola. I link per creare l'account o reimpostare la password, emessi dal terminale, durano 72 ore: rigenerali con il comando della fase 6. I link di invito a uno spazio durano 7 giorni: deve crearne uno nuovo chi ti ha invitato, dalla scheda Team, sezione «Invita una persona». Copia sempre l'indirizzo per intero, compresa la parte dopo #.

«L'invito è scaduto»

Gli inviti durano 7 giorni. Chi ti ha invitato ne crea uno nuovo dalla scheda Team, sezione «Invita una persona».

Troppi tentativi di accesso

Dopo 10 tentativi sbagliati l'account si blocca per 15 minuti. Attendi e riprova, oppure usa il link di reimpostazione.

Il consenso non si può verificare

Un Amministratore non può verificare un consenso che ha caricato lui: lo verifica il Titolare o un altro Amministratore. Il Titolare può verificare anche i propri. Vedi la fase 8.

Il video resta a lungo in elaborazione

Su CPU è normale: anche mezz'ora o più per una frase breve. Segui l'avanzamento con sudo journalctl -u danaivatar-worker -f.

Il video fallisce e il worker si riavvia

Probabilmente la memoria si è esaurita: cercalo con sudo journalctl -k | grep -i -E "out of memory|oom". Verifica di usare il taglio Advanced da 8 GB e di non aver attivato --with-voice-clone.

Limiti noti

Dal registro di revisione del repository
  • F-12, kit mai eseguito. install.sh è stato verificato solo staticamente: test di coerenza, ShellCheck, systemd-analyze verify e caddy validate. Conserva l'output della prima installazione: è il primo collaudo reale.
  • F-01, licenza della voce. La voce Kokoro ha un vincolo di licenza: la verifica di produzione la rifiuta, perciò l'istanza gira in modalità valutazione.
  • F-03, firma di provenienza. La firma C2PA è integra ma usa un certificato di sviluppo con una radice non attendibile.
  • F-08, velocità. 42–45 secondi per fotogramma con 5 thread in sviluppo; più lento sulle 2 vCPU del Cloud Computer.
  • Ripristino non provato. Lo script di backup esiste, ma il ripristino non è ancora stato provato su una macchina reale.

Dettagli e prove sono in docs/REVIEW-AND-TRACEABILITY.md e docs/PROGETTO.it.md nel repository, accessibile solo con autorizzazione.