Skip to main content

Setup

Development Environment​

A clean, structured guide to run Ambrosia‑POS locally with native tools.

Requirements:​

  • SDKMAN (official: https://sdkman.io/) 
    curl -s "https://get.sdkman.io" | bash
    source "$HOME/.sdkman/bin/sdkman-init.sh"
  • Java 21 (Temurin): 
    sdk list java
    sdk install java 21-tem
    java -version
  • Gradle: 
    sdk install gradle
    gradle -v
  • Node.js >= 18 and npm.
  • phoenixd (Lightning): 
    curl -fsSL https://raw.githubusercontent.com/btcgdl/Mastering-phoenixd/master/scripts/install.sh | bash -s -- --yes
    Full guide: https://btcgdl.github.io/Mastering-phoenixd/

Quick check​

java -version && gradle -v | head -n1 && node -v && npm -v

Step 1 · Start phoenixd​

After installation, ensure the service is running and ~/.phoenix is initialized as per the Mastering phoenixd guide.

Step 2 · Backend (Kotlin/Ktor)​

cd server
./gradlew run    # API on :9154
  • Tests: ./gradlew test

Step 3 · Frontend (Next.js)​

cd client
npm install
npm run dev      # web on :3000
  • Lint: npm run lint
  • Tests: npm test

Local endpoints​

Troubleshooting​

Tips
  • Use the ./gradlew wrapper to avoid PATH issues.
  • If a port is busy, change 3000/9154 or stop the conflicting process.
  • phoenixd: ensure it’s running and ~/.phoenix contains expected config.