MkDocs¶

O MkDocs é o sistema que gera e publica esta documentação operacional da VPS.

A interface utiliza o tema Material for MkDocs e os documentos são escritos em Markdown. O site é disponibilizado externamente pelo Traefik.

Informações desta VPS¶

Item	Valor
Stack	`/opt/stacks/mkdocs/compose.yml`
Serviço Compose	`mkdocs`
Container	`mkdocs`
Imagem	`squidfunk/mkdocs-material:latest`
MkDocs	`1.6.1`
Material for MkDocs	`9.7.7`
PyMdown Extensions	`11.0.1`
Pygments	`2.20.0`
Python	`3.11`
Domínio	`https://docs.cloud.hometecseg.com`
Porta interna	`8000`
Rede	`proxy`
Healthcheck	Não configurado
Política de reinício	`unless-stopped`

Arquivos principais¶

Arquivo ou diretório	Finalidade
`/opt/stacks/mkdocs/compose.yml`	Definição do container
`/opt/stacks/mkdocs/mkdocs.yml`	Configuração do site
`/opt/stacks/mkdocs/docs`	Arquivos Markdown
`/docs/docs`	Documentação dentro do container
`/docs/mkdocs.yml`	Configuração dentro do container
`/docs/site`	Site estático gerado pelo build

Estrutura atual¶

/opt/stacks/mkdocs/
├── compose.yml
├── mkdocs.yml
└── docs/
    ├── index.md
    ├── docker.md
    ├── traefik.md
    ├── n8n.md
    ├── postgres.md
    ├── redis.md
    ├── portainer.md
    ├── pgadmin.md
    ├── dozzle.md
    ├── kuma.md
    ├── mkdocs.md
    ├── scripts.md
    ├── security.md
    ├── backups.md
    ├── updates.md
    └── troubleshooting.md

Configuração atual¶

O site possui:

Idioma pt-BR
Navegação por abas
Seções na navegação
Botão para voltar ao topo
Rodapé de navegação
Sugestões de pesquisa
Destaque dos resultados de pesquisa
Botão para copiar código
Blocos de aviso
Tabelas
Blocos recolhíveis
Realce de sintaxe
Links permanentes nos títulos

Navegação¶

A navegação está dividida em:

Início

Infraestrutura
├── Docker
├── Traefik
├── Segurança
├── Backups
└── Atualizações

Serviços
├── n8n
├── PostgreSQL
├── Redis
├── Portainer
├── pgAdmin
├── Dozzle
├── Uptime Kuma
└── MkDocs

Operação
├── Scripts
└── Troubleshooting

Estado do serviço¶

Ver o estado¶

docker compose -f /opt/stacks/mkdocs/compose.yml ps -a

Ver somente o container¶

docker ps --filter name=mkdocs

Ver o estado detalhado¶

docker inspect mkdocs \
  --format 'Status={{.State.Status}} ExitCode={{.State.ExitCode}} StartedAt={{.State.StartedAt}} OOMKilled={{.State.OOMKilled}}'

Iniciar e parar¶

Iniciar¶

docker compose -f /opt/stacks/mkdocs/compose.yml start mkdocs

Caso o container ainda não exista:

docker compose -f /opt/stacks/mkdocs/compose.yml up -d mkdocs

Parar¶

docker compose -f /opt/stacks/mkdocs/compose.yml stop mkdocs

Reiniciar¶

docker compose -f /opt/stacks/mkdocs/compose.yml restart mkdocs

Recriar¶

docker compose -f /opt/stacks/mkdocs/compose.yml up -d --force-recreate mkdocs

Logs¶

Ver os últimos registros¶

docker logs mkdocs --tail 100

Acompanhar em tempo real¶

docker logs -f mkdocs

Procurar erros e avisos¶

docker logs mkdocs 2>&1 \
  | grep -Ei "error|fatal|exception|warning"

Versões instaladas¶

MkDocs¶

docker exec mkdocs mkdocs --version

Resultado registrado:

mkdocs, version 1.6.1

Material for MkDocs¶

docker exec mkdocs python -c \
"import importlib.metadata as m; print(m.version('mkdocs-material'))"

Resultado registrado:

9.7.7

Todos os componentes principais¶

docker exec mkdocs python -c \
"import importlib.metadata as m; \
pkgs=['mkdocs','mkdocs-material','pymdown-extensions','pygments']; \
[print(f'{p}={m.version(p)}') for p in pkgs]"

Resultado registrado:

mkdocs=1.6.1
mkdocs-material=9.7.7
pymdown-extensions=11.0.1
pygments=2.20.0

Estado das versões¶

