CLI Deploy
Scopri come il comando CLI jamdesk deploy impacchetta, carica e compila la tua documentazione, con flag, fasi di build e codici di errore.
Il comando deploy impacchetta la tua documentazione, la carica su Jamdesk e avvia una build dal terminale. Usalo per iterazioni rapide, per testare modifiche o per progetti non collegati a un repository GitHub.
Avvio rapido
jamdesk login # First time only
jamdesk deploy # From your project directoryOpzioni
| Flag | Descrizione |
|---|---|
--detach | Mette in coda la build ed esce immediatamente (stampa un link alla dashboard) |
--full-rebuild | Forza una build completa, ignorando la cache di build |
--project <id> | Esegue il deploy su uno specifico ID progetto (salta la selezione interattiva) |
--allow-empty | Consente il deploy con zero pagine di contenuto .mdx. Per impostazione predefinita la CLI rifiuta il deploy di un progetto vuoto. Questo impedisce che una directory di lavoro errata pubblichi un sito vuoto. Gli snippet non contano come pagine di contenuto |
-m, --message <text> | Messaggio di commit per le modifiche non committate in una cartella creata da jamdesk pull (predefinito: "Update docs") |
--allow-secret-files | Pubblica i file i cui nomi sembrano segreti da una cartella creata da jamdesk pull |
jamdesk push è un alias di jamdesk deploy.
Come funziona
Verifica la tua sessione. Un token scaduto richiede di eseguire jamdesk login.
Legge e valida docs.json dalla directory corrente.
Legge projectId da docs.json. Manca al primo deploy. La CLI ti chiede quindi di scegliere un progetto. La CLI salva la tua scelta in docs.json. Il deploy successivo salta la richiesta.
Usa --project <id> per sovrascrivere.
Crea un tarball compresso della tua documentazione. I file presenti in .gitignore vengono esclusi. La CLI avvisa dei file che sembrano segreti. L'avviso non blocca il caricamento.
Invia il tarball a Jamdesk tramite un URL pre-firmato. La dimensione massima di caricamento è 100 MB.
Mette in coda una build e interroga lo stato. Ogni fase viene stampata al completamento. Premi Ctrl+C per interrompere l'interrogazione. La build continua in background.
Stampa l'URL live al termine della build.
Progetti senza GitHub
Per un progetto la cui documentazione è ospitata da Jamdesk (Documentazione senza GitHub), esegui deploy all'interno della cartella creata da jamdesk pull. Lì, deploy salta i passaggi del tarball descritti sopra. Esegue invece:
- Controlla le modifiche e rifiuta i file che non pubblicherà, come i file
.github, i file dall'aspetto segreto e i file oltre 25 MB, prima di committare qualsiasi cosa. - Committa le modifiche non committate. Usa
-mper impostare il messaggio. - Carica i nuovi commit (fino a 100 MB), che Jamdesk aggiunge alla tua documentazione.
- Avvia una build e mostra ogni fase.
Deploy funziona da qualsiasi sottocartella e non modifica mai docs.json. --full-rebuild e --allow-empty non si applicano in questa cartella, e --project deve indicare il progetto della cartella. A differenza dell'avviso di un deploy normale, un file dall'aspetto segreto interrompe il deploy a meno che tu non aggiunga --allow-secret-files.
Se Jamdesk ha modifiche che non hai ancora, dall'Editor o da un collega, deploy si ferma e conserva il tuo commit. Esegui jamdesk pull, poi di nuovo jamdesk deploy. Consulta Modifica sul tuo computer per i conflitti e l'elenco completo dei file rifiutati.
| Errore | Codice | Soluzione |
|---|---|---|
| Jamdesk ha modifiche che non hai ancora | HOSTED_STALE | jamdesk pull, poi jamdesk deploy |
| Nulla è stato pubblicato | PUSH_REFUSED | Rimuovi o correggi i file elencati, poi esegui di nuovo il deploy |
| Un merge o un rebase non è terminato | MERGE_IN_PROGRESS | Risolvi i conflitti e fai commit, oppure esegui git merge --abort |
| La cartella è sul branch sbagliato | WRONG_BRANCH | git switch al branch indicato nel messaggio |
| Impossibile committare le modifiche | COMMIT_FAILED | Esegui git commit nella cartella per vedere il motivo |
| Jamdesk non ha potuto confermare la pubblicazione | PUSH_UNCONFIRMED | jamdesk pull per verificare, poi esegui di nuovo il deploy |
| Il progetto non è più ospitato da Jamdesk | NOT_HOSTED | Esegui il push sul tuo repository GitHub con i comandi stampati da deploy |
Fasi della build
La CLI stampa ogni fase in ordine durante l'interrogazione:
| Fase | Descrizione |
|---|---|
| Estrazione dei file | Decompressione del tarball caricato |
| Validazione della configurazione | Verifica dello schema e del contenuto di docs.json |
| Preparazione dei contenuti | Elaborazione dei file MDX e degli asset |
| Build della documentazione | Compilazione delle pagine e generazione degli artefatti statici |
| Caricamento sulla CDN | Invio dell'output compilato alla rete edge |
| Aggiornamento della cache | Eliminazione dei contenuti obsoleti dalla CDN |
Esclusioni dei file
Questi elementi sono sempre esclusi dai caricamenti, indipendentemente da ciò che dice il tuo .gitignore:
.git, node_modules, .next, .env, .env.*, *.pem, *.key, credentials.json, .gcloud, .DS_Store, Thumbs.db
Anche tutto ciò che è nel tuo .gitignore viene escluso.
Avvisi sui file segreti
La CLI avvisa (senza bloccare) quando rileva file che sembrano segreti:
- File
.enve.env.* - File
*.peme*.key credentials.jsonservice_account*.json- File il cui nome inizia con
secret
Aggiungili a .gitignore per eliminare l'avviso ed escluderli dai caricamenti.
Riferimento degli errori
| Errore | Codice | Causa | Soluzione |
|---|---|---|---|
| Non autenticato | AUTH_REQUIRED | Nessuna credenziale memorizzata | jamdesk login |
| Sessione scaduta | AUTH_EXPIRED | Aggiornamento del token non riuscito | jamdesk login |
| Accesso negato | FORBIDDEN | Non sei membro di questo progetto | Verifica l'appartenenza al progetto nella dashboard |
| Progetto non trovato | NOT_FOUND | ID progetto non valido | Verifica l'ID o rimuovi projectId da docs.json |
| Build in corso | BUILD_IN_PROGRESS | Un'altra build è in esecuzione | Attendi o controlla la dashboard |
| Caricamento troppo grande | TOO_LARGE | Il server ha rifiutato il caricamento (limite 100 MB) | Escludi i file grandi tramite .gitignore |
| Progetto troppo grande | PROJECT_TOO_LARGE | Il tarball supera 100 MB durante l'impacchettamento | Escludi i file grandi tramite .gitignore |
| Nessun progetto | NO_PROJECTS | Nessun progetto nel tuo account | Crea prima un progetto nella dashboard |
| Nessun file | EMPTY_PROJECT | Tutti i file sono esclusi | Controlla .gitignore |
| Nessuna pagina di contenuto | NO_CONTENT | Nessuna pagina di contenuto .mdx trovata (gli snippet non contano) | Esegui dalla directory della documentazione, oppure usa --allow-empty se la pubblicazione vuota è intenzionale |
| Configurazione non valida | CONFIG_NOT_FOUND | docs.json mancante o non valido | Esegui dalla radice del progetto, verifica la configurazione |
| Caricamento fallito | UPLOAD_FAILED | Problema di rete durante il caricamento | Verifica la connessione e riprova |
| Build fallita | BUILD_FAILED | Errore del servizio di build | Controlla i log di build nella dashboard |
Risoluzione dei problemi
Ogni progetto esegue una build alla volta. Attendi che la build corrente termini. Controlla lo stato nella dashboard sotto Deployments.
Esegui il comando dalla directory che contiene docs.json. Esegui jamdesk validate per verificare la presenza di errori di configurazione.
Il limite di 100 MB si applica al tarball compresso di tutti i file non esclusi. Cause comuni sono immagini, video o file di dati di grandi dimensioni. Aggiungili a .gitignore per escluderli.
Premi Ctrl+C per uscire. La build continua in background. Controlla lo stato nella dashboard. Un blocco che si ripete può indicare che la rete interrompe le richieste di interrogazione.
Ti serve almeno un progetto nel tuo account Jamdesk. Creane uno su dashboard.jamdesk.com.
Per ulteriori indicazioni sulla risoluzione dei problemi della CLI, consulta la guida CLI del Centro assistenza.