How to Deploy HowToCook Locally with Docker: A Complete Guide

Pull the pre-built image from GitHub Container Registry with docker pull ghcr.io/anduin2017/how-to-cook:latest and run it on port 5000 using docker run -d -p 5000:80 ghcr.io/anduin2017/how-to-cook:latest to serve the static cooking documentation locally.

The HowToCook repository generates a comprehensive cooking guide as a static website using MkDocs and serves it through Nginx. When you deploy locally with Docker, you can run the entire stack without installing Node.js, Python, or MkDocs on your host machine, using either the official pre-built image or building from source.

Understanding the HowToCook Docker Architecture

The project uses a multi-stage Dockerfile located at the repository root to optimize build efficiency and minimize the final image size.

Stage 1: Lint Environment (Node.js)

The first stage uses a Node-based image to install npm dependencies defined in package.json, execute the build script, and run the linter. This ensures all Markdown sources are valid before packaging. This stage corresponds to lines 3-9 in the Dockerfile.

Stage 2: Build Environment (Python 3.11)

The second stage starts from python:3.11, copies the built site from the lint stage, installs Python dependencies from requirements.txt, adds system fonts required by WeasyPrint for PDF generation, and runs mkdocs build to generate the static site under /app/site. This corresponds to lines 12-18 in the Dockerfile.

Stage 3: Runtime Environment (Nginx Alpine)

The final stage uses nginx:1-alpine as a lightweight runtime, copying only the generated static files from the Python stage into Nginx's default document root at /usr/share/nginx/html. The final image contains no build tools, reducing attack surface and download size. This is implemented in lines 20-23 of the Dockerfile.

Deploy Locally with Docker Using the Pre-Built Image

The fastest way to deploy locally with Docker is to use the GitHub Container Registry image. According to the README.md documentation, you can pull and run the container with two commands.

First, pull the latest image:

docker pull ghcr.io/anduin2017/how-to-cook:latest

Then run the container, mapping host port 5000 to the container's port 80:

docker run -d -p 5000:80 ghcr.io/anduin2017/how-to-cook:latest

After the container starts, open your browser to http://localhost:5000 to view the full HowToCook website.

Building the Docker Image Locally from Source

If you need to customize the content or modify the build process, you can build the Docker image locally instead of using the pre-built registry image.

First, clone the repository:

git clone https://github.com/Anduin2017/HowToCook.git
cd HowToCook

Build the image with a custom tag:

docker build -t how-to-cook:dev .

Run your locally built image:

docker run -d -p 5000:80 how-to-cook:dev

This approach executes all three stages of the multi-stage Dockerfile, including the Node.js linting and Python MkDocs build steps, before serving the site through Nginx.

Key Files in the Docker Build Process

Several files in the repository root control how you deploy locally with Docker:

• Dockerfile – The multi-stage build definition that orchestrates the lint, build, and runtime stages using Node, Python 3.11, and Nginx Alpine images.

• requirements.txt – Python dependencies including MkDocs and WeasyPrint, installed during the Python build stage to generate the static site.

• package.json – Node.js dependencies for linting and build scripts, used in the first stage to validate Markdown sources.

• README.md – User-facing documentation that includes the quick-start command for pulling the pre-built image from GitHub Container Registry.

Summary

• The HowToCook project uses a three-stage Dockerfile to build a static MkDocs site and serve it via Nginx.
• To deploy locally with Docker quickly, pull ghcr.io/anduin2017/how-to-cook:latest and map port 5000 to the container's port 80.
• For custom builds, clone the repository and run docker build -t how-to-cook:dev . to execute the full lint and build pipeline.
• The final runtime image contains only static files and Nginx, with no Node.js or Python tooling, minimizing the attack surface.

Frequently Asked Questions

What ports does HowToCook use when I deploy locally with Docker?

The container exposes port 80 internally for Nginx. When you run the container, map a host port (commonly 5000) to port 80 using the -p flag, such as -p 5000:80, then access the site at http://localhost:5000.

Can I modify the content before building the Docker image?

Yes. Clone the repository with git clone https://github.com/Anduin2017/HowToCook.git, edit the Markdown files in the repository, then build the image locally with docker build -t how-to-cook:dev .. The Dockerfile will process your modified content through the lint and build stages.

Why does the Dockerfile use a multi-stage build?

The multi-stage build separates the linting (Node.js), building (Python 3.11 with MkDocs), and runtime (Nginx Alpine) environments. This ensures the final image contains only the compiled static files and Nginx, excluding all build tools and dependencies, which reduces image size and security vulnerabilities.

Do I need Node.js and Python installed locally to run the container?

No. When you deploy locally with Docker using the pre-built image from GitHub Container Registry, you only need Docker installed. The container includes all necessary runtime components. You only need Node.js and Python if you choose to build the image from source and want to run linting or build steps outside of Docker.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}