Componente	Instalada	Mais recente verificada	Situação
MkDocs	`1.6.1`	`1.6.1`	Atualizado
Material for MkDocs	`9.7.7`	`9.7.7`	Atualizado

Verificação realizada em julho de 2026.

Informação temporal

A versão mais recente pode mudar. Consulte sempre os changelogs oficiais antes de atualizar.

Ciclo de vida do Material¶

O Material for MkDocs está em modo de manutenção.

Isso significa que:

Não deve receber novos recursos relevantes.
Deve receber apenas correções críticas e de segurança.
O fim de vida está programado para novembro de 2026.
Será necessário planejar uma migração futura.

O sucessor indicado pelo projeto é o Zensical.

Página oficial:

https://squidfunk.github.io/mkdocs-material/changelog/

Não migrar às cegas

A migração para outra ferramenta deve ser testada em uma cópia da documentação. O site atual está funcionando e não deve ser desmontado por entusiasmo migratório.

MkDocs 2.0¶

O Material for MkDocs 9.7.7 restringe o MkDocs para versões inferiores à 2.0.

O alerta exibido durante o build informa que o MkDocs 2.0 possui mudanças incompatíveis com:

Plugins existentes
Sobrescritas de tema
Configurações atuais
Fluxos de migração anteriores

Não instalar MkDocs 2.0

Não tente atualizar manualmente o MkDocs para a versão 2.0 dentro desta instalação.

A imagem atual mantém uma combinação compatível:

MkDocs 1.6.1
Material for MkDocs 9.7.7

Funcionamento atual¶

O Compose executa:

command: serve --dev-addr=0.0.0.0:8000

Isso inicia o servidor de desenvolvimento do MkDocs na porta 8000.

Características:

Detecta alterações nos arquivos.
Reconstrói o site automaticamente.
Atualiza os navegadores conectados.
Exibe alterações sem reiniciar o container.

Confirmar o comando¶

docker inspect mkdocs \
  --format '{{json .Config.Cmd}}'

Observação sobre produção¶

O comando mkdocs serve é destinado principalmente à edição e pré-visualização.

A arquitetura recomendada para uma publicação mais robusta é:

Executar mkdocs build.
Gerar o site estático em /docs/site.
Publicar os arquivos com Nginx, Caddy ou outro servidor HTTP.

A configuração atual funciona, mas mantém permanentemente:

Servidor de desenvolvimento
Monitoramento de arquivos
Live reload
Processo de reconstrução automática

Melhoria futura

A migração para publicação estática pode ser feita posteriormente, depois de documentada e testada. Não é necessário alterar agora.

Validar a documentação¶

Build normal¶

docker exec mkdocs mkdocs build

Build estrito¶

docker exec mkdocs mkdocs build --strict

O modo estrito transforma avisos de configuração e referências inválidas em falhas do build.

Resultado atual:

Documentation built successfully

O alerta referente ao MkDocs 2.0 é emitido pelo tema e não representa falha da documentação.

Editar uma página¶

Exemplo:

nano /opt/stacks/mkdocs/docs/mkdocs.md

Depois de salvar, o servidor detecta automaticamente a alteração.

Verificar nos logs¶

docker logs mkdocs --tail 30

Saída esperada:

Detected file changes
Building documentation...
Documentation built
Reloading browsers

Criar uma página¶

Criar o arquivo¶

nano /opt/stacks/mkdocs/docs/nova-pagina.md

Editar:

nano /opt/stacks/mkdocs/mkdocs.yml

Adicionar na seção desejada:

nav:
  - Operação:
      - Nova página: nova-pagina.md

Validar¶

docker exec mkdocs mkdocs build --strict

Excluir uma página¶

Antes de excluir, remova a referência correspondente no mkdocs.yml.

Depois:

rm /opt/stacks/mkdocs/docs/nome-da-pagina.md

Validar:

docker exec mkdocs mkdocs build --strict

Configuração YAML¶

Validar dentro do container¶

docker exec mkdocs mkdocs build --strict

Ver o arquivo¶

sed -n '1,260p' /opt/stacks/mkdocs/mkdocs.yml

Procurar tabulações¶

Arquivos YAML devem usar espaços, não tabulações:

grep -nP '\t' /opt/stacks/mkdocs/mkdocs.yml

Nenhuma saída significa que não foram encontradas tabulações.

Montagens¶

Os arquivos são montados diretamente do host:

Host	Container	Tipo	Escrita
`/opt/stacks/mkdocs/docs`	`/docs/docs`	Bind	Sim
`/opt/stacks/mkdocs/mkdocs.yml`	`/docs/mkdocs.yml`	Bind	Sim

