AI Assist Dockerize Website

Dockerize a Website

This skill is invoked manually — only when the user explicitly runs /ai-assist-dockerize-website. Don't auto-trigger it from general talk about Docker, containers, or websites.

Guide the user from a project folder to a working Docker container that serves their site or documentation. The skill is interactive and guided, not a one-shot script: inspect the project, propose a sensible plan, confirm a few details, generate the files, then offer to build/test and publish.

The spine is: detect → confirm → generate → offer to test → offer to publish. Lead with a good default at every step so the user is confirming, not configuring from scratch.

When to use

Use this whenever the user wants to serve a static website or a documentation folder out of a container — loose HTML/CSS/JS, the build output of a site generator, or a folder of markdown docs. The "project with a docs folder" case is the bullseye.

Out of scope — dynamic apps

This skill serves static content. If the project is a dynamic app that runs code per request — an Express/Fastify/Nest server, Next.js in SSR mode, Flask/Django/FastAPI, a Go/Rust web server, anything with a long-running start/serve process and a port it listens on — stop and say so plainly. Containerizing those means basing the image on the app's own runtime and running its start command, which is a different job. Detect this case (see below), tell the user, and don't half-build a static image that won't actually run their app.

Don't leave them stranded, though. After declining, offer a real next step: a correct container for a dynamic app is based on the app's own runtime (e.g. node:22-alpine), installs its dependencies, runs the start command, and exposes the port the app listens on. Offer to hand-write that separately — it's just outside this skill's static-hosting scope.

Step 1 — Inspect and classify the project

Before asking anything, look at what's there so the proposal is concrete. If the user named a folder (argument or in their message), focus on it; otherwise scan the working directory.

Classify into one of four strategies:

State your finding in one line — e.g. "Found a built site in dist/ with an index.html, so I'll serve it directly with nginx (strategy A)." — and let the user correct you if the detection is off.

For strategy B and C, the build/render details live in references/recipes.md. Read that file when you land on those paths — it has the multi-stage Dockerfiles per generator (Node SSGs, MkDocs, Hugo, Jekyll), the SPA fallback config, the raw-markdown render path, caching headers, the non-root variant, and a Caddy alternative.

Step 2 — Confirm the details

Pre-fill every answer from Step 1 so these are quick confirmations, not an interrogation:

• What to serve — the folder (strategy A) or the build output directory (strategy B/C). Show the path you detected.
• Port — what host port to expose. Default 8080 (avoids clashing with anything already on 80). Honor --port if given.
• Image / container name — propose one lowercase-hyphenated name for both. Default to the project folder name, but prefer a more meaningful name when one is obvious — a package.json name, or a clear title in the README — e.g. favor marketing-site over a generic folder like app or vite-app. Always let the user override.
• Compose? — yes by default (one-command up/down). Mention they can skip it.
• For strategy C, confirm they want the docs rendered (recommended — browsers download raw .md instead of displaying it) versus served as raw files.

Skip questions whose answers are obvious or already given. The user invited a guided flow, not a form.

Step 3 — Generate the artifacts

Generate all of these, tailored to the chosen strategy. Substitute the real folder, port, and names — don't leave placeholders in the files you write.

Dockerfile (strategy A — ready static)

# syntax=docker/dockerfile:1
FROM nginx:1.27-alpine

# Copy the site into nginx's web root.
COPY <SITE_DIR>/ /usr/share/nginx/html/

EXPOSE 80

# Fail the container's health check if nginx stops serving.
# busybox wget ships in the alpine image, so no extra install is needed.
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
  CMD wget -q --spider http://localhost/ || exit 1

Pin the base image to a real minor tag (e.g. nginx:1.27-alpine) rather than the floating nginx:alpine, so a rebuild months from now doesn't silently pull a different nginx. Mention this so the user knows to bump it deliberately.

The build context is the project root (compose uses build: .), so COPY paths are relative to it: copy the served folder by its path from the root — COPY public/ … when the site lives in public/, or COPY . … when the site is the project root (then lean on .dockerignore to keep junk out).

For strategy B/C, use the matching multi-stage Dockerfile from references/recipes.md — a builder stage runs the generator, and only its static output is copied into the nginx stage, so build tooling never ships in the final image.

