Local Development

This guide covers setting up your local development environment using Docker.

Prerequisites

• Docker Desktop installed
• Node.js 20.x (for non-Docker development)
• Git

Quick Start

# Clone the repository
git clone <repository-url>
cd hrms-docs

# Option 1: Docker (recommended for production parity)
docker-compose up

# Option 2: Native Node.js (faster hot reload)
npm install
npm run dev

Docker Setup

Dockerfile

The project uses a multi-stage Dockerfile for optimized production builds:

# See Dockerfile in project root

docker-compose.yml

For local development with hot reload:

# See docker-compose.yml in project root

Environment Variables

Common Tasks

Build Production Image Locally

docker build -t hrms-docs:local .
docker run -p 3000:3000 hrms-docs:local

Clean Rebuild

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

Troubleshooting

Port Already in Use

# Find process using port 3000
lsof -ti:3000 | xargs kill -9

Docker Build Fails

1. Ensure Docker Desktop is running
2. Check available disk space
3. Try docker system prune to clean up

Out of Memory During Build

Next.js builds can be memory-intensive. If you see cannot allocate memory or SIGKILL:

1. Increase Docker Desktop memory allocation:

   • Docker Desktop → Settings → Resources → Memory
   • Recommended: 8GB or more for builds

2. Build in CI instead:

   • Local Docker builds are optional
   • GitHub Actions has sufficient memory
   • Use npm run dev for local development

Postinstall Script Fails

The fumadocs-mdx postinstall script may fail in Docker if vite is not available. The Dockerfile uses --ignore-scripts to skip this - it's only needed for development TypeScript types.

Status: Verified - Dockerfile tested, requires 8GB+ Docker memory for local builds