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.
- Controlla di avere tuttoTaglio della macchina, accesso a GitHub, e-mail dell'owner
- Crea il Cloud Computer e apri il terminaleImpostazioni Manus, poi SSH
- Scarica il codice di DanAivatarGitHub CLI e repository privato
- Scegli l'indirizzo del sitoNomi automatici sslip.io oppure un tuo dominio
- Lancia l'installerUn solo comando, rieseguibile
- Attiva il primo ownerLink monouso, password, spazio di lavoro
- Controlla che tutto funzioniServizi, HTTPS, revisione installata
- Consenso e primo videoModulo online, approvazione del Titolare
Prima di iniziare
Nessun comando: solo controlli| Cosa serve | Dettagli |
|---|---|
| Cloud Computer Manus, taglio Advanced | 8 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 repository | Un account GitHub con accesso al repository privato ArabianLove/DanAivatar. |
| E-mail dell'owner | Diventa 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 browser | Sul 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). |
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- Apri la pagina Impostazioni → My Computer → Crea, scegli il taglio Advanced e conferma. Se hai già un Cloud Computer Advanced puoi usare quello.
- Nella stessa sezione delle impostazioni trovi i dati di accesso SSH: IP pubblico, utente
ubuntu, password e il comando SSH già pronto. - 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
lsb_release -ds; dpkg --print-architecture; nproc; free -h; df -h /
sudo ufw status
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 ComputerIl repository è privato: per scaricarlo autentichi la macchina con la GitHub CLI.
sudo apt-get update
sudo apt-get install -y git gh tmux
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.
gh repo clone ArabianLove/DanAivatar ~/DanAivatar
cd ~/DanAivatar
git checkout manus/danaivatar-implementation
git log -1 --oneline
L'ultima riga mostra il commit d20f7bb o uno più recente dello stesso ramo.
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 obbligatorioDanAivatar 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:
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 ComputerL'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.
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)
cd ~/DanAivatar
sudo deploy/cloud-computer/install.sh --owner-email tua@email.it
Con un tuo dominio (opzione B)
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
| Opzione | Effetto |
|---|---|
--owner-email | Obbligatoria. E-mail del primo owner: è l'unico account che potrà creare spazi di lavoro. |
--domain e --s3-domain | Il tuo dominio per il sito e per lo storage: vanno usati insieme e devono essere diversi. |
--skip-models | Salta 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-start | Non 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-clone | Aggiunge 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.
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 telefonoAlla fine dell'installazione il terminale mostra il link dell'owner in una riga di testo. Questo è un esempio, con un IP di documentazione:
== 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 …)
- Copia solo il valore di
url, dahttps://fino alla fine, compresa la parte#account=…. Intmuxpuoi scorrere l'output con Ctrl+b e poi [; esci con q. - Aprilo nel browser del telefono. Compare la schermata «Crea il tuo account», con la tua e-mail già compilata e non modificabile.
- 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».
- 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».
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.
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.
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 Computersystemctl is-active danaivatar-api danaivatar-worker danaivatar-seaweed caddy
systemctl list-timers danaivatar-janitor.timer --no-pager
Quattro righe active e il timer danaivatar-janitor.timer con la prossima esecuzione in programma.
curl -fsS http://127.0.0.1:8000/readyz; echo
{"status":"ready","checks":{"database":true,"storage":true}}. Se uno dei due è false, il comando termina con errore 503: guarda i problemi comuni.
curl -fsS -o /dev/null -w '%{http_code}\n' https://danaivatar.203-0-113-10.sslip.io/readyz
cat /opt/danaivatar/app/REVISION
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
BrowserLa 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.
- Prepara il soggetto. Nella scheda Soggetti registra la persona reale o il personaggio sintetico («Registra soggetto») e carica il ritratto.
- 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.
- 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.
- 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.
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 ComputerBackup
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.
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
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
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'apperror: 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 verifyecaddy 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.