Verificar¶

docker inspect mkdocs \
  --format '{{range .Mounts}}{{println .Type "|" .Source "|" .Destination "|" .RW}}{{end}}'

Escrita habilitada

O container possui acesso de escrita aos arquivos da documentação. Uma futura melhoria de segurança pode avaliar mounts somente leitura, desde que o funcionamento do MkDocs seja preservado.

Rede e Traefik¶

O container participa da rede externa:

proxy

O Traefik encaminha o domínio:

docs.cloud.hometecseg.com

para a porta interna:

Ver as redes¶

docker inspect mkdocs \
  --format '{{json .NetworkSettings.Networks}}'

Ver as labels¶

docker inspect mkdocs \
  --format '{{json .Config.Labels}}'

Testar o domínio¶

curl -I https://docs.cloud.hometecseg.com

Verificar DNS¶

getent hosts docs.cloud.hometecseg.com

Healthcheck¶

Atualmente não existe healthcheck:

Healthcheck=null

Confirmar¶

docker inspect mkdocs \
  --format '{{json .Config.Healthcheck}}'

Exemplo para avaliação futura¶

healthcheck:
  test:
    - CMD
    - wget
    - --spider
    - -q
    - http://localhost:8000/
  interval: 30s
  timeout: 10s
  retries: 5
  start_period: 30s

Ainda não aplicado

O exemplo precisa ser testado porque a disponibilidade do comando wget depende da imagem usada.

Backup¶

Como os dados são bind mounts, o backup deve incluir:

/opt/stacks/mkdocs/compose.yml
/opt/stacks/mkdocs/mkdocs.yml
/opt/stacks/mkdocs/docs

Criar diretório¶

mkdir -p /opt/backups/mkdocs

Criar backup completo¶

tar -czf \
  "/opt/backups/mkdocs/mkdocs-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C /opt/stacks mkdocs

Listar backups¶

ls -lh /opt/backups/mkdocs

Testar o arquivo¶

tar -tzf /opt/backups/mkdocs/mkdocs-*.tar.gz | head

Restaurar backup¶

Cuidado

Confirme o nome correto do arquivo antes de restaurar. A restauração pode substituir a documentação atual.

Parar o container¶

docker compose -f /opt/stacks/mkdocs/compose.yml stop mkdocs

Restaurar¶

tar -xzf /opt/backups/mkdocs/ARQUIVO_DO_BACKUP.tar.gz \
  -C /opt/stacks

Iniciar¶

docker compose -f /opt/stacks/mkdocs/compose.yml up -d mkdocs

Validar¶

docker exec mkdocs mkdocs build --strict

Atualização manual¶

Criar backup¶

mkdir -p /opt/backups/mkdocs

tar -czf \
  "/opt/backups/mkdocs/mkdocs-pre-update-$(date +%Y%m%d-%H%M%S).tar.gz" \
  -C /opt/stacks mkdocs

Validar o Compose¶

docker compose -f /opt/stacks/mkdocs/compose.yml config

Baixar a imagem mais recente¶

docker compose -f /opt/stacks/mkdocs/compose.yml pull mkdocs

Recriar o container¶

docker compose -f /opt/stacks/mkdocs/compose.yml up -d mkdocs

Ver os logs¶

docker logs mkdocs --tail 100

Confirmar versões¶

docker exec mkdocs mkdocs --version

docker exec mkdocs python -c \
"import importlib.metadata as m; print(m.version('mkdocs-material'))"

Validar toda a documentação¶

docker exec mkdocs mkdocs build --strict

Testar o domínio¶

curl -I https://docs.cloud.hometecseg.com

Fixar versão da imagem¶

Atualmente é utilizada:

image: squidfunk/mkdocs-material:latest

Para reduzir atualizações inesperadas, pode ser usada uma tag fixa:

image: squidfunk/mkdocs-material:9.7.7

Planejar antes

A alteração para tag fixa deve ser feita junto com um procedimento claro de atualização e rollback.

Rollback de imagem¶

Identificar imagens existentes¶

docker images squidfunk/mkdocs-material

Alterar temporariamente o Compose¶

nano /opt/stacks/mkdocs/compose.yml

Definir a tag anterior:

image: squidfunk/mkdocs-material:VERSAO_ANTERIOR

Recriar¶

docker compose -f /opt/stacks/mkdocs/compose.yml up -d mkdocs

Validar¶

docker exec mkdocs mkdocs build --strict

robots.txt¶

Os logs atuais mostram acessos a:

/robots.txt

com resposta:

