Skip to main content
This guide walks you through setting up OrgStack for local development on your machine.

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Install Java 25

OrgStack requires Java 25. Download and install it from Oracle or use a package manager:
# macOS with Homebrew
brew install openjdk@25

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install openjdk-25-jdk
Verify your installation:
java -version
The output should show Java version 25 or higher.
2

Install Maven

Maven is used for building and managing dependencies. You can use the Maven wrapper included in the project, or install Maven globally:
# macOS with Homebrew
brew install maven

# Linux (Ubuntu/Debian)
sudo apt install maven
The project includes Maven wrapper scripts (mvnw and mvnw.cmd), so you don’t need to install Maven separately if you prefer to use the wrapper.
3

Install PostgreSQL

You need PostgreSQL 16 or higher for the database:
# macOS with Homebrew
brew install postgresql@16
brew services start postgresql@16

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install postgresql-16
sudo systemctl start postgresql
Alternatively, you can use Docker to run PostgreSQL (see the Docker setup guide).

​
Database setup

Create the database and user for OrgStack:
1

Connect to PostgreSQL

psql -U postgres
2

Create database and user

CREATE DATABASE orgstack;
CREATE USER orgstack WITH PASSWORD 'orgstack_dev_password';
GRANT ALL PRIVILEGES ON DATABASE orgstack TO orgstack;
The password orgstack_dev_password is for local development only. Never use this password in production.
3

Exit PostgreSQL

\q

​
Configuration

The default configuration in backend/src/main/resources/application.properties is set up for local development: 
spring.application.name=backend

# --- Datasource ---
spring.datasource.url=jdbc:postgresql://localhost:5432/orgstack
spring.datasource.username=orgstack
spring.datasource.password=orgstack_dev_password

# --- JPA ---
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=false
spring.jpa.properties.hibernate.format_sql=false
spring.jpa.open-in-view=false

# -- Server
server.port=8080
You can override these settings using environment variables or by creating an application-local.properties file.

​
Running the application

You have two options for running the Spring Boot application: 
cd backend
./mvnw spring-boot:run
The application will start on http://localhost:8080.
Use ./mvnw clean install to build the project and run tests before starting the application.

​
Verify the setup

Once the application is running, you can verify it’s working:
1

Check the health endpoint

curl http://localhost:8080/actuator/health
You should receive a response indicating the application is up:
{"status":"UP"}
2

Check the logs

Review the console output for any errors or warnings. The application should start without issues if the database connection is successful.

​
Development workflow

1

Make code changes

Edit the source code in your preferred IDE or text editor.
2

Rebuild and restart

Stop the application (Ctrl+C) and restart it with ./mvnw spring-boot:run to see your changes.
Consider using Spring Boot DevTools for automatic restarts during development. Add it as a dependency in pom.xml for a faster development cycle.
3

Run tests

./mvnw test

​
Troubleshooting

Ensure PostgreSQL is running:
# macOS
brew services list

# Linux
sudo systemctl status postgresql
Check that the database exists and the user has proper permissions:
psql -U orgstack -d orgstack -h localhost
OrgStack requires Java 25. Check your Java version:
java -version
If you have multiple Java versions installed, set JAVA_HOME to point to Java 25:
export JAVA_HOME=/path/to/java-25
If another application is using port 8080, you can change the port in application.properties:
server.port=8081
Or set it as an environment variable:
SERVER_PORT=8081 ./mvnw spring-boot:run

​
Next steps

Docker setup

Use Docker Compose for containerized development

Production deployment

Learn how to deploy OrgStack to production

Build docs developers (and LLMs) love

Get started for freeTalk to us