Docker Next.js Local Deploy Skill

Purpose

Use this skill to build and run a Next.js application with Docker using a versioned image tag.

This skill must not hard-code the project name. Infer the image name from the current repository unless the user provides a specific name.

Project Name Resolution

Before building, determine these values:

text

PROJECT_NAME=<resolved project name>
IMAGE_NAME=<resolved image name>
IMAGE_VERSION=<resolved version>
IMAGE_TAG=${IMAGE_NAME}:${IMAGE_VERSION}
CONTAINER_NAME=<resolved container name>
ENV_FILE=<resolved env file>
HOST_PORT=<resolved host port>
CONTAINER_PORT=<resolved container port>

Resolution rules:

If the user provides an image name, use it.
Otherwise, read
```
package.json
```
and use the
```
name
```
field.
If
```
package.json
```
has no
```
name
```
, use the current folder name.
Normalize the image name:
- lowercase
- replace spaces and underscores with hyphens
- remove invalid Docker image name characters
If the user provides a version, use it.
Otherwise, default to
```
1.0.0
```
.
If the user provides a container name, use it.
Otherwise, use the normalized image name as the container name.
If the user provides an env file, use it.
Otherwise, default to
```
.env.production
```
.
If the user provides ports, use them.
Otherwise, default to
```
HOST_PORT=4000
```
and
```
CONTAINER_PORT=3000
```
.

Example:

text

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

Safety Rules

Before running any build or run command:

Confirm the current working directory is the project root.
Confirm
```
Dockerfile
```
exists.
Confirm the env file exists.
Confirm Docker is installed and running.
Check whether the requested image tag already exists locally.
Check whether the requested container name already exists.
Never print secrets from the env file.
Do not use the
```
latest
```
tag unless the user explicitly asks.

Do not run destructive cleanup commands such as:

```
docker system prune
```
```
docker image prune
```
```
docker volume prune
```

Do not stop, remove, or replace an existing container without explicit confirmation from the user.
Do not rebuild an existing version tag unless the user clearly confirms.

Preflight Checks

Run these checks first:

bash

pwd
ls -la

test -f package.json && echo "OK: package.json found" || echo "WARN: package.json not found"
test -f Dockerfile && echo "OK: Dockerfile found" || echo "ERROR: Dockerfile not found"
test -f "$ENV_FILE" && echo "OK: env file found: $ENV_FILE" || echo "ERROR: env file not found: $ENV_FILE"

docker --version
docker info >/dev/null && echo "OK: Docker daemon is running" || echo "ERROR: Docker daemon is not running"

Dockerfile

is missing, stop and report the issue.

If the env file is missing, stop and report the issue. Do not create a placeholder env file unless the user asks.

If Docker daemon is not running, stop and tell the user to start Docker Desktop or Docker Engine.

Suggested Helper Commands

To infer the image name from

package.json

bash

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

package.json

does not exist or has no

name

, use the current directory name:

bash

basename "$PWD"

To normalize a project name manually, use lowercase kebab-case.

Example:

text

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

Version Tag Check

Before building, check whether the requested image tag already exists:

bash

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

Also list existing local versions for this image:

bash

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

If the requested image tag already exists:

Do not run
```
docker build
```
.
Report that the version already exists locally.
Suggest the next patch version, such as
```
1.0.1
```
.
Ask the user whether to use a new version or explicitly rebuild the same tag.

Only rebuild an existing tag if the user clearly confirms.

Container Name Check

Before running the container, check whether the container name already exists:

bash

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

If a container with the same name already exists:

Do not run another container with the same name.
Report the existing container status.
Ask the user whether to stop/remove it or use a different container name.
Do not remove it automatically.

Build Command

If the image tag does not exist, run:

bash

docker build -t "$IMAGE_TAG" .

After build, verify the image exists:

bash

docker image inspect "$IMAGE_TAG" >/dev/null \
  && echo "OK: image built successfully: $IMAGE_TAG" \
  || echo "ERROR: image not found after build: $IMAGE_TAG"

Run Command

If the image exists and the container name is available, run:

bash

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

Post-run Validation

After running the container, validate with:

bash

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}"

Expected result:

Container status should be
```
Up
```
.
Port mapping should include
```
${HOST_PORT}->${CONTAINER_PORT}
```
.
Logs should not show fatal errors.
```
curl -I
```
should return an HTTP response such as
```
200
```
,
```
301
```
,
```
302
```
,
```
307
```
, or
```
308
```
.

curl

fails, inspect logs and report the likely cause.

Common Failure Handling

Image tag already exists

Report:

text

Image tag already exists locally:
<IMAGE_TAG>

Recommended action:
- Use a new patch version, such as 1.0.1
- Or explicitly confirm rebuilding the same tag

Container name already exists

Report:

text

Container already exists:
<CONTAINER_NAME>

Please confirm whether to stop/remove it, or provide a different container name.

Port already in use

Check:

bash

lsof -i :"$HOST_PORT"

Report the process using the port and ask whether the user wants to change

HOST_PORT

Env file missing

Report:

text

Env file was not found:
<ENV_FILE>

I cannot run the container with --env-file until this file exists.

Do not print or infer secrets.

Docker daemon not running

Report:

text

Docker is installed but the daemon is not running.
Start Docker Desktop or Docker Engine, then run the preflight checks again.

Final Response Format

When finished, report:

text

Result:
- Project: <PROJECT_NAME>
- Image: <IMAGE_TAG>
- Container: <CONTAINER_NAME>
- Env file: <ENV_FILE>
- Port: http://localhost:<HOST_PORT>
- Restart policy: always
- Validation: passed/failed

Commands used:
<list important commands>

Notes:
<any warnings, existing image/container conflicts, or follow-up action>

If the workflow stops because of an existing version tag, missing env file, existing container, Docker error, or port conflict, clearly state the blocking issue and the safest next command.

deploy-docker-production

NPX Install

Tags

SKILL.md Content

Docker Next.js Local Deploy Skill

Purpose

Project Name Resolution

Safety Rules

Preflight Checks

Suggested Helper Commands

Version Tag Check

Container Name Check

Build Command

Run Command

Post-run Validation

Common Failure Handling

Image tag already exists

Container name already exists

Port already in use

Env file missing

Docker daemon not running

Final Response Format