Jamdesk Documentation logo

CLI Deploy

Saiba como o comando deploy da CLI do jamdesk empacota, envia e compila sua documentação, incluindo flags, fases de build e códigos de erro.

O comando deploy empacota sua documentação, envia para o Jamdesk e dispara um build pelo terminal. Use-o para iterações rápidas, testes de alterações ou projetos que não estão conectados a um repositório do GitHub.

Início rápido

jamdesk login        # First time only
jamdesk deploy       # From your project directory

Opções

FlagDescrição
--detachEnfileira o build e encerra imediatamente (exibe um link para o dashboard)
--full-rebuildForça um rebuild completo, ignorando o cache de build
--project <id>Faz o deploy para um ID de projeto específico (ignora a seleção interativa)
--allow-emptyPermite o deploy com zero páginas de conteúdo .mdx. Por padrão, a CLI recusa o deploy de um projeto vazio. Isso evita que um diretório de trabalho incorreto publique um site vazio. Snippets não contam como páginas de conteúdo
-m, --message <text>Mensagem de commit para alterações não commitadas em uma pasta criada por jamdesk pull (padrão: "Update docs")
--allow-secret-filesPublica arquivos cujos nomes parecem segredos, em uma pasta criada por jamdesk pull

jamdesk push é um alias para jamdesk deploy.

Como funciona

1
Autenticar

Verifica sua sessão. Um token expirado solicita que você execute jamdesk login.

2
Carregar configuração

Lê e valida o docs.json do diretório atual.

3
Resolver projeto

Lê o projectId do docs.json. Ele não existe no primeiro deploy. Nesse caso, a CLI pede que você escolha um projeto. A CLI salva sua escolha no docs.json. O próximo deploy pula essa etapa.

Use --project <id> para substituir.

4
Empacotar arquivos

Cria um tarball compactado da sua documentação. Arquivos listados no .gitignore ficam de fora. A CLI avisa sobre arquivos que parecem segredos. O aviso não bloqueia o envio.

5
Enviar

Envia o tarball para o Jamdesk por meio de uma URL pré-assinada. O tamanho máximo de envio é 100 MB.

6
Build

Enfileira um build e consulta o status periodicamente. Cada fase é exibida conforme é concluída. Pressione Ctrl+C para parar a consulta. O build continua em segundo plano.

7
Concluído

Exibe a URL ativa quando o build termina.

Projetos sem GitHub

Para um projeto cuja documentação é hospedada pelo Jamdesk (Documentação sem GitHub), você executa o deploy dentro da pasta criada por jamdesk pull. Nesse caso, o deploy pula as etapas de tarball descritas acima. Em vez disso, ele:

  1. Verifica suas alterações e recusa arquivos que não serão publicados, como arquivos .github, arquivos com aparência de segredo e arquivos com mais de 25 MB, antes de fazer qualquer commit.
  2. Faz commit das alterações não commitadas. Use -m para definir a mensagem.
  3. Envia os novos commits (até 100 MB), que o Jamdesk adiciona à sua documentação.
  4. Inicia um build e exibe cada fase.

O deploy funciona a partir de qualquer subpasta e nunca altera o docs.json. --full-rebuild e --allow-empty não se aplicam nessa pasta, e --project deve indicar o projeto próprio da pasta. Diferentemente do aviso em um deploy normal, um arquivo com aparência de segredo interrompe o deploy, a menos que você adicione --allow-secret-files.

Se o Jamdesk tiver alterações que você ainda não possui, feitas no Editor ou por um colega de equipe, o deploy para e mantém seu commit. Execute jamdesk pull e depois jamdesk deploy novamente. Consulte Editar no seu computador para conflitos e a lista completa de arquivos recusados.

ErroCódigoCorreção
O Jamdesk tem alterações que você ainda não possuiHOSTED_STALEjamdesk pull, depois jamdesk deploy
Nada foi publicadoPUSH_REFUSEDRemova ou corrija os arquivos listados e faça o deploy novamente
Um merge ou rebase não foi concluídoMERGE_IN_PROGRESSCorrija os conflitos e faça commit, ou execute git merge --abort
A pasta está no branch erradoWRONG_BRANCHgit switch para o branch indicado na mensagem
Não foi possível fazer commit das alteraçõesCOMMIT_FAILEDExecute git commit na pasta para ver o motivo
O Jamdesk não conseguiu confirmar a publicaçãoPUSH_UNCONFIRMEDjamdesk pull para verificar, depois faça o deploy novamente
O projeto não é mais hospedado pelo JamdeskNOT_HOSTEDEnvie para o seu repositório do GitHub com os comandos que o deploy exibir

