Skip to main content
This guide walks you through setting up a complete development environment for OrgStack, a multi-tenant organization management platform.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:
1

Install Java 25

OrgStack requires Java 25. Download and install the JDK from Oracle or use SDKMAN:
# Using SDKMAN
sdk install java 25-open
sdk use java 25-open
Verify your installation:
java -version
The project is configured to use Java 25 in pom.xml. Using a different version may cause compatibility issues.
2

Install Apache Maven

Maven is used for dependency management and building the backend. Download Maven from the official website or use a package manager:
# macOS
brew install maven

# Ubuntu/Debian
sudo apt-get install maven
Verify the installation:
mvn -version
3

Install Docker and Docker Compose

Docker is used to run PostgreSQL locally. Install Docker Desktop for your operating system.Verify Docker is running:
docker --version
docker compose version
4

Install Node.js (for Angular)

The frontend is built with Angular and requires Node.js. Install Node.js 18 or later from nodejs.org or use nvm:
# Using nvm
nvm install 18
nvm use 18
Verify the installation:
node -version
npm -version

​
Clone the repository

Clone the OrgStack repository to your local machine: 
git clone <repository-url>
cd orgstack

​
Set up the database

OrgStack uses PostgreSQL 16 as its primary database. The project includes a Docker Compose configuration for easy setup.
1

Start PostgreSQL with Docker Compose

The docker-compose.yml file configures a PostgreSQL container with the necessary credentials:
docker-compose.yml
services:
  postgres:
    image: postgres:16
    container_name: orgstack-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: orgstack
      POSTGRES_USER: orgstack
      POSTGRES_PASSWORD: orgstack_dev_password
    ports:
      - "5432:5432"
    volumes:
      - orgstack_pg_data:/var/lib/postgresql/data
volumes:
  orgstack_pg_data:
Start the database:
docker compose up -d
The -d flag runs the container in detached mode (in the background).
2

Verify the database is running

Check that the PostgreSQL container is running:
docker ps
You should see orgstack-postgres in the list of running containers.You can also connect to the database to verify:
docker exec -it orgstack-postgres psql -U orgstack -d orgstack
Type \q to exit the PostgreSQL prompt.
The default password orgstack_dev_password is for development only. Never use this password in production environments.

​
Build and run the backend

With the database running, you can now build and start the Spring Boot backend.
1

Navigate to the backend directory

cd backend
2

Install dependencies

Maven will download all required dependencies specified in pom.xml:
mvn clean install
This command:
  • Cleans any previous build artifacts
  • Downloads dependencies (Spring Boot 4.0.3, PostgreSQL driver, Lombok, etc.)
  • Compiles the Java code
  • Runs tests
  • Packages the application
3

Run the application

Start the Spring Boot application:
mvn spring-boot:run
The backend will start on port 8080. You should see output indicating the application has started successfully:
Started BackendApplication in X.XXX seconds
4

Verify the backend is running

Test the application by accessing the actuator health endpoint:
curl http://localhost:8080/actuator/health
You should receive a response like:
{"status":"UP"}

​
Set up the frontend

The OrgStack frontend is built with Angular and uses Spartan NG components.
1

Navigate to the frontend directory

cd frontend
2

Install dependencies

Install all npm packages:
npm install
3

Run the development server

Start the Angular development server:
npm start
The frontend will typically run on http://localhost:4200 and will automatically reload when you make changes to the source files.

​
Development workflow

With everything set up, your typical development workflow will be: 
# Terminal 1: Database
docker compose up

# Terminal 2: Backend
cd backend
mvn spring-boot:run

# Terminal 3: Frontend
cd frontend
npm start

# Stop frontend and backend: Ctrl+C in their terminals

# Stop database
docker compose down

​
Troubleshooting

If port 8080 or 5432 is already in use, you’ll need to either:
  • Stop the conflicting service
  • Change the port in application.properties (backend) or docker-compose.yml (database)
Ensure:
  • PostgreSQL container is running: docker ps
  • Database credentials in application.properties match docker-compose.yml
  • Port 5432 is accessible and not blocked by a firewall
Try:
  • Clearing Maven cache: mvn clean
  • Updating dependencies: mvn clean install -U
  • Verifying Java version: java -version (should be 25)

​
Next steps

Configuration

Learn how to configure database connections, server settings, and JPA properties

Data model

Understand the entity structure and BaseEntity pattern

Build docs developers (and LLMs) love

Get started for freeTalk to us