Communitygithub.com

Nuvraxis/nuvraxis-plugins

Regras de Helm chart para apps Next.js da Nuvraxis — um chart por app em charts/, publicado em oci://ghcr.io/nuvraxis/charts e sincronizado pelo Argo CD.

O que é nuvraxis-plugins?

Este skill define o padrão para criação e gerenciamento de Helm charts em aplicações Next.js da Nuvraxis. O skill especifica que cada aplicação deve ter seu próprio chart dentro do diretório `charts/<app>` na raiz do repositório, garantindo que o chart seja versionado junto com o código-fonte e sincronizado pelo Argo CD a partir tanto do Git (para ambientes de desenvolvimento) quanto de um registro OCI (para produção). São estabelecidas regras rigorosas para não editar manualmente `version` ou `appVersion`, delegando essa tarefa ao pipeline de release, além de configurações obrigatórias como probes de startup/liveness/readiness no endpoint `/api/health`, contexto de segurança não-root com sistema de arquivos somente leitura, uso de `emptyDir` para o cache do Next.js, e variáveis de ambiente via ConfigMap e Secrets externos. O skill também cobre aspectos de alta disponibilidade com HPA, PDB, topology spread, e validação obrigatória dos charts com `helm lint --strict` e `kubeconform`, sendo indicado para repositórios que contenham a estrutura de Helm charts ou quando for solicitado implantar, escalar, expor ou configurar a aplicação no Kubernetes.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Nuvraxis/nuvraxis-plugins/tree/HEAD/plugins/nuvraxis-frontend/skills/helm-nextjs
Ver original→Navegar por todas as habilidades

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentação

Helm chart para uma aplicação Next.js

Use para charts/<app>/ e como o Argo CD o consome. A imagem executada vem de docker-nextjs; o pipeline que publica ambos é github-actions.

O modelo em charts/__APP__/ é a fonte da verdade. Todos os valores com comentários: references/values.md. Integração com Argo CD: references/argocd.md.

Regras

  1. Um chart por aplicação, em charts/<app>/ na raiz do repositório da aplicação. Por que lá: o Argo CD pode sincronizá-lo diretamente do Git (path: charts/<app>) para um ambiente de desenvolvimento e do registro OCI para produção, com os mesmos arquivos; está fora de apps/, portanto não está nem no contexto de build do Docker nem em um pacote do pnpm workspace; e o chart muda no mesmo PR que o código que precisa dele. O chart é propositalmente para uma única aplicação: sem umbrella, sem subcharts. Templates genéricos orientados a valores (como o chart umbrella de backend) apenas onde uma única aplicação precisa da alternância: ingress, HPA, PDB, topology spread.

  2. Nunca edite manualmente version ou appVersion. Ambos permanecem 0.0.0 no Git. O release.yaml executa helm package --version X.Y.Z --app-version vX.Y.Z a partir da tag vX.Y.Z, de modo que o chart publicado e a tag da imagem sempre correspondam.

  3. image.tag padrão é appVersion; defina-o apenas para ambientes sincronizados pelo Git. Pelo OCI, appVersion é a tag de release e a imagem é ghcr.io/nuvraxis/<app>:vX.Y.Z. Sincronizado pelo Git, appVersion é 0.0.0, então o Application do Argo CD define image.tag: sha-<short-sha> (ou main). image.repository é sempre minúsculo.

  4. Probes: startup, liveness e readiness, todas em /api/health. A probe startup (2s × 30) cobre a inicialização; liveness e readiness só iniciam depois dela. A rota nunca toca em uma dependência, portanto uma falha no banco de dados não reinicia os pods. Não aponte uma probe para /: isso renderiza uma página.

  5. Contexto de segurança corresponde à imagem: uid/gid 1001, runAsNonRoot, readOnlyRootFilesystem, sem escalonamento de privilégios, todas as capabilities removidas, seccomp RuntimeDefault. automountServiceAccountToken: false tanto no ServiceAccount quanto no pod: a aplicação não chama a API do Kubernetes.

  6. .next/cache é um emptyDir com sizeLimit. É o único caminho gravável (/app/apps/<app>/.next/cache). O limite evita que um cache de imagem descontrolado encha o nó.

  7. Configuração através de envFrom: um ConfigMap a partir de values.config, e um Secret que já existe.

    config:
  API_BASE_URL: https://api.nuvraxis.com
