Skip to main content
OrgStack is a starter template currently in early development. This quickstart gets you running with the foundational infrastructure (Spring Boot application, PostgreSQL database, BaseEntity with JPA auditing). See the architecture guide for the planned feature set.

​
Get OrgStack running locally

This guide walks you through cloning the repository, starting the database with Docker Compose, and running the Spring Boot skeleton application locally.
1

Clone the repository

Clone the OrgStack repository to your local machine:
git clone https://github.com/louayhouimli/orgstack.git
cd orgstack
2

Start PostgreSQL with Docker Compose

OrgStack includes a Docker Compose configuration for the PostgreSQL database. Start it with:
docker compose up -d
This starts PostgreSQL 16 with the following configuration:
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
The database runs on port 5432 and persists data in a Docker volume named orgstack_pg_data.
Verify PostgreSQL is running:
docker ps
You should see the orgstack-postgres container running.
3

Run the Spring Boot backend

Navigate to the backend directory and start the application:
cd backend
./mvnw 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
If you don’t have Maven installed, the project includes the Maven wrapper (mvnw) which will automatically download the correct version.
4

Verify the application is running

Open your browser and navigate to:
http://localhost:8080
You can also check the Spring Boot Actuator health endpoint:
curl http://localhost:8080/actuator/health
If you see a response, congratulations! OrgStack is running successfully.

​
What you just deployed

Your local OrgStack setup includes:

PostgreSQL 16

Relational database ready for the orgstack schema

Spring Boot application

Skeleton Spring Boot app running on port 8080 with foundational dependencies (Spring Security, JPA, Actuator)
The application currently runs with minimal functionality. It provides the infrastructure foundation (BaseEntity, JpaConfig) but does not yet include controllers, services, or API endpoints. See the planned architecture for details on the intended implementation.

​
Understanding the setup

​
Database configuration

The backend connects to PostgreSQL using the configuration in application.properties:
backend/src/main/resources/application.properties
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
The ddl-auto=validate setting means Hibernate will validate the database schema but not modify it. You’ll need to manage schema migrations separately (e.g., with Flyway or Liquibase).

​
JPA auditing

OrgStack automatically tracks creation and modification timestamps on all entities:
com/orgstack/config/JpaConfig.java
@Configuration
@EnableJpaAuditing
public class JpaConfig {
}
All entities extend BaseEntity, which provides:
  • UUID id - Unique identifier
  • Instant createdAt - Creation timestamp
  • Instant updatedAt - Last modification timestamp
com/orgstack/common/BaseEntity.java
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
@Getter
public class BaseEntity {
    @Column(nullable = false, updatable = false)
    private UUID id;
    
    @CreatedDate
    @Column(nullable = false, updatable = false)
    private Instant createdAt;
    
    @LastModifiedDate
    @Column(nullable = false)
    private Instant updatedAt;

    protected BaseEntity() {
        this.id = UUID.randomUUID();
    }
}

​
Development workflow

​
Running in development mode

For active development, you can use Spring Boot DevTools for automatic restarts: 
cd backend
./mvnw spring-boot:run
Any changes to Java files will trigger an automatic restart.

​
Stopping the services

To stop PostgreSQL: 
docker compose down
To stop the Spring Boot application, press Ctrl+C in the terminal where it’s running.
The database data persists in a Docker volume, so you won’t lose data when stopping the container.

​
Removing all data

To completely remove the database and all data: 
docker compose down -v
The -v flag removes the volume containing the database data.

​
Prerequisites

Before you start, make sure you have:
OrgStack requires Java 25. Check your version:
java -version
Download from Oracle or use SDKMAN to manage Java versions.
Docker is required to run PostgreSQL. Check your installation:
docker --version
docker compose version
Download from docker.com.
Git is required to clone the repository:
git --version
Download from git-scm.com.

​
Next steps

Now that you have OrgStack running locally, explore these topics:

Multi-tenancy concepts

Learn how OrgStack implements strict tenant isolation

Authentication

Understand JWT-based authentication with Spring Security

Architecture overview

Explore the layered architecture and design patterns

Development setup

Set up your IDE and start building features

​
Troubleshooting

If you have another PostgreSQL instance running, stop it or change the port in docker-compose.yml:
ports:
  - "5433:5432"  # Use port 5433 on host
Update application.properties to match:
spring.datasource.url=jdbc:postgresql://localhost:5433/orgstack
If port 8080 is in use, change the server port in application.properties:
server.port=8081
Ensure PostgreSQL is running:
docker ps
Check the logs:
docker logs orgstack-postgres
Try connecting with psql:
docker exec -it orgstack-postgres psql -U orgstack -d orgstack
Clear the Maven cache and rebuild:
./mvnw clean install
If you’re behind a proxy, configure it in ~/.m2/settings.xml.
Need help? Open an issue on GitHub or check the development guide for more detailed setup instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us