How to Run the Docker Setup for Local Development of the AI Website Cloner

You can launch the AI Website Cloner locally by executing docker compose up dev --build for hot-reload development or docker compose up app --build for production testing, with both services defined in docker-compose.yml orchestrating the multi-stage builds specified in Dockerfile and Dockerfile.dev.

The JCodesMore/ai-website-cloner-template repository ships with a complete containerized environment that eliminates the need to install Node.js or other dependencies on your host system. This guide explains how to run the docker setup for local development of the AI website cloner using the provided production and development Dockerfiles alongside the compose orchestration layer.

Understanding the Docker Architecture

The repository provides three container definitions that work together to support both production and development workflows.

Production Multi-Stage Build

The Dockerfile implements a secure, multi-stage build process that minimizes the final image size. The build progresses through three distinct stages:

1. Dependencies stage – Installs packages using the lockfile to ensure reproducible builds.
2. Builder stage – Executes npm run build to compile the Next.js application.
3. Runner stage – Copies only the compiled assets from .next/standalone and the public directory into a minimal Node.js runtime, then runs as the non-root user node (see lines 12-14, 76-84, and 91-101 of Dockerfile).

This architecture ensures the production container exposes port 3000 with only the essential files required to serve the application.

Development Image

The Dockerfile.dev uses the lightweight node:24-alpine base image to provide a fast, iterative development environment. Unlike the production build, this configuration:

• Copies package.json and package-lock.json before running npm install
• Executes npm run dev to enable Next.js hot-reloading
• Works in conjunction with the compose file's volume mount (volumes: - .:/app) to reflect your local code changes instantly without rebuilding the container

The development service maps to port 3001 by default (configurable via the $DEV_PORT environment variable) while the internal Next.js process still listens on port 3000.

Compose Orchestration

The docker-compose.yml file defines two services under the services: key that handle environment injection and health monitoring:

• app service: Builds from Dockerfile and runs the production-optimized server.
• dev service: Builds from Dockerfile.dev with source code mounted for live editing.
• Health checks: Both services use wget to poll http://localhost:3000/ and verify the application is responding.
• Environment files: Optionally loads .env.local and .env files if present; the container starts successfully even if these files are absent.

Step-by-Step Setup Guide

Follow these commands to get the AI Website Cloner running locally in your preferred mode.

1. Clone the Repository

First, obtain the source code from the JCodesMore/ai-website-cloner-template repository.

git clone https://github.com/JCodesMore/ai-website-cloner-template.git
cd ai-website-cloner-template

2. Configure Environment Variables (Optional)

Create a .env file in the project root if your implementation requires custom API keys or configuration values. The Docker setup will automatically detect and load .env and .env.local files if they exist.

3. Run the Development Container

For active development with hot-reloading, build and start the dev service.

docker compose up dev --build

This command mounts your current directory into the container at /app, allowing you to edit files on your host system while the Next.js development server watches for changes. Access the application at http://localhost:3001 (or the port specified in $DEV_PORT).

4. Run the Production Container

To test the optimized production build locally, execute:

docker compose up app --build

This builds the multi-stage image and starts the compiled Next.js server on port 3000. Visit http://localhost:3000 to verify the production behavior.

5. Stop and Clean Up

When finished, stop all running containers and remove the associated networks.

docker compose down

Add the -v flag to docker compose down -v if you need to remove named volumes as well.

6. Rebuild After Dependency Changes

If you modify package.json or the lockfile, you must rebuild the image to install the new dependencies.

docker compose up app --build

For code-only changes in development mode, hot-reload handles recompilation automatically without requiring a rebuild.

Key Files Reference

Understanding the role of each Docker configuration file helps troubleshoot issues and customize the environment.

• Dockerfile – Defines the multi-stage production build (dependencies → builder → runner) with non-root user security.
• Dockerfile.dev – Lightweight development configuration using node:24-alpine and npm run dev for hot-reloading.
• docker-compose.yml – Orchestrates the app and dev services, manages port mappings (3000 for production, 3001 for development), and configures health checks using wget.
• README.md – Contains quick-reference commands for Docker usage (lines 46-52).

Summary

• The JCodesMore/ai-website-cloner-template provides separate Dockerfiles for production (Dockerfile) and development (Dockerfile.dev) to optimize for security and iteration speed respectively.
• Use docker compose up dev --build to start a hot-reload development environment on port 3001.
• Use docker compose up app --build to run the production-optimized build on port 3000.
• The docker-compose.yml handles service orchestration, optional environment file injection, and health checks via wget.
• Rebuild containers only when dependencies change; code changes in development mode reflect immediately via volume mounts.

Frequently Asked Questions

How do I switch between development and production modes?

Stop any running containers with docker compose down, then start the desired service. Run docker compose up dev --build for development with hot-reloading on port 3001, or docker compose up app --build for the production build on port 3000. Both services can run simultaneously because they bind to different host ports.

Do I need Node.js installed on my local machine?

No. The Docker setup encapsulates the entire Node.js 24 runtime and all dependencies within the containers. You only need Docker and Docker Compose installed. The development container mounts your local source code and handles all JavaScript execution internally.

Why does the development service use port 3001 while the production service uses port 3000?

The docker-compose.yml maps the internal Next.js port 3000 to host port 3000 for the production app service. For the dev service, it maps internal port 3000 to host port 3001 (or $DEV_PORT if set) to prevent conflicts when running both services simultaneously. You can customize this by setting the DEV_PORT environment variable before running the compose command.

How do I persist data or environment variables across container restarts?

Place environment variables in .env or .env.local files in the project root. The docker-compose.yml includes these files in the service definitions, making them available inside the containers. If you modify these files while the container is running, restart the service with docker compose up dev --build (or app) to reload the configuration.

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