existingSecret: portal-secrets

    O chart nunca faz template de valores secretos: sem kind: Secret com data vindo de values, sem --set secret=…. O Secret é criado por External Secrets, Sealed Secrets ou um operador, e apenas seu nome está em values. Uma alteração no ConfigMap faz o rollout dos pods através da anotação checksum/config.

  8. Sem NEXT_PUBLIC_* no chart. Eles são incorporados no build da imagem (veja docker-nextjs); defini-los em tempo de execução não faz efeito.

  9. Recursos: requests para CPU e memória, um limite de memória, sem limite de CPU. Limites de CPU limitam um servidor Node durante picos e aumentam a latência; o limite de memória permanece porque o heap do Node cresce conforme o que é dado.

  10. Alta disponibilidade por padrão: 2 réplicas, PDB maxUnavailable: 1, atualização rolling com maxUnavailable: 0, restrições de topology spread entre zonas e nós (ScheduleAnyway). Com autoscaling.enabled, o Deployment omite replicas, para que o Argo CD e o HPA não entrem em conflito.

  11. Ingress é opt-in, TLS através de anotações do cert-manager. ingress.enabled, className, hosts, tls com secretName, e cert-manager.io/cluster-issuer nas anotações. Para respostas streaming no ingress-nginx, adicione nginx.ingress.kubernetes.io/proxy-buffering: "off"; para rate limiting, limit-rps (veja nextjs-security).

  12. Sem Helm hooks, sem lookup, sem valores aleatórios. O Argo CD renderiza o chart com helm template e aplica o resultado: hooks se tornam hooks do Argo com semântica diferente, lookup não retorna nada, e randAlphaNum muda a cada sincronização e mostra a aplicação permanentemente fora de sincronia. Tudo o que é renderizado deve ser uma função pura dos valores.

  13. Pacotes GHCR privados precisam de credenciais de pull. Pacotes GHCR são privados no primeiro push. Para imagens: um Secret docker-registry com um token que tenha read:packages, referenciado em imagePullSecrets (valores de produção referenciam ghcr-pull). Para o chart no Argo CD: um Secret de repositório com enableOCI: "true" (veja references/argocd.md). Ou torne os pacotes públicos no GitHub se o código for público.

  14. values-production.yaml contém apenas o que difere em produção. Faça a camada: -f values.yaml -f values-production.yaml. Não copie os padrões para ele.

  15. Valide com helm lint --strict e helm template | kubeconform -strict. Por que kubeconform em vez de helm-unittest: os bugs que um chart de aplicação única realmente tem são nomes de campos, tipos ou versões de API errados na saída renderizada, o que kubeconform detecta contra os schemas reais do Kubernetes com zero código de teste. O helm-unittest testa a lógica do template, que este chart mal tem. Valide lint e ambos os arquivos de valores, como faz pr.yaml.

Adicionando coisas

NecessidadeAlteração
Uma variável de ambiente em runtimeconfig: em values (não secreta) ou uma chave no Secret existente
Um segredoadicione-o ao Secret externo; nada no chart muda
Outra porta ou sidecarjustifique primeiro; uma aplicação Next precisa de uma porta
Um cron jobum chart ou aplicação separada, não este Deployment
NetworkPolicyadicione templates/networkpolicy.yaml, ativado por networkPolicy.enabled

Verificar

helm lint --strict charts/<app>
helm lint --strict charts/<app> -f charts/<app>/values-production.yaml
helm template <app> charts/<app> -f charts/<app>/values-production.yaml \
  | docker run --rm -i ghcr.io/yannh/kubeconform:v0.8.0 -strict -summary -kubernetes-version 1.34.0 -

Fontes

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

Nuvraxis/nuvraxis-plugins

>- Biome 2.5 setup and rules for Nuvraxis monorepos — root biome.json with pinned $schema, VCS ignore, formatter settings, the recommended preset with a11y and the react/next domains, nursery policy, organize imports, overrides, nested per-package configs ("extends": "//"), biome check --write locally, biome ci in CI, VS Code settings, and migrating from ESLint/Prettier. Use when the repo has biome.json or biome.jsonc, @biomejs/biome in package.json, .eslintrc*/eslint.config.*/.prettierrc* to migrate, or when fixing lint and formatting errors.

Nuvraxis/nuvraxis-plugins

>- Dockerfile rules for Next.js standalone apps in a pnpm + Turborepo monorepo — multi-stage build (turbo prune → pnpm fetch/offline install → turbo build → minimal runner), pinned Node 26 Alpine by digest, checksum-verified pnpm binary, non-root uid 1001, read-only root filesystem with a writable .next/cache, HEALTHCHECK on /api/health, build args only for NEXT_PUBLIC_* values, BuildKit secrets and cache mounts, multi-arch, OCI labels and .dockerignore. Use when the repo has a Dockerfile, .dockerignore, compose file, or next.config with output "standalone", or when asked to containerise, shrink, harden or debug an image.

Nuvraxis/nuvraxis-plugins

>- GitHub Actions conventions for Nuvraxis Next.js apps — exactly three workflows: pr.yaml (every PR to any branch: Biome, stylelint, typecheck/test/build with turbo --affected, Docker build + health check, helm lint + kubeconform; publishes nothing), main.yaml (push to main: one multi-arch image to GHCR tagged sha-SHORTSHA and main, provenance + SBOM, gha cache), release.yaml (tag vX.Y.Z: verify on main, retag the existing image without rebuilding, package and push the Helm chart to OCI, GitHub Release with chart, digest and SBOM). Minimal permissions per job, GITHUB_TOKEN only, pinned action majors. Use when editing .github/workflows/*, adding a CI step, or debugging a failed run or release.

Nuvraxis/nuvraxis-plugins

>- Production rules for Next.js 16 App Router apps at Nuvraxis — Server/Client Component boundaries, Cache Components ("use cache", cacheLife, cacheTag, updateTag), Server Actions, route handlers, env handling, instrumentation, output standalone and the /api/health route. Use when the project has "next" in package.json, an app/ or src/app/ directory, next.config.ts, proxy.ts, instrumentation.ts, or files named page.tsx, layout.tsx, route.ts, loading.tsx, error.tsx.

Habilidades Relacionadas

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community