Skip to main content
This guide shows you how to use Docker and Docker Compose to run OrgStack’s PostgreSQL database and connect your Spring Boot application to it.

​
Prerequisites

1

Install Docker

Download and install Docker Desktop from docker.com:
  • macOS: Download Docker Desktop for Mac
  • Windows: Download Docker Desktop for Windows
  • Linux: Install Docker Engine using your package manager
# Verify installation
docker --version
docker compose version
Docker Compose is included with Docker Desktop. On Linux, you may need to install it separately.
2

Install Java 25

You still need Java 25 installed to run the Spring Boot application locally:
# Verify Java installation
java -version
See the local development guide for detailed Java installation instructions.

​
Docker Compose configuration

OrgStack includes a docker-compose.yml file that defines the PostgreSQL database service: 
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:
This configuration creates a PostgreSQL 16 container with persistent storage using a Docker volume named orgstack_pg_data.

​
Starting the database

From the root directory of the project, start the PostgreSQL container: 
docker compose up
Docker will:
  1. Pull the PostgreSQL 16 image if not already downloaded
  2. Create a container named orgstack-postgres
  3. Initialize the database with the specified credentials
  4. Expose PostgreSQL on port 5432
Use the -d flag to run the container in the background. You can view logs anytime with docker compose logs -f.

​
Verify the database is running

Check that the PostgreSQL container is running: 
docker compose ps
You should see output similar to: 
NAME                  IMAGE         STATUS         PORTS
orgstack-postgres     postgres:16   Up 2 minutes   0.0.0.0:5432->5432/tcp
1

Test the connection

Connect to the database using the PostgreSQL client:
docker compose exec postgres psql -U orgstack -d orgstack
You should see the PostgreSQL prompt. Exit with \q.
2

View logs

Check the PostgreSQL logs to ensure it started correctly:
docker compose logs postgres

​
Running the Spring Boot application

With PostgreSQL running in Docker, you can start the Spring Boot application locally: 
cd backend
./mvnw spring-boot:run
The application will connect to the PostgreSQL container using the configuration in application.properties: 
spring.datasource.url=jdbc:postgresql://localhost:5432/orgstack
spring.datasource.username=orgstack
spring.datasource.password=orgstack_dev_password
The Spring Boot application runs on your host machine and connects to the containerized database on localhost:5432.

​
Managing the Docker containers

docker compose stop
This stops the containers but preserves data in the volumes.
docker compose start

docker compose down
This removes the containers but keeps the data volume. Your database data is preserved.
docker compose down -v
The -v flag removes the volume, deleting all database data. Use with caution!
# Follow logs in real-time
docker compose logs -f

# View logs for specific service
docker compose logs postgres

​
Persisting data

The Docker Compose configuration uses a named volume orgstack_pg_data to persist database data: 
volumes:
  - orgstack_pg_data:/var/lib/postgresql/data
This means:
  • Data survives container restarts
  • Data persists when you run docker compose down
  • Data is only deleted with docker compose down -v
To view all Docker volumes: docker volume ls

​
Database backup and restore

1

Create a backup

docker compose exec postgres pg_dump -U orgstack orgstack > backup.sql
This creates a SQL dump of the database in backup.sql.
2

Restore from backup

docker compose exec -T postgres psql -U orgstack orgstack < backup.sql
This will overwrite existing data in the database.

​
Containerizing the Spring Boot application

While the current setup runs PostgreSQL in Docker and the application on your host, you can containerize the entire application:
1

Create a Dockerfile

Create backend/Dockerfile:
FROM eclipse-temurin:25-jdk-alpine AS build
WORKDIR /app
COPY pom.xml mvnw ./
COPY .mvn .mvn
RUN ./mvnw dependency:go-offline
COPY src src
RUN ./mvnw package -DskipTests

FROM eclipse-temurin:25-jre-alpine
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
2

Add to docker-compose.yml

Extend the Docker Compose configuration to include the backend:
services:
  postgres:
    # ... existing postgres config ...

  backend:
    build: ./backend
    container_name: orgstack-backend
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/orgstack
      SPRING_DATASOURCE_USERNAME: orgstack
      SPRING_DATASOURCE_PASSWORD: orgstack_dev_password
    depends_on:
      - postgres
When services communicate within Docker Compose, use the service name (e.g., postgres) as the hostname instead of localhost.
3

Run the full stack

docker compose up --build

​
Troubleshooting

If you have PostgreSQL installed locally and running, it may conflict with the Docker container. Either:
  1. Stop the local PostgreSQL service: 
    # macOS
brew services stop postgresql@16

# Linux
sudo systemctl stop postgresql
  2. Or change the port mapping in docker-compose.yml: 
    ports:
  - "5433:5432"  # Map to host port 5433
    Then update application.properties: 
    spring.datasource.url=jdbc:postgresql://localhost:5433/orgstack
Ensure the container is running:
docker compose ps
Check the logs for errors:
docker compose logs postgres
Verify the connection parameters match between docker-compose.yml and application.properties.
Ensure you’re using docker compose stop or docker compose down without the -v flag. Using -v removes the data volume:
# Preserves data
docker compose down

# Deletes data
docker compose down -v

​
Next steps

Local development

Set up for development without Docker

Production deployment

Deploy OrgStack to production

Build docs developers (and LLMs) love

Get started for freeTalk to us