Compilação e Deploy da Documentação em Produção

Este guia descreve o processo completo para compilar a documentação técnica da SSSI e publicá-la em produção utilizando VitePress, Docker e GitLab Container Registry.

Visão Geral do Fluxo

O processo segue uma abordagem padronizada de versionamento e containerização:

Desenvolvimento Local: Editar e validar as páginas .md localmente
Commit e Preparação: Fazer commit das mudanças no Git
Versionamento: Criar uma tag Git (seguindo semver)
Build Docker: Compilar a imagem com o conteúdo gerado
Registry: Enviar a imagem para o GitLab Container Registry
Deploy: Atualizar o serviço em produção

Pré-Requisitos

Antes de começar, verifique se possui:

Node.js 20.x ou superior
Docker e Docker buildx configurados
Git com acesso ao repositório
Credenciais de Acesso ao GitLab Container Registry (registry.pm.df.gov.br)
Acesso para executar comandos no servidor de produção

Etapa 1: Desenvolvimento Local

Instalação de Dependências

bash

npm install

Servidor de Desenvolvimento

Para visualizar mudanças em tempo real:

bash

npm run docs:dev

O servidor estará disponível em http://localhost:5173 (ou conforme outputado).

Estrutura de Arquivos

Páginas: Criar/editar arquivos .md nos diretórios temáticos (servicos/, processos/, monitoramento/, seguranca/, etc.)
Imagens: Armazenar em images/ com subpastas organizadas (images/kubernetes/, images/active-directory/, etc.)
Configuração: Arquivo .vitepress/config.mts contém navegação, temas e metadados

Como Usar a Skill VitePress

Se precisar criar ou melhorar páginas de documentação, use a Skill VitePress Docs. Ela automatiza a criação de conteúdo técnico bem estruturado, com suporte a frontmatter, containers de aviso e exemplos de código.

Etapa 2: Validação e Commit

Validar Sintaxe Markdown

Verifique visualmente no servidor de desenvolvimento se:

Todos os links internos funcionam
Código-fonte está corretamente formatado com highlights
Imagens carregam corretamente

Fazer Commit

bash

git add .
git commit -m "docs: atualizar documentação de [módulo/serviço]"
git push origin main

Padrão de Mensagens

Prefira mensagens descritivas: docs:, feat:, fix:, chore: conforme Conventional Commits.

Etapa 3: Compilação Local (Opcional)

Para testar a compilação final antes de enviar para produção:

bash

npm run docs:build

Isto gera a documentação estática em .vitepress/dist/. Você pode visualizar localmente com:

bash

npm run docs:preview

Etapa 4: Criar Versão e Fazer Tag

Após validar o conteúdo localmente, crie uma versão seguindo Semantic Versioning (MAJOR.MINOR.PATCH):

bash

# Exemplo: Para versão 1.2.3
git tag -a v1.2.3 -m "Documentação versão 1.2.3"
git push origin v1.2.3

Guia rápido de versionamento:

v1.0.0 → Primeira versão em produção (MAJOR release)
v1.1.0 → Novas seções ou conteúdo significativo (MINOR)
v1.0.1 → Correções ortográficas ou pequenas atualizações (PATCH)

Não Reutilize Tags

Uma vez criada e enviada, uma tag é imutável. Se errar, crie uma nova tag e marque a anterior como deprecated.

Etapa 5: Build e Push Automático

Use o script build-and-push.sh para automatizar a compilação, versionamento e envio para o registry:

bash

./build-and-push.sh v1.2.3

Este script realiza:

Git Tagging: Cria a tag v1.2.3 localmente e a envia para o repositório
Docker Build: Constrói a imagem Docker com:
- VitePress compilando o conteúdo .md
- Variáveis de ambiente injetadas (Keycloak)
- Base Nginx Alpine para produção
Registry Push: Envia tanto v1.2.3 quanto latest para registry.pm.df.gov.br/sss/docs-sss

Configurações do Script

No arquivo build-and-push.sh, ajuste conforme sua infraestrutura:

bash

REGISTRY="registry.pm.df.gov.br"           # Registry do GitLab
IMAGE_NAME="sss/docs-sss"                  # Namespace/Projeto

E as variáveis de ambiente Keycloak:

bash

--build-arg VITE_KEYCLOAK_URL="https://auth2.policia.df.gov.br/"
--build-arg VITE_KEYCLOAK_REALM="pmdf-hml"
--build-arg VITE_KEYCLOAK_CLIENT_ID="docs-ceti"

