Skip to main content

Development Environment

This document explains how to set up and run the DocApply project locally for development.

Prerequisites​

Prerequisites

Make sure you have the following installed:

  • Java 25
  • Node.js v24.2.0+ and pnpm (activated via corepack enable)
  • Docker and Docker Compose
  • Git

Docker Services​

Make sure Docker Desktop is running. For local development, you only need to run the services file which starts Keycloak and PostgreSQL:

docker compose -f docker/local-setup/services.yml up -d

This starts:

  • PostgreSQL on localhost:5432 — the application database (user, password and database: docapply)
  • Keycloak on localhost:9080 — the identity provider with a pre-configured dev realm

To stop the services:

docker compose -f docker/local-setup/services.yml down

Docker File Overview​

All Docker configuration files are located in the docker/ directory:

FilePurpose
docker/local-setup/services.ymlLocal development — starts Keycloak and PostgreSQL
docker/local-setup/keycloak.ymlKeycloak service definition for local development
docker/local-setup/postgres.ymlPostgreSQL service definition for local development

Starting the Application​

Once the Docker services are running, start the server and client in two separate terminals:

# Terminal 1 - Start Spring Boot without client build
./gradlew -x webapp

# Terminal 2 - Install pnpm dependencies and start Angular dev server
pnpm install
pnpm start

Starting the server will automatically apply all Liquibase migrations to the database.

note

If you encounter errors starting the server, ensure the PostgreSQL container is running and reachable.

Importing Test Data​

To populate the database with example data, run the import script. This automatically imports all SQL files from the src/main/resources/testdata/ folder, sorted alphabetically:

bash ./src/main/resources/testdata/import-testdata.sh

The script runs psql inside the postgres container, so no database client is needed on your machine (on Windows, run it from Git Bash). To import a single file manually:

docker compose -f docker/local-setup/services.yml exec -T postgres psql -U docapply -d docapply -v ON_ERROR_STOP=1 < src/main/resources/testdata/01_users.sql

Local LLM Setup​

If you want to use the AI features on the website then you need a local LLM instance. Follow the instructions in the Local LLM Setup Guide to get started.

Troubleshooting​

Common Issues
  • PostgreSQL container is not running (test data import): Start the Docker services first
  • password authentication failed for user "docapply": The local database uses user, password and database docapply; check SPRING_DATASOURCE_* if you overrode them
  • Connection refused on port 5432: Another PostgreSQL may already be using the port, or the container is not running
  • Unexpected build issues: Try running ./gradlew clean build to reset the environment