Deploy e CI/CD
1 O que é CI/CD
CI/CD (Continuous Integration / Continuous Delivery) é uma prática de automatizar a entrega de software. Em vez de fazer deploy manualmente, um pipeline executa automaticamente quando código é enviado ao repositório.
No contexto deste projeto: a cada push, o site é gerado e publicado automaticamente.
2 Como funciona o nosso pipeline
O arquivo .gitlab-ci.yml na raiz do repositório define o pipeline. Ele dispara em todo push para a branch knowledge-deploy e faz três coisas via SSH no servidor (VPS HOSTINGER):
push → GitLab CI → SSH no servidor → git pull → quarto render → nginx serve _site/
Passo a passo:
- O GitLab sobe um container Alpine e configura a conexão SSH com o servidor
- Conecta no servidor via SSH e executa:
git pull— puxa as mudanças do repositório- Se
install_packages.Rfoi modificado → instala pacotes R novos quarto render— gera o_site/com todos os HTMLs
- O nginx é reiniciado via
docker compose restart— necessário porque oquarto renderrecria o diretório_site/, quebrando o bind mount do container
2.1 Configuração SSH
Para conectar ao servidor, o pipeline usa uma chave SSH armazenada como variável no GitLab. As variáveis ficam em:
GitLab → Repositório → Settings → CI/CD → Variables
| Variável | Tipo | Descrição |
|---|---|---|
SSH_PRIVATE_KEY |
File | Chave privada SSH com acesso ao servidor |
SERVER_IP |
Variable | IP do servidor |
SERVER_USER |
Variable | Usuário SSH (root) |
SSH_PRIVATE_KEYdeve ser do tipo File — o GitLab cria um arquivo temporário com o conteúdo da chave, e a pipeline carrega esse arquivo no agente SSH.
2.2 R e Quarto no servidor
R e Quarto estão instalados diretamente no servidor. A pipeline renderiza lá mesmo, sem precisar de ambiente separado. A desvantagem é que o servidor faz tanto o trabalho de renderização quanto o de servir o site.
3 Como adicionar um documento ao site
- Criar o arquivo
.qmdemsrc/notebooks/ - Adicionar na sidebar do
_quarto.yml:
sidebar:
contents:
- section: "Minha Seção"
contents:
- src/notebooks/meu-documento.qmd- Commitar e fazer push para
knowledge-deploy - A pipeline renderiza e publica automaticamente
Para documentos puramente em markdown (sem código R), não é necessário nenhuma configuração adicional.
4 Notebooks com código R e dados externos
Notebooks que acessam dados externos (AWS, banco de dados, pacotes internos) não podem ser executados no servidor. Para esses casos existe o freeze.
Quando você roda quarto render arquivo.qmd localmente, o Quarto salva o resultado em _freeze/. Na pipeline, se esse cache existir, o Quarto usa o resultado salvo sem executar o código R.
Fluxo para notebooks com dados externos:
# 1. Localmente, com acesso aos dados:
quarto render src/notebooks/meu-arquivo.qmd
# 2. Commitar o cache:
git add _freeze/src/notebooks/meu-arquivo/
git commit -m "freeze: meu-arquivo"
git push origin knowledge-deploySe o
.qmdfor editado sem atualizar o freeze, a pipeline tentará executar o R e falhará. Sempre atualize o freeze antes de subir alterações nesses notebooks. Os notebooks que dependem de freeze estão listados no_quarto.yml.
5 Adicionando pacotes R
Para usar um pacote R novo em algum notebook, adicione-o ao vetor pacotes em install_packages.R e commite. A próxima pipeline detecta a mudança no arquivo e instala automaticamente apenas os pacotes faltantes no servidor.