Docker

Docker Compose Setup for Infra Services

This document provides instructions on how to set up and run the infrastructure services using Docker Compose. The services included are PostgreSQL, Oracle Database and the oracle tables. Docker is a platform that enables developers to package applications into containers—standardized executable components that combine application source code with all the operating system libraries and dependencies required to run that code in any environment. Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application's services, networks, and volumes. Then, with a single command, you create and start all the services from your configuration.

This setup uses Docker Compose to orchestrate multiple infrastructure services, making it easy to start, stop, and manage them as a unified environment.

Prerequisites

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

• Docker or Podman
• Docker Compose (or Podman Compose)

Setting Up the Services

The Docker Compose configuration defines several infrastructure services that work together to support the Waste Plus application. The key infrastructure services are:

Database Services

PostgreSQL Database (database)

The PostgreSQL database serves as the primary data store for the modern backend service. This service:

• Runs PostgreSQL 13.23
• Listens on port 5432
• Uses the default credentials: postgres/default
• Is automatically initialized and migrated by the backend application on startup

The backend service connects to this database and handles all schema creation and data migrations internally. There is no need for external migration tools like Flyway for PostgreSQL, as the backend application manages its own database schema using its built-in migration capabilities.

Oracle Legacy Database (legacydb)

The Oracle database is a legacy system that the legacy service connects to. This service:

• Runs Oracle Database Free 23.9
• Listens on port 1521
• Uses the schema user THE with password default
• Requires explicit migration scripts to set up the schema and initial data

Unlike the PostgreSQL database, the Oracle database requires manual schema management because it represents a legacy system with a fixed schema structure, and our legacy service expects this schema to be pre-defined.

Flyway Migration Service (legacyflyway)

The Flyway service is a dedicated migration tool that initializes and manages the Oracle database schema. This service:

• Runs automatically after the legacydb service is healthy
• Executes SQL migration scripts from legacy/src/test/resources/db/migration
• Creates the necessary tables, views, and initial data in the Oracle database
• Only runs once during initial setup or when new migrations are added

Why Flyway for Oracle but not PostgreSQL?

The legacy Oracle database requires Flyway because:

• It represents a legacy system with a pre-defined, fixed schema
• The schema needs to be created from SQL scripts before the legacy service can use it
• The legacy service doesn't have built-in migration capabilities

The PostgreSQL database doesn't need Flyway because:

• The backend service is a modern Spring Boot application with built-in migration support
• The backend automatically creates and updates its database schema on startup
• This approach keeps database management logic within the application itself

Running the Services

To start the infrastructure services, navigate to the directory containing the docker-compose.yml file and run the following command:

docker compose up -d database legacydb legacyflyway

The most recent versions of Docker support the docker compose command natively. If you are using an older version, you may need to use docker-compose instead.

Depending on your company policies, you might need to use podman instead of docker. In that case, use the following command:

podman-compose up -d database legacydb legacyflyway

This command will start the PostgreSQL database, Oracle database, and Flyway migration service in detached mode.

Running the backend services

Once the infrastructure services are up and running, you can start the backend and legacy services. The backend service will connect to the PostgreSQL database, and the legacy service will connect to the Oracle database.

Make sure to read the Backend Structure documentation for instructions on how to setup the required parameters for the backend and legacy services to connect to the databases.

In order for it to run, you can use the following command from the root of the project:

docker compose up -d backend legacy

This command will start both backend services in detached mode.

Running the frontend services

After the backend services are running, you can start the frontend service. The frontend service connects to the backend services to provide the user interface for the Waste Plus application.

To start the frontend service, use the following command from the root of the project:

docker compose up -d frontend

Make sure to set all the appropriate environment variables for the frontend service to connect to the backend services. Refer to the Frontend Structure documentation for more details on the required configuration.

Setting up your own configuration

As you may have guessed, the provided docker-compose.yml file is a basic setup for local development and testing purposes, but it does not cover all the configuration options needed for each application. In order for it to work properly, you will need to set up your own configuration files or environment variables for each service. To avoid committing sensitive information to version control, it is recommended to use environment variable files (.env files) or the docker compose override feature to manage your configurations securely.

Using Environment Variables with .env Files

Docker Compose automatically loads environment variables from a .env file located in the same directory as your docker-compose.yml file. This is useful for managing configuration values that may differ between environments or contain sensitive information.

How to set up a .env file:

1. Create a new file named .env in the root directory of the project (where docker-compose.yml is located)

2. Add your environment variables in the format KEY=VALUE, one per line:

   # Database credentials
   POSTGRES_USER=myuser
   POSTGRES_PASSWORD=mysecretpassword
   POSTGRES_DATABASE=mydb
   
   # Application settings
   BACKEND_PORT=8080
   LEGACY_PORT=9090

3. Reference these variables in your docker-compose.yml or override file using the ${VARIABLE_NAME} syntax

Important: The .env file is already configured to be ignored by Git (listed in .gitignore), so you can safely store local configuration and secrets without accidentally committing them to version control.

For more information about environment variables in Docker Compose, refer to the official documentation.

Using Docker Compose Override Files

Docker Compose supports an override mechanism that allows you to customize the configuration without modifying the base docker-compose.yml file. This is particularly useful for:

• Adding local development settings
• Overriding ports, volumes, or environment variables
• Enabling debugging features
• Mounting local code directories for hot-reload during development

How to use docker-compose.override.yml:

1. Create a new file named docker-compose.override.yml in the same directory as docker-compose.yml

2. Define only the services and settings you want to override or extend:

   services:
     backend:
       environment:
         SPRING_PROFILES_ACTIVE: local
         DEBUG: "true"
       volumes:
         - ./backend/src:/app/src  # Mount source code for hot-reload
       ports:
         - "8081:8080"  # Use a different host port
     
     frontend:
       environment:
         VITE_API_URL: http://localhost:8081
       command: npm run dev  # Override to use dev mode

3. When you run docker compose up, Docker Compose automatically merges docker-compose.yml with docker-compose.override.yml

Key features of override files:

• Override files are applied on top of the base configuration
• You can override individual properties (like environment variables or ports) without duplicating the entire service definition
• Arrays (like ports or volumes) are merged, not replaced
• The override file takes precedence when there are conflicts

Important: The docker-compose.override.yml file is also configured to be ignored by Git (listed in .gitignore), allowing you to customize your local setup without affecting other developers or the repository.

Alternative override files:

You can also use named override files for specific scenarios:

# Use a specific override file
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# Use multiple override files
docker compose -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.debug.yml up

For comprehensive information about Docker Compose override files and their behavior, consult the official Docker Compose documentation on extending services.

Best Practices

• Never commit sensitive data: Both .env and docker-compose.override.yml are git-ignored to prevent accidental commits of secrets
• Document required variables: Create a .env.example file with placeholder values to help other developers understand what variables are needed
• Use override files for local customization: Keep the base docker-compose.yml generic and use override files for environment-specific settings
• Keep it simple: Only override what you need to change; unnecessary overrides can make the configuration harder to maintain