Docker Setup Issues

HireKit runs in Docker containers. Here are solutions for common setup and runtime issues.

Initial Setup

Prerequisites

Make sure you have installed:

• Docker Desktop (latest version)
• Docker Compose (included with Docker Desktop)
• At least 4GB of RAM allocated to Docker

First-Time Build

docker compose up --build

This command builds and starts all four services:

• frontend on port 3000
• backend on port 4000
• postgres on port 5432
• redis on port 6379

Common Issues

Port Already in Use

Error: port is already allocated

Solution: Stop other services using those ports, or change the port mapping in docker-compose.yml:

# Check what is using the port
lsof -i :3000
lsof -i :4000

Container Keeps Restarting

Check the container logs for errors:

docker compose logs frontend
docker compose logs backend

Common causes:

• Missing environment variables (check .env file)
• Database not ready (backend starts before postgres is ready)
• Invalid API keys

Database Migration Errors

If you see migration-related errors:

# Generate and run migrations
npm run db:generate
npm run db:migrate

Volume Permission Issues

On some systems, Docker volumes may have permission issues:

# Reset volumes (WARNING: this deletes all data)
docker compose down -v
docker compose up --build

Accessing from Other Devices

HireKit binds to 0.0.0.0 for LAN access. To access from another device on your network:

1. Find your host machine's IP address
2. Access http://<your-ip>:3000 from the other device
3. Ensure your firewall allows connections on ports 3000 and 4000

Useful Commands

# View running containers
docker compose ps

# View logs for a specific service
docker compose logs -f backend

# Restart a specific service
docker compose restart backend

# Rebuild a specific service
docker compose up --build backend

# Open Drizzle Studio for DB visualization
npm run db:studio