How to set up local development
Get the Aucert monorepo running locally from scratch. This guide uses interactive verification — click "Verify" after each step to confirm before moving on.
Prerequisites
- macOS or Linux (Windows via WSL2)
- Git configured with SSH key for GitHub (
ssh -T git@github.comshould succeed) - Homebrew (macOS) or equivalent package manager
- At least 16 GB RAM (8 GB for backend + frontend, 8 GB for emulator)
Steps
Install Node.js and pnpm
brew install node
npm install -g pnpm
Install JDK 21 (Temurin)
brew install --cask temurin
Install Python 3.12+
brew install python@3.12
pip3 install uv
Install infrastructure tools
brew install kubectl terraform azure-cli helm
Clone the repository
git clone git@github.com:aucert-admin/aucert.git
cd aucert
Install monorepo dependencies
pnpm install
Authenticate with Azure
az login
Configure kubectl for AKS
az aks get-credentials --resource-group aucert-rg --name aucert-aks
Verify backend builds
cd backend/platform && ./gradlew build && cd ../..
Verify frontend builds
cd frontend/apps/console && pnpm build && cd ../../..
Verify docs build
cd docs/public && pnpm build && cd ../..
cd docs/internal && pnpm build && cd ../..
Environment setup
Shell configuration
Add these to your ~/.zshrc or ~/.bashrc:
# JDK 21 (required for backend)
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
# Android SDK (required for emulator execution)
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools
Database access
The dev PostgreSQL instance runs in AKS. Port-forward for local access:
kubectl port-forward -n aucert-dev svc/product-pg 5432:5432
Connection string for local development:
jdbc:postgresql://localhost:5432/aucert
Username: aucert. Password: stored in Key Vault (aucertdev-kv-41e0x5, secret: pg-password).
Editor setup
| Editor | Recommended plugins |
|---|---|
| VS Code | Kotlin Language, ESLint, Prettier, Tailwind CSS IntelliSense |
| IntelliJ IDEA | Built-in Kotlin support. Import as Gradle project. |
| Cursor | Same as VS Code + .cursorrules reads from .context/AI_RULES.md |
Troubleshooting
pnpm install fails with peer dependency errors
Run with relaxed peer dependency checks:
pnpm install --no-strict-peer-dependencies
This is safe for development. The CI build uses strict mode, so you'll catch real conflicts there.
Gradle build fails with JDK version error
Ensure JAVA_HOME points to JDK 21:
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
echo $JAVA_HOME # Should show a temurin-21 path
If you have multiple JDKs installed, verify the active one:
/usr/libexec/java_home -V # Lists all installed JDKs
az login hangs in terminal
Use device code flow instead of browser redirect:
az login --use-device-code
This gives you a URL and code to enter in any browser — works in SSH sessions and containers.
kubectl: connection refused
Re-fetch AKS credentials:
az aks get-credentials --resource-group aucert-rg --name aucert-aks --overwrite-existing
If the cluster is unreachable, check your network (VPN may be required for some environments).
Frontend build fails with "Module not found"
Clear Next.js cache and rebuild:
cd frontend/apps/console
rm -rf .next node_modules/.cache
pnpm install
pnpm build
What's next
- How to run the backend — Start the Kotlin backend locally
- How to run the frontend — Start the Next.js console
- How to run tests — Run the test suites