Build com BuildX

O script usa docker build --provenance=false --push, otimizado para push direto ao registry sem armazenar localmente.

Etapa 6: Deploy em Produção

Após o push bem-sucedido, a imagem estará disponível no registry. Existem duas formas de fazer deploy:

Opção 1: Docker Compose (Simples)

No servidor de produção, atualize o docker-compose.yml:

yaml

services:
  docs-secao:
    image: registry.pm.df.gov.br/sss/docs-sss:v1.2.3  # ou :latest
    restart: always
    ports:
      - "8080:80"
    environment:
      - VITE_KEYCLOAK_URL=https://auth2.policia.df.gov.br/
      - VITE_KEYCLOAK_REALM=pmdf-hml
      - VITE_KEYCLOAK_CLIENT_ID=docs-ceti

Em seguida, execute:

bash

docker-compose up -d

Opção 2: Kubernetes (Recomendado para Alta Disponibilidade)

Crie um Deployment que referencie a nova imagem:

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: docs-sssi
  namespace: pmdf-docs
spec:
  replicas: 3
  selector:
    matchLabels:
      app: docs-sssi
  template:
    metadata:
      labels:
        app: docs-sssi
    spec:
      containers:
      - name: docs
        image: registry.pm.df.gov.br/sss/docs-sss:v1.2.3
        ports:
        - containerPort: 80
        env:
        - name: VITE_KEYCLOAK_URL
          value: "https://auth2.policia.df.gov.br/"
        - name: VITE_KEYCLOAK_REALM
          value: "pmdf-hml"
        - name: VITE_KEYCLOAK_CLIENT_ID
          value: "docs-ceti"
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /
            port: 80
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /
            port: 80
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: docs-sssi-svc
  namespace: pmdf-docs
spec:
  selector:
    app: docs-sssi
  type: LoadBalancer
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80

Aplique com:

bash

kubectl apply -f docs-deployment.yaml

Para atualizar a versão, basta alterar a tag da imagem e reaplicar.

Etapa 7: Validação Pós-Deploy

Após o deploy, valide:

Acesso HTTP:
bash
```
curl -I https://docs.seu-dominio.com.br
```
Autenticação Keycloak: Verifique se o login funciona
Conteúdo: Acesse a página no navegador e confirme que todo o conteúdo está acessível

Logs:

bash

# Docker Compose
docker-compose logs -f docs-secao

# Kubernetes
kubectl logs -f deployment/docs-sssi -n pmdf-docs

Monitoramento

Integre a aplicação ao Zabbix e Wazuh conforme política de monitoramento da SSSI para alertar sobre indisponibilidades.

Rollback em Caso de Falha

Se o novo deploy causa problemas, reverta rapidamente para a versão anterior:

Docker Compose

bash

# Verifique a versão anterior
docker images | grep docs-sss

# Atualize o compose para a versão anterior
# docker-compose.yml: image: registry.pm.df.gov.br/sss/docs-sss:v1.2.2
docker-compose up -d --no-deps --build docs-secao

Kubernetes

bash

# Reverta para a revisão anterior
kubectl rollout undo deployment/docs-sssi -n pmdf-docs

# Ou especifique uma revisão
kubectl rollout history deployment/docs-sssi -n pmdf-docs
kubectl rollout undo deployment/docs-sssi --to-revision=2 -n pmdf-docs

Variáveis de Ambiente

A tabela abaixo descreve as variáveis usadas durante o build e em produção:

Variável	Descrição	Exemplo
`VITE_KEYCLOAK_URL`	URL base do servidor Keycloak	`https://auth2.policia.df.gov.br/`
`VITE_KEYCLOAK_REALM`	Realm (domínio) no Keycloak	`pmdf-hml`
`VITE_KEYCLOAK_CLIENT_ID`	ID do cliente registrado no Keycloak	`docs-ceti`
`NODE_ENV`	Ambiente de execução	`production`

Variáveis Sensíveis

Não commite credenciais ou tokens no repositório. Use arquivos .env.production no servidor local e injete via secrets do Kubernetes ou variáveis do docker-compose.

Troubleshooting

Erro: "Docker image not found"

Verifique credenciais do GitLab Registry: docker login registry.pm.df.gov.br
Confirme que o push foi bem-sucedido: docker images | grep docs-sss

