# How to Deploy Vue Color Avatar Using Docker: Complete Guide

> Deploy Vue Color Avatar with Docker. Clone the repo, build the image, and run the container. Get your personalized avatars served via Nginx in minutes.

- Repository: [LeoKu/vue-color-avatar](https://github.com/codennnn/vue-color-avatar)
- Tags: how-to-guide
- Published: 2026-02-27

---

**To deploy Vue Color Avatar using Docker, clone the repository, build the multi-stage image with `docker build -t vue-color-avatar .`, and run it with `docker run -p 3000:80` to serve the Vite-built static files via Nginx.**

Vue Color Avatar is a Vue 3 + Vite application for generating vector-based avatars. Deploying it using Docker provides a reproducible, production-ready environment with a minimal final image size of approximately 30 MB. The containerization strategy uses a multi-stage build to separate the Node.js compilation environment from the lightweight Nginx serving layer.

## Understanding the Multi-Stage Docker Build

The `Dockerfile` at the repository root implements a two-stage build process that optimizes the final image size and security.

### Stage 1: Node.js Builder

The first stage uses `node:20-alpine` as the base image to compile the application. It enables Corepack to use **pnpm** for deterministic dependency installation, then executes the Vite production build.

Key steps from `Dockerfile` lines 1-15:

```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

```

The `pnpm build` command executes `vite build`, which bundles the Vue 3 application into static assets in the `/app/dist` directory.

### Stage 2: Nginx Production

The second stage copies only the compiled `dist/` folder into an `nginx:alpine` image, resulting in a production container that contains no build tools or Node.js runtime.

Key steps from `Dockerfile` lines 18-34:

```dockerfile
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost/ || exit 1
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

```

The **health-check** uses `wget` to verify that Nginx is serving traffic on port 80 every 30 seconds.

## Step-by-Step Deployment Guide

Follow these commands to deploy Vue Color Avatar using Docker on any Linux, macOS, or Windows system with Docker installed.

1. **Clone the repository**

   ```bash
   git clone https://github.com/codennnn/vue-color-avatar.git
   cd vue-color-avatar
   ```

2. **Build the Docker image**

   ```bash
   docker build -t vue-color-avatar:latest .
   ```

   This executes the multi-stage build, compiling the Vue 3 application with Vite and packaging it with Nginx.

3. **Run the container**

   ```bash
   docker run -d -p 3000:80 --name vue-color-avatar vue-color-avatar:latest
   ```

   The `-p 3000:80` flag maps port 3000 on your host to port 80 inside the container where Nginx is listening.

4. **Verify the deployment**

   ```bash
   curl -f http://localhost:3000 || echo "Container unhealthy"
   ```

   Or open `http://localhost:3000` in a browser to access the avatar generator interface.

## Dockerfile Configuration Details

The `Dockerfile` in the repository root ([view source](https://github.com/codennnn/vue-color-avatar/blob/main/Dockerfile)) uses specific optimizations for Vue 3 + Vite projects:

- **Corepack integration**: Uses `corepack enable pnpm` to ensure consistent package manager versioning without global installation.
- **Layer caching**: Copies [`package.json`](https://github.com/codennnn/vue-color-avatar/blob/main/package.json) and [`pnpm-lock.yaml`](https://github.com/codennnn/vue-color-avatar/blob/main/pnpm-lock.yaml) before the main source code, allowing Docker to cache the dependency installation layer.
- **Frozen lockfile**: The `--frozen-lockfile` flag prevents accidental updates during the build, ensuring reproducible builds.
- **Multi-stage separation**: The final image contains only Nginx and static HTML/CSS/JS assets from the `dist/` folder, eliminating the Node.js runtime and build dependencies.

## Optional Enhancements

Extend the basic Docker deployment with these production-ready configurations.

### Docker Compose Setup

Create a [`docker-compose.yml`](https://github.com/codennnn/vue-color-avatar/blob/main/docker-compose.yml) file to manage the container with restart policies and environment variables:

```yaml
version: "3.9"
services:
  vue-color-avatar:
    build: .
    image: vue-color-avatar:latest
    ports:
      - "3000:80"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost/"]
      interval: 30s
      timeout: 3s
      retries: 3

```

Run with `docker compose up -d`.

### Custom Nginx Configuration

To customize caching headers or HTTPS redirection, uncomment and modify the Nginx configuration copy in the `Dockerfile`:

```dockerfile

# In Dockerfile, add before the HEALTHCHECK

COPY nginx.conf /etc/nginx/conf.d/default.conf

```

Create an [`nginx.conf`](https://github.com/codennnn/vue-color-avatar/blob/main/nginx.conf) with your specific server block settings for production optimization.

## Summary

- **Vue Color Avatar** uses a multi-stage Docker build combining `node:20-alpine` for compilation and `nginx:alpine` for serving.
- The build process relies on **pnpm** with Corepack to install dependencies and **Vite** to generate static assets in the `dist/` folder.
- The final image exposes port 80 and includes a health-check using `wget` to verify Nginx availability.
- Deploy by cloning the repository, running `docker build -t vue-color-avatar .`, and starting the container with `docker run -p 3000:80`.

## Frequently Asked Questions

### What is the final image size when deploying Vue Color Avatar with Docker?

The final production image is approximately **30 MB** because the multi-stage build discards the Node.js toolchain and retains only the compiled static assets served by the lightweight `nginx:alpine` base image.

### Can I use Docker Compose to deploy Vue Color Avatar?

Yes. Create a [`docker-compose.yml`](https://github.com/codennnn/vue-color-avatar/blob/main/docker-compose.yml) file that defines the service, maps port 3000 to 80, and sets `restart: unless-stopped`. Run `docker compose up -d` to start the container in detached mode with automatic restart capabilities.

### How do I customize the Nginx configuration in the Docker deployment?

Add a custom [`nginx.conf`](https://github.com/codennnn/vue-color-avatar/blob/main/nginx.conf) file to your project root, then modify the `Dockerfile` to copy it into the container using `COPY nginx.conf /etc/nginx/conf.d/default.conf` before the `HEALTHCHECK` instruction. This allows you to customize caching headers, compression, or SSL settings.

### What Node.js version does the Docker build use?

The builder stage uses **`node:20-alpine`**, which provides Node.js 20 in a minimal Alpine Linux environment. This version is specified in the first line of the `Dockerfile` and ensures compatibility with the project's pnpm and Vite build requirements.