Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add a Docker deployment guide to /deploy

Open
  • Is something wrong?
#2,398 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@BobTheShoplifter is already working on this.

Since Aug 26, 2026.

  • #2399 by @BobTheShoplifter — open

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
76/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
docker, dockerfile, typescript
Domain
devops, documentation

Research direction

Start by reading the existing deployment content and inspect test/mcp.eval.ts, then update content/deploy/docker.md and the Dockerfile language entry in nuxt.config.ts. Done means the guide covers the requested Docker, runtime, static, and Compose cases, and Dockerfile fences render with the documented syntax highlighting.

Written by the indexing model from the issue text.

Description

Describe the feature

/deploy documents 23 hosting providers, but there is no page on running Nuxt in a container, and /docs/getting-started/deployment never mentions Docker either — it covers the Node.js server preset, static hosting, serverless/edge, PM2 and cluster mode, but the words "Docker" and "container" do not appear in it.

That is a noticeable gap, because a container image is the default deployment unit for anyone self-hosting on a VPS, Kubernetes, Fly.io, Railway, Coolify, Dokploy, ECS or Cloud Run — and several providers already listed under /deploy are consumed through an image anyway.

This repository already assumes people ask the question. test/mcp.eval.ts contains:

{ input: 'What deployment providers support Docker containerization?', expected: [{ toolName: 'list_deploy_providers' }] }

list_deploy_providers currently has nothing Docker-related to return.

Why it matters

Without a canonical page, people copy Dockerfiles from blog posts and the same mistakes keep recurring:

  • copying the host node_modules into the image because there is no .dockerignore
  • shipping the whole source tree to production instead of the standalone .output directory
  • not knowing .output needs nothing but a Node.js runtime, so no multi-stage build
  • confusing build-time values (baked into the image) with runtimeConfig values (NUXT_*, read at container start), which leads to secrets in image layers
  • missing NITRO_PORT / NITRO_HOST when the platform assigns a port

None of that is hard, but it is currently undocumented and each of the 23 provider pages assumes a managed build instead.

Proposal

Add content/deploy/docker.md covering:

  • a multi-stage Dockerfile per package manager, copying only .output into a clean runtime stage
  • a .dockerignore
  • build and run commands
  • the runtime environment variables, and the build-time vs runtime distinction
  • a Docker Compose example
  • a static variant (nuxt generate served by nginx), including the 200.html / 404.html fallback caveat

One small code change comes with it: dockerfile is not part of content.build.markdown.highlight.langs in nuxt.config.ts, so Dockerfile code fences currently render as plain text. @nuxt/content maps each entry of that array to import('@shikijs/langs/<entry>') and keys the result by the entry string verbatim, without expanding aliases, then looks the fence language up in that map — so the entry has to match the fence label exactly. Listing docker is not enough for a ```dockerfile fence; dockerfile is itself a valid @shikijs/langs subpath that re-exports the docker grammar, and that is the entry to add.

Additional information
  • Would you be willing to help implement this feature?
Dominant language
TypeScript
Stars
460
Forks
281
Avg merge
1d 9h
Merged PRs (30d)
84

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from nuxt/nuxt.com

All issues in nuxt/nuxt.com

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.