Erro: "Keycloak variables not found"

Adicione as variáveis de build ao script build-and-push.sh
Verifique se as variáveis estão exportadas como ENV no Dockerfile

Página em branco no navegador

Verifique os logs da aplicação
Confirme que VitePress compilou corretamente (verificar .vitepress/dist/)
Valide a configuração de Nginx no container

Certificado HTTPS expirado

Se usar HTTPS, atualize o certificado no loadbalancer (Kubernetes) ou proxy reverso (Docker Compose)
Integre com Let's Encrypt ou sua autoridade certificadora

Estrutura Completa do Dockerfile

Para referência, o Dockerfile usa multi-stage build:

dockerfile

# Stage 1: Build
FROM node:20-alpine AS build-stage
WORKDIR /app

ARG VITE_KEYCLOAK_URL
ARG VITE_KEYCLOAK_REALM
ARG VITE_KEYCLOAK_CLIENT_ID

ENV VITE_KEYCLOAK_URL=$VITE_KEYCLOAK_URL
ENV VITE_KEYCLOAK_REALM=$VITE_KEYCLOAK_REALM
ENV VITE_KEYCLOAK_CLIENT_ID=$VITE_KEYCLOAK_CLIENT_ID

COPY package*.json ./
RUN npm install
COPY . .
RUN npm run docs:build

# Stage 2: Produção (Nginx)
FROM nginx:alpine
COPY --from=build-stage /app/.vitepress/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Esta arquitetura reduz o tamanho da imagem final removendo dependências de build.

Checklist de Deploy

Antes de fazer cada release, verifique:

[ ] Todas as mudanças foram commitadas e pusheadas
[ ] A tag foi criada com formato correto (v1.2.3)
[ ] npm run docs:build executa sem erros localmente
[ ] As variáveis de ambiente Keycloak estão corretas
[ ] O script build-and-push.sh foi executado com sucesso
[ ] A imagem aparece no GitLab Container Registry
[ ] O deployment em produção foi atualizado com a nova versão
[ ] O site está acessível e funcional
[ ] Links internos, autenticação e conteúdo foram validados
[ ] Logs mostram nenhum erro crítico

Compilação e Deploy da Documentação em Produção ​

Visão Geral do Fluxo ​

Pré-Requisitos ​

Etapa 1: Desenvolvimento Local ​

Instalação de Dependências ​

Servidor de Desenvolvimento ​

Estrutura de Arquivos ​

Etapa 2: Validação e Commit ​

Validar Sintaxe Markdown ​

Fazer Commit ​

Etapa 3: Compilação Local (Opcional) ​

Etapa 4: Criar Versão e Fazer Tag ​

Etapa 5: Build e Push Automático ​

Configurações do Script ​

Etapa 6: Deploy em Produção ​

Opção 1: Docker Compose (Simples) ​

Opção 2: Kubernetes (Recomendado para Alta Disponibilidade) ​

Etapa 7: Validação Pós-Deploy ​

Rollback em Caso de Falha ​

Docker Compose ​

Kubernetes ​

Variáveis de Ambiente ​

Troubleshooting ​

Erro: "Docker image not found" ​

Erro: "Keycloak variables not found" ​

Página em branco no navegador ​

Certificado HTTPS expirado ​

Estrutura Completa do Dockerfile ​

Checklist de Deploy ​

Referências ​

Compilação e Deploy da Documentação em Produção

Visão Geral do Fluxo

Pré-Requisitos

Etapa 1: Desenvolvimento Local

Instalação de Dependências

Servidor de Desenvolvimento

Estrutura de Arquivos

Etapa 2: Validação e Commit

Validar Sintaxe Markdown

Fazer Commit

Etapa 3: Compilação Local (Opcional)

Etapa 4: Criar Versão e Fazer Tag

Etapa 5: Build e Push Automático

Configurações do Script

Etapa 6: Deploy em Produção

Opção 1: Docker Compose (Simples)

Opção 2: Kubernetes (Recomendado para Alta Disponibilidade)

Etapa 7: Validação Pós-Deploy

Rollback em Caso de Falha

Docker Compose

Kubernetes

Variáveis de Ambiente

Troubleshooting

Erro: "Docker image not found"

Erro: "Keycloak variables not found"

Página em branco no navegador

Certificado HTTPS expirado

Estrutura Completa do Dockerfile

Checklist de Deploy

Referências