Skip to main content

​
Overview

Gridfinity Builder includes Docker support for consistent development environments across different platforms. The Docker setup uses Docker Compose for easy orchestration.

​
Prerequisites

  • Docker 20.10+
  • Docker Compose 2.0+ (included with Docker Desktop)

​
Quick Start

1

Build the Docker image

Build the image with no cache to ensure fresh dependencies:
docker compose build --no-cache
This will:
  • Use Node.js 20 Alpine base image
  • Install npm dependencies
  • Copy source files
  • Configure the development server
2

Start the container

Start the application in detached mode:
docker compose up -d
The -d flag runs the container in the background.
3

Access the application

Open your browser and navigate to:
http://localhost:5173

​
Dockerfile

The Dockerfile uses a multi-stage approach optimized for development: 
FROM node:20-alpine

WORKDIR /app

# Copy package files first for better layer caching
COPY package.json package-lock.json* ./

RUN npm install

# Copy the rest of the source
COPY . .

EXPOSE 5173

CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]
Key features:
  • Alpine Linux - Minimal image size (~150MB vs 1GB+)
  • Layer caching - Package files copied separately for faster rebuilds
  • Host binding - --host 0.0.0.0 allows external connections
  • Port 5173 - Vite’s default development port

​
Docker Compose Configuration

The docker-compose.yml orchestrates the development environment: 
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      no_cache: true
    ports:
      - "5173:5173"
    volumes:
      - ./src:/app/src
      - ./public:/app/public
      - ./index.html:/app/index.html
      - ./vite.config.ts:/app/vite.config.ts
      - ./tailwind.config.ts:/app/tailwind.config.ts
      - ./tsconfig.json:/app/tsconfig.json
      - ./tsconfig.app.json:/app/tsconfig.app.json
    environment:
      - NODE_ENV=development
    restart: unless-stopped

​
Port Mappings

Host PortContainer PortPurpose
51735173Vite development server

​
Volume Mounts

The following directories are mounted for hot reload:
  • ./src - Application source code
  • ./public - Static assets (icons, etc.)
  • index.html - Entry HTML file
  • vite.config.ts - Vite configuration
  • tailwind.config.ts - Tailwind CSS config
  • tsconfig.json - TypeScript configuration
Volume mounts enable hot module replacement (HMR). Changes to mounted files are immediately reflected in the running container.

​
Common Commands

​
View logs

# Follow logs in real-time
docker compose logs -f

# View last 100 lines
docker compose logs --tail=100

​
Restart the container

docker compose restart

​
Stop the container

docker compose down

​
Rebuild and restart

docker compose down
docker compose build --no-cache
docker compose up -d

​
Execute commands inside container

# Open a shell
docker compose exec app sh

# Install a new package
docker compose exec app npm install <package-name>

# Run TypeScript compiler
docker compose exec app npm run build

​
Troubleshooting

Check container logs for errors:
docker compose logs app
Common issues:
  • Port 5173 already in use on host
  • npm install failed (check network/registry)
  • Missing package-lock.json
If file changes aren’t reflected:
  1. Check volume mounts: 
    docker compose config
  2. Verify file polling is enabled: The vite.config.ts includes usePolling: true for Docker compatibility.
  3. Restart the container: 
    docker compose restart
If port 5173 is occupied:
# Edit docker-compose.yml
ports:
  - "3000:5173"  # Map host port 3000 to container port 5173
Access the app at http://localhost:3000.
Files created by the container may have root ownership:
# Fix ownership (replace 1000:1000 with your UID:GID)
sudo chown -R 1000:1000 .
Or add to docker-compose.yml:
user: "${UID}:${GID}"
If npm install times out:
# Use a different npm registry
docker compose exec app npm config set registry https://registry.npmmirror.com

# Or rebuild with build args
docker compose build --build-arg NPM_REGISTRY=https://registry.npmmirror.com
Ensure the container has sufficient memory:
# Add to docker-compose.yml
services:
  app:
    deploy:
      resources:
        limits:
          memory: 4G

​
Production Build in Docker

To build a production-ready image: 
# Create a production Dockerfile.prod
FROM node:20-alpine AS build

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

docker build -f Dockerfile.prod -t gridfinity-builder:prod .
docker run -p 8080:80 gridfinity-builder:prod

​
Next Steps

Local Setup

Set up without Docker for faster iteration

Building for Production

Create optimized production builds

Build docs developers (and LLMs) love

Get started for freeTalk to us