How to Set Up and Use the Docker Development Environment for the AI Website-Cloner Template

The AI Website-Cloner Template ships with a complete Docker-based workflow that supports both production and development modes, eliminating the need to install Node.js or any host-side dependencies.

This repository provides a containerized Next.js application orchestrated through Docker Compose. Whether you are iterating on features locally or deploying a production build, the Docker development environment ensures reproducible builds and consistent runtime behavior across all machines.

Architecture Overview

The repository contains four key files that define the containerization strategy:

Component	Purpose	Key Docker Features
Dockerfile	Multi-stage build producing a minimal production image	Three stages: dependencies (caches node_modules), builder (runs npm run build), and runner (serves compiled assets)
Dockerfile.dev	Simplified development image for hot-reloading	Uses node:24-alpine, copies package manifests, and relies on volume mounts for live code updates
docker-compose.yml	Orchestrates production and development services	Defines separate app (production) and dev services with distinct ports, build contexts, and environment variables
package.json	Declares npm scripts invoked by containers	Exposes dev, build, and start scripts used consistently in both local and containerized workflows

The production configuration generates a standalone Next.js deployment that contains only the compiled output (.next/standalone, .next/static, and public), resulting in a compact, secure image that runs under a non-root node user. The development configuration prioritizes developer experience by mounting the host filesystem into the container, enabling instantaneous hot-reload without image rebuilds.

How the Dockerfiles Work

Production Dockerfile

The production Dockerfile implements a three-stage build process to optimize layer caching and minimize final image size:

1. dependencies stage: Installs exact dependency versions from the lockfile using npm ci (or equivalent), caching the package manager directories to accelerate subsequent builds.
2. builder stage: Copies the installed modules, adds the source code, sets NODE_ENV=production, and executes npm run build to compile the Next.js application.
3. runner stage: Starts from a fresh Node.js image, copies only the built assets from the previous stage, switches to the non-root node user, exposes port 3000, and launches the server with node server.js.

This multi-stage approach ensures the final image contains no build tools, source code, or development dependencies.

Development Dockerfile

The Dockerfile.dev uses a single-stage build optimized for rapid iteration:

1. Sets WORKDIR /app and copies package.json plus package-lock.json.
2. Runs npm install to install dependencies.
3. Declares EXPOSE 3000 and sets NODE_ENV=development.
4. Executes npm run dev, which launches the Next.js development server with hot-reload enabled.

When invoked via docker-compose.yml, the development service mounts the repository root (.:/app) as a volume. This binds your local source code into the container, allowing file changes to trigger immediate recompilation without requiring a container rebuild.

Running the Containers

Start the Development Environment

Launch the hot-reload development server on port 3001 (mapped to port 3000 inside the container):

docker compose up dev

Access the application at http://localhost:3001. Edit files locally; Next.js will automatically recompile inside the container.

Start the Production Environment

Build and run the optimized production image:

docker compose up app

This constructs the ai-website-cloner:latest image using the runner target and exposes the application on ${PORT:-3000} (defaulting to port 3000).

Run Containers in Detached Mode

Append the -d flag to run containers in the background:

docker compose up -d dev

Force a Rebuild

When modifying dependencies in package.json, rebuild the image to refresh the node_modules layer:

docker compose up --build dev

Stop and Clean Up

Terminate all running containers and remove associated networks:

docker compose down

Environment Configuration

The docker-compose.yml file reads environment variables from .env or .env.local files (marked as optional). Key variables include:

• PORT: Overrides the production service port (default: 3000)
• DEV_PORT: Overrides the development service host port (default: 3001)

Both services include health checks that ping http://localhost:<port>/ and automatically restart the container if the endpoint becomes unreachable.

Typical Development Workflow

1. Clone the repository to your local machine and ensure Docker Desktop (or Docker Engine) is installed and running.

2. (Optional) Create a .env file in the repository root to override default ports or other configuration values.

3. Launch the development service:

   docker compose up dev

4. Open your browser to http://localhost:3001 to view the application.

5. Edit source files on your host machine; the Next.js dev server inside the container detects changes and hot-reloads instantly.

6. Build for production when ready to deploy:

   docker compose up app

   Verify the optimized build at http://localhost:3000.

Summary

• The AI Website-Cloner Template provides distinct Docker configurations for production (Dockerfile) and development (Dockerfile.dev) workflows.
• The production image uses a three-stage build to create a minimal, secure runtime containing only compiled Next.js assets.
• The development environment mounts the host filesystem as a volume, enabling hot-reload without container rebuilds.
• Docker Compose orchestrates both modes through separate services (app and dev) with configurable ports and automatic health checks.
• All npm scripts (dev, build, start) execute consistently inside containers, ensuring parity between development and production environments.

Frequently Asked Questions

How do I change the port for the development server?

Set the DEV_PORT environment variable before running the command. For example, to use port 4000 instead of 3001:

DEV_PORT=4000 docker compose up dev

The application will be available at http://localhost:4000.

Why does the production container use a non-root user?

The runner stage in Dockerfile switches to the node user before executing node server.js. This security best practice minimizes potential damage if the container is compromised, as the process lacks root privileges required to modify system files or install malicious packages.

Do I need to rebuild the container after installing new npm packages?

Yes. If you modify package.json or package-lock.json, you must rebuild the image to install the new dependencies inside the container. Use docker compose up --build dev to force a fresh build of the development image, or docker compose up --build app for production.

Can I use this Docker setup without installing Node.js locally?

Absolutely. The entire purpose of this Docker development environment is to encapsulate all runtime dependencies. As long as you have Docker installed, you can build, develop, and run the application without Node.js, npm, or any other tools installed on your host machine.

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