Advanced
Troubleshooting
Docker Port Allocation Conflicts
If you encounter `port is already allocated` when running `docker compose up -d` (port 5432 or 27017):
✓ Cause: You have a local PostgreSQL or MongoDB instance running outside Docker.
✓ Solution: Stop the local system service or edit `docker-compose.yml` to map host ports to an alternative number (e.g. `"5433:5432"`).
Execution Permissions on macOS & Linux
If you download native binaries directly from GitHub Releases and receive `permission denied` or Gatekeeper security prompts:
✓ On Linux/macOS: Grant execution permissions using `chmod +x koko`.
✓ On macOS (Gatekeeper): If the binary is quarantined, run `xattr -d com.apple.quarantine koko` or allow it via System Settings > Privacy & Security.
Monorepo Workspace Linking (pnpm)
If local package symlinks in `packages/db` fail to resolve:
✓ Make sure you have `pnpm` (v9 or newer) installed.
✓ Run `pnpm install` from the project root so workspace symlinks are properly established.