.dockerignore

Keep the build context small and the image clean:

.git
.gitignore
node_modules
npm-debug.log*
.env
.env.*
.DS_Store
Thumbs.db
Dockerfile*
.dockerignore
docker-compose*.yml

Tailor it to the project. For a multi-stage build (strategy B/C), also ignore the local build-output directory (dist, build, _site, out, site, …) — it's regenerated inside the image, and shipping a stale host copy into the build context only bloats it. The "don't ignore your content" rule is about source you serve directly (strategy A), not generated output.

docker-compose.yml

services:
  web:
    build: .
    image: <IMAGE_NAME>:latest
    container_name: <CONTAINER_NAME>
    ports:
      - "<HOST_PORT>:80"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost/"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

No top-level version: key — it's obsolete in Compose v2 and prints a warning.

Helper commands + README section

Append a "Running with Docker" section to the project's README.md (or create a short DOCKER.md if there's no README). The commands are identical in PowerShell and bash, so no per-shell variants are needed.

The block below is the template; its outer 4-backtick fence is only the boundary so the inner blocks display here. When you write the actual file, use normal 3-backtick fences for the bash blocks — don't copy the 4-backtick wrapper.

## Running with Docker

This site is served by nginx in a container.

### Quick start (Docker Compose)

```bash
docker compose up -d --build      # build the image and start in the background
# open http://localhost:<HOST_PORT>
docker compose logs -f            # follow logs
docker compose down               # stop and remove
```

### Without Compose

```bash
docker build -t <IMAGE_NAME> .
docker run -d --name <CONTAINER_NAME> -p <HOST_PORT>:80 <IMAGE_NAME>
docker stop <CONTAINER_NAME> && docker rm <CONTAINER_NAME>
```

After writing the files, summarize what you created and the one command to run it.

Step 4 — Offer to build and smoke-test

Don't build automatically — the user may not have Docker running, or may want to review the files first. Ask: "Want me to build it and confirm it serves?"

If yes:

1. Check the daemon is up first with docker info. If it fails, tell the user to start Docker Desktop and stop here — the files are already written and ready whenever they are.
2. Build and start: docker compose up -d --build (or docker build + docker run if they skipped compose).
3. Smoke-test the URL — request http://localhost:<HOST_PORT>/ and confirm an HTTP 200 with non-empty HTML. On Windows use curl.exe or PowerShell's Invoke-WebRequest; give nginx a second to come up and retry once or twice before calling it a failure.
4. Report the result. Leave it running if they want to look at it, or tear down with docker compose down. If you started a throwaway container by hand, clean it up.

If the build or smoke-test fails, read the actual error (docker compose logs) and fix the real cause — a wrong output directory, a missing build step, a port already in use — rather than guessing.

Step 5 — Offer to publish (optional)

Once it runs locally, offer to push the image to a registry so it can be shared or deployed. Only do this if the user wants it. Read references/registry-publish.md for the Docker Hub and GHCR walkthrough (login, tag, push, image naming, and the multi-arch --platform note for Apple-Silicon-built images headed to amd64 servers).

Conventions and rationale

• nginx:alpine for static — tiny, battle-tested, zero app code to maintain. Reach for the Caddy alternative (in recipes) only when the user wants dead-simple config or automatic file serving.
• Multi-stage when building — the final image carries only the rendered site, not Node/Python/Hugo and their caches. Smaller image, smaller attack surface.
• Pin the base image to a minor tag so rebuilds are reproducible.
• Default to port 8080 on the host to avoid colliding with whatever already owns 80.
• Non-root is available via nginxinc/nginx-unprivileged (recipes) for stricter environments — note it as an option rather than forcing it.
• No secrets in the image — static hosting rarely needs any; if the user mentions API keys or env config, that's a sign this is really a dynamic app (strategy D).

Reference files

• references/recipes.md — multi-stage Dockerfiles per generator (Node SSGs, MkDocs, Hugo, Jekyll), the raw-markdown render path, SPA fallback, caching headers, non-root, and the Caddy alternative. Read it for strategy B or C.
• references/registry-publish.md — pushing the image to Docker Hub or GHCR. Read it for Step 5.