Skip to main content
OrgStack uses Spring Boot’s standard configuration approach with application.properties for environment-specific settings. This guide covers all configuration options available in the application.

​
Configuration file location

The main configuration file is located at: 
backend/src/main/resources/application.properties

​
Application configuration

​
Application name

The application is identified by its Spring application name:
application.properties
spring.application.name=backend
This name is used for logging, monitoring, and service identification.

​
Database configuration

OrgStack uses PostgreSQL as its primary database. All database settings are configured under the spring.datasource namespace.

​
Connection settings

​
spring.datasource.url
string
required
JDBC connection URL for the PostgreSQL database.
spring.datasource.url=jdbc:postgresql://localhost:5432/orgstack
Format: jdbc:postgresql://<host>:<port>/<database>
The default configuration connects to a local PostgreSQL instance on port 5432 with database name orgstack, matching the Docker Compose setup.
​
spring.datasource.username
string
required
Database username for authentication.
spring.datasource.username=orgstack
​
spring.datasource.password
string
required
Database password for authentication.
spring.datasource.password=orgstack_dev_password
This is a development password. In production, use environment variables or a secrets management system instead of hardcoding passwords.

​
Complete datasource configuration

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

​
JPA and Hibernate configuration

OrgStack uses Spring Data JPA with Hibernate as the JPA implementation. These settings control how JPA interacts with the database.

​
Schema management

​
spring.jpa.hibernate.ddl-auto
string
default:"validate"
Controls how Hibernate manages the database schema.
spring.jpa.hibernate.ddl-auto=validate
Possible values:
  • validate - Validates the schema without making changes (recommended for production)
  • update - Updates the schema automatically (use with caution)
  • create - Creates the schema, destroying previous data
  • create-drop - Creates schema on startup, drops on shutdown
  • none - No schema management
OrgStack uses validate to ensure database schema matches entity definitions without automatic modifications. Schema changes should be managed through migrations.

​
SQL logging

​
spring.jpa.show-sql
boolean
default:"false"
Controls whether SQL statements are logged to the console.
spring.jpa.show-sql=false
Set to true during development to see generated SQL queries.
​
spring.jpa.properties.hibernate.format_sql
boolean
default:"false"
Formats SQL output for better readability when show-sql is enabled.
spring.jpa.properties.hibernate.format_sql=false

​
Open Session in View

​
spring.jpa.open-in-view
boolean
default:"false"
Controls the Open Session in View (OSIV) pattern.
spring.jpa.open-in-view=false
OSIV is disabled (false) in OrgStack to prevent lazy loading issues and encourage explicit transaction boundaries. This follows best practices for clean layered architecture.

​
Complete JPA configuration

application.properties
# --- 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 configuration

​
server.port
integer
default:"8080"
The HTTP port the Spring Boot application listens on.
server.port=8080
The backend API will be accessible at http://localhost:8080.

​
Environment-specific configuration

For different environments (development, staging, production), you can create environment-specific property files: 
# Development settings
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
logging.level.com.orgstack=DEBUG
Activate a profile using: 
# Via command line
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# Via environment variable
export SPRING_PROFILES_ACTIVE=prod

​
Using environment variables

For sensitive configuration like database passwords, use environment variables: 
spring.datasource.url=${DATABASE_URL:jdbc:postgresql://localhost:5432/orgstack}
spring.datasource.username=${DATABASE_USER:orgstack}
spring.datasource.password=${DATABASE_PASSWORD:orgstack_dev_password}
The syntax ${VAR_NAME:default_value} uses the environment variable if set, otherwise falls back to the default.
1

Create a .env file (optional)

.env
DATABASE_URL=jdbc:postgresql://localhost:5432/orgstack
DATABASE_USER=orgstack
DATABASE_PASSWORD=your_secure_password
2

Load variables before running

export $(cat .env | xargs)
mvn spring-boot:run
Never commit .env files or files containing secrets to version control. Add them to .gitignore.

​
Configuration validation

To verify your configuration is correct:
1

Check database connectivity

# Test PostgreSQL connection
docker exec -it orgstack-postgres psql -U orgstack -d orgstack -c "SELECT version();"
2

Start the application

mvn spring-boot:run
Watch for any configuration errors in the startup logs.
3

Verify health endpoint

curl http://localhost:8080/actuator/health
Should return:
{"status":"UP"}

​
Troubleshooting

Symptoms: Connection refused or Could not connect to databaseSolutions:
  • Verify PostgreSQL is running: docker ps
  • Check database URL matches your setup
  • Ensure port 5432 is not blocked by firewall
  • Verify credentials match between application.properties and docker-compose.yml
Symptoms: Schema-validation: wrong column type encounteredSolutions:
  • Ensure database schema matches entity definitions
  • Run database migrations if needed
  • Temporarily use spring.jpa.hibernate.ddl-auto=update to sync schema (development only)
Symptoms: Port 8080 already in useSolutions:
  • Change server.port in application.properties
  • Stop the conflicting application
  • Find and kill the process: lsof -i :8080

​
Next steps

Data model

Learn about the entity structure and BaseEntity pattern

Development setup

Set up your complete development environment

Build docs developers (and LLMs) love

Get started for freeTalk to us