nuxt / nuxt/nuxt.com

Add a Docker deployment guide to /deploy

Open
#2,398 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
457
Forks
272
Avg merge
13h 33m
Merged PRs (30d)
23

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?

Contributor guide

Open the contributing guide

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.

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.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.