Docker Development

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

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

Start the container

Start the application in detached mode:

docker compose up -d

The -d flag runs the container in the background.

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 Port	Container Port	Purpose
5173	5173	Vite 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

Container fails to start

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

Hot reload not working

If file changes aren’t reflected:

Check volume mounts:
docker compose config
Verify file polling is enabled: The vite.config.ts includes usePolling: true for Docker compatibility.
Restart the container:
docker compose restart

Port already in use

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.

Permission issues on Linux

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}"

Build fails with network errors

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

WASM module fails to load

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

Setup

Contributing

Overview

Prerequisites

Quick Start

Dockerfile

Docker Compose Configuration

Port Mappings

Volume Mounts

Common Commands

View logs

Restart the container

Stop the container

Rebuild and restart

Execute commands inside container

Troubleshooting

Production Build in Docker

Next Steps

Local Setup

Building for Production

​Overview

​Prerequisites

​Quick Start

​Dockerfile

​Docker Compose Configuration

​Port Mappings

​Volume Mounts

​Common Commands

​View logs

​Restart the container

​Stop the container

​Rebuild and restart

​Execute commands inside container

​Troubleshooting

​Production Build in Docker

​Next Steps

Local Setup

Building for Production

Overview

Prerequisites

Quick Start

Dockerfile

Docker Compose Configuration

Port Mappings

Volume Mounts

Common Commands

View logs

Restart the container

Stop the container

Rebuild and restart

Execute commands inside container

Troubleshooting

Production Build in Docker

Next Steps