How to Deploy Vue Color Avatar Using Docker: Complete Guide

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:

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:

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

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

2. Build the Docker image

   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

   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

   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) 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 and 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 file to manage the container with restart policies and environment variables:

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:

# In Dockerfile, add before the HEALTHCHECK

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

Create an 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 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 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.

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