This guide is for local development purposes. For production deployment, please refer to the Deploy Kodus guide.

​
Prerequisites

  • Node.js (LTS version)
  • Docker
  • Yarn or NPM
  • LLM API Keys

​
Running the project

​
Development workflow

​
Basic Local Development

  1. Start services: yarn docker:start
  2. Run migrations: yarn migrate:dev
  3. Load seed data: yarn seed
  4. Create tunnel: yarn tunnel (creates public endpoint)
  5. Health check: yarn dev:health-check

​
Development with External Integrations

If you need to test integrations with external services (like Git webhooks):
  1. Start services: yarn docker:start && yarn migrate:dev && yarn seed
  2. Create tunnel: yarn tunnel (creates public endpoint)
  3. Update webhook URLs: The tunnel command updates your .env automatically
  4. Configure Git provider: Use the tunnel URL in your Git provider webhook settings
  5. Test integration: Trigger webhooks and monitor logs
Tunnel Benefits:
  • Test real webhook integrations locally
  • Debug external service communications
  • Share your development environment with team members
  • Test mobile apps or other external clients

​
Troubleshooting

​
Quick Health Check

yarn dev:health-check
This comprehensive healtha*: Kodus API, PostgreSQL, MongoDB
  • 🔌 Port availability: API (3001), PostgreSQL (5432), MongoDB (27017)
  • 🗄️ Database setup: Migrations and seed data
  • 🌐 API endpoints: Health endpoints and basic connectivity

​
Manual Verification

  1. Check API health: Visit http://localhost:3001/health in your browser
  2. Verify database connections: Check the logs for successful database connections
  3. Test webhook endpoints: Your Git provider webhooks should point to http://localhost:3001/[provider]/webhook

​
Setup Script Issues

If the automated setup script (yarn dev:first-run) fails: Missing dependencies: 
# Check if all required tools are installed
node --version
yarn --version
docker --version
openssl version
Permission issues with Docker: 
# Add your user to the docker group (Linux/macOS)
sudo usermod -aG docker $USER
# Then log out and log back in
Network creation errors: 
# Check if networks already exist
docker network ls | grep kodus
# Remove conflicting networks if needed
docker network rm kodus-backend-services shared-network

​
Common Issues

Port conflicts:
  • Ensure ports 3001 (API), 5432 (PostgreSQL), and 27017 (MongoDB) are available
  • Stop other services using these ports before starting Kodus
Environment variables not loading:
  • Verify your .env file exists in the project root
  • Check that there are no trailing spaces in variable assignments
  • Ensure all required security keys were generated properly
Health check failures:
  • Run yarn dev:health-check to get detailed diagnostics
  • Check if containers are fully started (wait 1-2 minutes after yarn docker:start)
  • Verify database migrations and seed data are loaded
  • Check API logs with yarn docker:logs for startup errors
API not responding:
  • The API takes time to fully initialize after container startup
  • Check if migrations and seed data are loaded
  • Verify the .env file has all required variables
  • Run health check to see which specific components are failing
Webhook issues with external services:
  • Use yarn tunnel to create a public endpoint for external webhooks
  • Update your Git provider webhook URLs to use the tunnel URL
  • Ensure the tunnel is running when testing webhook integrations
  • Check tunnel logs for connection issues