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

> Learn to set up and use the Docker development environment for the AI Website-Cloner Template. Run the project without Node.js or host dependencies for a seamless workflow.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-06-23

---

**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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/package.json) plus [`package-lock.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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):

```bash
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:

```bash
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:

```bash
docker compose up -d dev

```

### Force a Rebuild

When modifying dependencies in [`package.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/package.json), rebuild the image to refresh the `node_modules` layer:

```bash
docker compose up --build dev

```

### Stop and Clean Up

Terminate all running containers and remove associated networks:

```bash
docker compose down

```

## Environment Configuration

The [`docker-compose.yml`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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**:
   ```bash
   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:
   ```bash
   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:

```bash
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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/package.json) or [`package-lock.json`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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.