lounge. by LoungeTech

Your first Lounge application

Build a small application, send an event, then change its behavior. No account or production license is needed for development. Use JDK 25 exactly: this release uses Java preview features. The starter uses an in-memory H2 database; Docker is not needed for its development loop.

Install the developer kit

Choose CORE on the download page. Follow the signing-key and checksum verification instructions there, run the downloaded installer, and open a new terminal. The installed version lives under ~/.lounge/current.

lounge doctor
lounge install ./hello-lounge HelloLounge
cd hello-lounge
lounge build
lounge dev

The first build downloads Java dependencies and can take several minutes. A successful build prints LOUNGE BUILD: PASS. Keep the terminal running; the development server normally listens on port 8080. If that port is already in use, stop your other development server or choose a different port.

Send a real event

In another terminal:

curl -sS -u user:userPassword \
  -H 'Content-Type: application/json' \
  -H 'Lounge-Envelope: returns' \
  -d '{"message":"hello"}' \
  http://localhost:8080/lounge/events/Ping

The response should report status: "success", with data.message: "hello" and an at timestamp. The credentials above are the local development defaults. Use your own authentication configuration before production.

The files to inspect are:

  • src/main/resources/lounge/project.yaml: the echo task and its error handler.
  • src/main/java/com/example/hellolounge/domain/DomainRecords.java: the Ping and Pong records.
  • src/main/java/com/example/hellolounge/functions/AppFunctions.java: the small echo function.
  • src/test/java/com/example/hellolounge/TreeBootsTest.java: the build gate and flow test.

Make one change

In AppFunctions.echo, change the Pong message to ping.message().toUpperCase(java.util.Locale.ROOT). Update the corresponding test expectation to HELLO, run lounge build, and submit the same event again. It should now answer HELLO. Restore the echo if you want to continue with the original example.

The Lounge UI opens on the application map. Use Focus to select a subtree, Levels to reduce the visible depth, or Fit width to show the whole structure. Open Try an event and inspect its path, select raw.Ping, and send the same JSON. The emitted-event trace shows actual values and links back to their producing nodes; it is not a database audit log.

Work with an assistant

Point your coding assistant at ~/.lounge/current/tools/lounge/SKILL.md and its references. Ask it to add one operation, its immutable records, and success/failure tests. Keep the generated build test. Review the YAML and any referenced Java before running it.

When something fails

  • Missing JDK or wrong version: fix the specific requirement printed by lounge doctor.
  • Invalid tree: read the named node and rule in the build output. Add or repair the relevant branch; do not disable strict validation to make the build green.
  • HTTP 401/403: check the development credentials and the input's required role.
  • HTTP 422: a validator rejected the input. HTTP 500: processing failed; use the response's correlation ID to find the server-side diagnostic.
  • Memory-only state disappears at restart. Add database persistence or the supported event-log recovery configuration deliberately; an HTTP success is not a promise of disk durability.

Version note: mandatory local-tree lint, corrected class discovery, Docker-free starter defaults and the event runner are part of the 1.0.5 development work. The download page continues to identify the actual published binary version. These improvements should be released together before using this walkthrough as the release acceptance test.