Fases do build

A CLI exibe cada fase em ordem enquanto consulta o status:

FaseDescrição
Extraindo arquivosDescompactando o tarball enviado
Validando configuraçãoVerificando o schema e o conteúdo do docs.json
Preparando conteúdoProcessando arquivos MDX e recursos
Compilando documentaçãoCompilando páginas e gerando artefatos estáticos
Enviando para o CDNEnviando a saída compilada para a rede de borda
Atualizando o cacheRemovendo conteúdo desatualizado do CDN

Exclusões de arquivos

Estes itens são sempre excluídos dos envios, independentemente do que está no seu .gitignore:

.git, node_modules, .next, .env, .env.*, *.pem, *.key, credentials.json, .gcloud, .DS_Store, Thumbs.db

Tudo o que estiver no seu .gitignore também é excluído.

Avisos sobre arquivos secretos

A CLI avisa (mas não bloqueia) quando detecta arquivos que parecem segredos:

  • Arquivos .env e .env.*
  • Arquivos *.pem e *.key
  • credentials.json
  • service_account*.json
  • Arquivos que começam com secret

Adicione-os ao .gitignore para suprimir o aviso e excluí-los dos envios.

Referência de erros

ErroCódigoCausaCorreção
Não autenticadoAUTH_REQUIREDNenhuma credencial armazenadajamdesk login
Sessão expiradaAUTH_EXPIREDFalha na renovação do tokenjamdesk login
Acesso negadoFORBIDDENVocê não é membro deste projetoVerifique a participação no projeto no dashboard
Projeto não encontradoNOT_FOUNDID de projeto inválidoVerifique o ID ou remova o projectId do docs.json
Build em andamentoBUILD_IN_PROGRESSOutro build está em execuçãoAguarde ou verifique o dashboard
Envio muito grandeTOO_LARGEO servidor rejeitou o envio (limite de 100 MB)Exclua arquivos grandes via .gitignore
Projeto muito grandePROJECT_TOO_LARGEO tarball excede 100 MB durante o empacotamentoExclua arquivos grandes via .gitignore
Sem projetosNO_PROJECTSNão há projetos na sua contaCrie um projeto no dashboard primeiro
Sem arquivosEMPTY_PROJECTTodos os arquivos foram excluídosVerifique o .gitignore
Sem páginas de conteúdoNO_CONTENTNenhuma página de conteúdo .mdx encontrada (snippets não contam)Execute a partir do diretório da documentação ou use --allow-empty se a publicação vazia for intencional
Configuração inválidaCONFIG_NOT_FOUNDdocs.json ausente ou inválidoExecute a partir da raiz do projeto e verifique a configuração
Falha no envioUPLOAD_FAILEDProblema de rede durante o envioVerifique a conexão e tente novamente
Falha no buildBUILD_FAILEDErro do serviço de buildVerifique os logs de build no dashboard

Solução de problemas

Cada projeto executa um build por vez. Aguarde o build atual terminar. Verifique o status no dashboard, em Deployments.

Execute o comando a partir do diretório que contém o docs.json. Execute jamdesk validate para verificar erros de configuração.

O limite de 100 MB se aplica ao tarball compactado de todos os arquivos não excluídos. Imagens, vídeos ou arquivos de dados grandes são causas comuns. Adicione-os ao .gitignore para excluí-los.

Pressione Ctrl+C para sair. O build continua em execução em segundo plano. Verifique o dashboard para ver o status. Um travamento que se repete pode indicar que sua rede está derrubando as requisições de consulta.

Você precisa de pelo menos um projeto na sua conta do Jamdesk. Crie um em dashboard.jamdesk.com.

Para mais informações sobre solução de problemas da CLI, consulte o guia da CLI na Central de ajuda.

O que vem a seguir?

Fluxo de deploy

Deploy automático pelo GitHub e status do deploy

Autenticação

Fluxo de login, sessões e solução de problemas