thanatornPik/nextjs-skill-app-workshop

Habilidade de Deploy Local Next.js com Docker

Propósito

Use esta habilidade para construir e executar uma aplicação Next.js com Docker usando uma tag de imagem versionada.

Esta habilidade não deve codificar o nome do projeto. Deduza o nome da imagem a partir do repositório atual, a menos que o usuário forneça um nome específico.

Resolução do Nome do Projeto

Antes de construir, determine estes valores:

PROJECT_NAME=<nome do projeto resolvido>
IMAGE_NAME=<nome da imagem resolvido>
IMAGE_VERSION=<versão resolvida>
IMAGE_TAG=${IMAGE_NAME}:${IMAGE_VERSION}
CONTAINER_NAME=<nome do contêiner resolvido>
ENV_FILE=<arquivo de ambiente resolvido>
HOST_PORT=<porta do host resolvida>
CONTAINER_PORT=<porta do contêiner resolvida>

Regras de resolução:

1. Se o usuário fornecer um nome de imagem, use-o.
2. Caso contrário, leia o package.json e use o campo name.
3. Se o package.json não tiver name, use o nome da pasta atual.
4. Normalize o nome da imagem:
   • em minúsculas
   • substitua espaços e sublinhados por hífens
   • remova caracteres inválidos para nomes de imagem Docker
5. Se o usuário fornecer uma versão, use-a.
6. Caso contrário, use o padrão 1.0.0.
7. Se o usuário fornecer um nome de contêiner, use-o.
8. Caso contrário, use o nome da imagem normalizado como nome do contêiner.
9. Se o usuário fornecer um arquivo de ambiente, use-o.
10. Caso contrário, use o padrão .env.production.
11. Se o usuário fornecer portas, use-as.
12. Caso contrário, use os padrões HOST_PORT=4000 e CONTAINER_PORT=3000.

Exemplo:

package.json name: nextjs-skill-app-workshop

PROJECT_NAME=nextjs-skill-app-workshop
IMAGE_NAME=nextjs-skill-app-workshop
IMAGE_VERSION=1.0.0
IMAGE_TAG=nextjs-skill-app-workshop:1.0.0
CONTAINER_NAME=nextjs-skill-app-workshop
ENV_FILE=.env.production
HOST_PORT=4000
CONTAINER_PORT=3000

Regras de Segurança

Antes de executar qualquer comando de construção ou execução:

1. Confirme que o diretório de trabalho atual é a raiz do projeto.
2. Confirme que o Dockerfile existe.
3. Confirme que o arquivo de ambiente existe.
4. Confirme que o Docker está instalado e em execução.
5. Verifique se a tag da imagem solicitada já existe localmente.
6. Verifique se o nome do contêiner solicitado já existe.
7. Nunca imprima segredos do arquivo de ambiente.
8. Não use a tag latest a menos que o usuário peça explicitamente.
9. Não execute comandos de limpeza destrutivos como:
   • docker system prune
   • docker image prune
   • docker volume prune
10. Não pare, remova ou substitua um contêiner existente sem confirmação explícita do usuário.
11. Não reconstrua uma tag de versão existente a menos que o usuário confirme claramente.

Verificações de Pré-voo

Execute estas verificações primeiro:

pwd
ls -la

test -f package.json && echo "OK: package.json encontrado" || echo "AVISO: package.json não encontrado"
test -f Dockerfile && echo "OK: Dockerfile encontrado" || echo "ERRO: Dockerfile não encontrado"
test -f "$ENV_FILE" && echo "OK: arquivo de ambiente encontrado: $ENV_FILE" || echo "ERRO: arquivo de ambiente não encontrado: $ENV_FILE"

docker --version
docker info >/dev/null && echo "OK: daemon Docker está em execução" || echo "ERRO: daemon Docker não está em execução"

Se o Dockerfile estiver faltando, pare e relate o problema.

Se o arquivo de ambiente estiver faltando, pare e relate o problema. Não crie um arquivo de ambiente provisório a menos que o usuário peça.

Se o daemon Docker não estiver em execução, pare e diga ao usuário para iniciar o Docker Desktop ou o Docker Engine.

Comandos Auxiliares Sugeridos

Para deduzir o nome da imagem a partir do package.json:

node -p "require('./package.json').name"

Se o package.json não existir ou não tiver name, use o nome do diretório atual:

basename "$PWD"

Para normalizar manualmente um nome de projeto, use minúsculas com hífens (kebab-case).

Exemplo:

My Next App -> my-next-app
nextjs_skill_app -> nextjs-skill-app