Isso não quebra o site. Bots e mecanismos de busca procuram esse arquivo automaticamente.

Para criar um arquivo básico:

nano /opt/stacks/mkdocs/docs/robots.txt

Conteúdo exemplo:

User-agent: *
Disallow:

Depois, validar:

docker exec mkdocs mkdocs build --strict

O MkDocs copia arquivos não Markdown da pasta docs para o site gerado.

Troubleshooting¶

Site não abre¶

docker compose -f /opt/stacks/mkdocs/compose.yml ps -a

docker logs mkdocs --tail 200

curl -I https://docs.cloud.hometecseg.com

Erro 502 ou Gateway Timeout¶

docker ps --filter name=mkdocs

docker network inspect proxy

docker inspect mkdocs \
  --format '{{json .Config.Labels}}'

docker logs reverse-proxy-traefik-1 --tail 100

A porta interna esperada é:

Verifique se o arquivo existe:

ls -l /opt/stacks/mkdocs/docs

Verifique o nav:

sed -n '17,50p' /opt/stacks/mkdocs/mkdocs.yml

Valide:

docker exec mkdocs mkdocs build --strict

Alteração não aparece¶

docker logs mkdocs --tail 50

docker compose -f /opt/stacks/mkdocs/compose.yml restart mkdocs

Erro de YAML¶

docker exec mkdocs mkdocs build --strict

grep -nP '\t' /opt/stacks/mkdocs/mkdocs.yml

Verifique principalmente:

Indentação
Dois-pontos
Listas iniciadas por hífen
Nome e caminho dos arquivos
Espaços em vez de tabulações

Build falha¶

docker exec mkdocs mkdocs build --strict

docker logs mkdocs --tail 200

Container reiniciando¶

docker inspect mkdocs \
  --format 'Status={{.State.Status}} ExitCode={{.State.ExitCode}} OOMKilled={{.State.OOMKilled}} RestartCount={{.RestartCount}}'

docker stats mkdocs

Ver consumo de recursos¶

docker stats mkdocs

Ver espaço ocupado¶

du -sh /opt/stacks/mkdocs

du -sh /opt/stacks/mkdocs/docs

Boas práticas¶

Executar mkdocs build --strict após cada alteração importante.
Fazer backup antes de atualizar a imagem.
Não atualizar manualmente para MkDocs 2.0.
Considerar fixar a versão da imagem.
Planejar a migração antes do fim de vida do Material.
Manter o mkdocs.yml com indentação consistente.
Não remover arquivos ainda referenciados no menu.
Não expor credenciais na documentação.
Considerar publicação estática no futuro.
Considerar adicionar healthcheck.
Manter o site acessível apenas por HTTPS.

MkDocs¶

Informações desta VPS¶

Arquivos principais¶

Estrutura atual¶

Configuração atual¶

Navegação¶

Estado do serviço¶

Ver o estado¶

Ver somente o container¶

Ver o estado detalhado¶

Iniciar e parar¶

Iniciar¶

Parar¶

Reiniciar¶

Recriar¶

Logs¶

Ver os últimos registros¶

Acompanhar em tempo real¶

Procurar erros e avisos¶

Versões instaladas¶

MkDocs¶

Material for MkDocs¶

Todos os componentes principais¶

Estado das versões¶

Ciclo de vida do Material¶

MkDocs 2.0¶

Funcionamento atual¶

Confirmar o comando¶

Observação sobre produção¶

Validar a documentação¶

Build normal¶

Build estrito¶

Editar uma página¶

Verificar nos logs¶

Criar uma página¶

Criar o arquivo¶

Adicionar ao menu¶

Validar¶

Excluir uma página¶

Configuração YAML¶

Validar dentro do container¶

Ver o arquivo¶

Procurar tabulações¶

Montagens¶

Verificar¶

Rede e Traefik¶

Ver as redes¶

Ver as labels¶

Testar o domínio¶

Verificar DNS¶

Healthcheck¶

Confirmar¶

Exemplo para avaliação futura¶

Backup¶

Criar diretório¶

Criar backup completo¶

Listar backups¶

Testar o arquivo¶

Restaurar backup¶

Parar o container¶

Restaurar¶

Iniciar¶

Validar¶

Atualização manual¶

Criar backup¶

Validar o Compose¶

Baixar a imagem mais recente¶

Recriar o container¶

Ver os logs¶

Confirmar versões¶

Validar toda a documentação¶

Testar o domínio¶

Fixar versão da imagem¶

Rollback de imagem¶

Identificar imagens existentes¶

Alterar temporariamente o Compose¶

Recriar¶

Validar¶

robots.txt¶

Troubleshooting¶