Verificação de Tag de Versão

Antes de construir, verifique se a tag da imagem solicitada já existe:

docker image inspect "$IMAGE_TAG" >/dev/null 2>&1 \
  && echo "EXISTS: $IMAGE_TAG" \
  || echo "AVAILABLE: $IMAGE_TAG"

Liste também as versões locais existentes para esta imagem:

docker images "$IMAGE_NAME" --format "table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedSince}}\t{{.Size}}"

Se a tag da imagem solicitada já existir:

1. Não execute docker build.
2. Relate que a versão já existe localmente.
3. Sugira a próxima versão patch, como 1.0.1.
4. Pergunte ao usuário se deseja usar uma nova versão ou reconstruir explicitamente a mesma tag.

Apenas reconstrua uma tag existente se o usuário confirmar claramente.

Verificação de Nome do Contêiner

Antes de executar o contêiner, verifique se o nome do contêiner já existe:

docker ps -a --filter "name=^/${CONTAINER_NAME}$" \
  --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"

Se um contêiner com o mesmo nome já existir:

1. Não execute outro contêiner com o mesmo nome.
2. Relate o status do contêiner existente.
3. Pergunte ao usuário se deseja pará-lo/removê-lo ou usar um nome de contêiner diferente.
4. Não o remova automaticamente.

Comando de Construção

Se a tag da imagem não existir, execute:

docker build -t "$IMAGE_TAG" .

Após a construção, verifique se a imagem existe:

docker image inspect "$IMAGE_TAG" >/dev/null \
  && echo "OK: imagem construída com sucesso: $IMAGE_TAG" \
  || echo "ERRO: imagem não encontrada após construção: $IMAGE_TAG"

Comando de Execução

Se a imagem existir e o nome do contêiner estiver disponível, execute:

docker run --restart=always -d \
  --name "$CONTAINER_NAME" \
  --env-file "$ENV_FILE" \
  -p "${HOST_PORT}:${CONTAINER_PORT}" \
  "$IMAGE_TAG"

Validação Pós-execução

Após executar o contêiner, valide com:

docker ps --filter "name=^/${CONTAINER_NAME}$" \
  --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"

docker logs --tail=80 "$CONTAINER_NAME"

curl -I "http://localhost:${HOST_PORT}"

Resultado esperado:

1. O status do contêiner deve ser Up.
2. O mapeamento de portas deve incluir ${HOST_PORT}->${CONTAINER_PORT}.
3. Os logs não devem mostrar erros fatais.
4. curl -I deve retornar uma resposta HTTP como 200, 301, 302, 307 ou 308.

Se o curl falhar, inspecione os logs e relate a causa provável.

Tratamento de Falhas Comuns

Tag de imagem já existe

Relate:

A tag da imagem já existe localmente:
<IMAGE_TAG>

Ação recomendada:
- Use uma nova versão patch, como 1.0.1
- Ou confirme explicitamente a reconstrução da mesma tag

Nome do contêiner já existe

Relate:

O contêiner já existe:
<CONTAINER_NAME>

Por favor, confirme se deseja pará-lo/removê-lo ou forneça um nome de contêiner diferente.

Porta já em uso

Verifique:

lsof -i :"$HOST_PORT"

Relate o processo usando a porta e pergunte se o usuário deseja alterar HOST_PORT.

Arquivo de ambiente faltando

Relate:

O arquivo de ambiente não foi encontrado:
<ENV_FILE>

Não é possível executar o contêiner com --env-file até que este arquivo exista.

Não imprima ou deduza segredos.

Daemon Docker não está em execução

Relate:

O Docker está instalado, mas o daemon não está em execução.
Inicie o Docker Desktop ou o Docker Engine e, em seguida, execute as verificações de pré-voo novamente.

Formato da Resposta Final

Ao finalizar, relate:

Resultado:
- Projeto: <PROJECT_NAME>
- Imagem: <IMAGE_TAG>
- Contêiner: <CONTAINER_NAME>
- Arquivo de ambiente: <ENV_FILE>
- Porta: http://localhost:<HOST_PORT>
- Política de reinicialização: always
- Validação: passed/failed

Comandos usados:
<lista de comandos importantes>

Observações:
<quaisquer avisos, conflitos de imagem/contêiner existentes ou ação de acompanhamento>

Se o fluxo de trabalho parar devido a uma tag de versão existente, arquivo de ambiente faltando, contêiner existente, erro do Docker ou conflito de porta, indique claramente o problema bloqueador e o comando mais seguro a seguir.