Dockerizing Spring Boot Application with Database and Vite Frontend: A Comprehensive Guide

In today’s microservices-driven world, containerization is paramount. Docker provides a way to package applications and their dependencies into portable containers, ensuring consistency across different environments. This guide provides a comprehensive walkthrough of Dockerizing a Spring Boot application with a database backend (e.g., PostgreSQL) and a Vite-powered frontend (e.g., React, Vue, Svelte). We’ll cover everything from setting up the application to building and running the Docker containers, complete with best practices for optimization and maintainability.

Why Dockerize Your Spring Boot, Database, and Vite Frontend?

Before we dive into the specifics, let’s explore the benefits of Dockerizing our entire stack:

1. Consistency: Docker ensures consistent application behavior across development, testing, and production environments. No more “it works on my machine” issues.
2. Portability: Docker containers can be easily moved and deployed to various platforms and cloud providers.
3. Scalability: Docker simplifies scaling your application by allowing you to create multiple instances of your services.
4. Isolation: Containers isolate applications from each other, preventing conflicts and improving security.
5. Resource Efficiency: Docker containers share the host operating system kernel, making them more resource-efficient than virtual machines.
6. Simplified Deployment: Docker streamlines the deployment process, making it faster and more reliable.
7. Version Control: Docker images can be version controlled, allowing you to easily roll back to previous versions.

Prerequisites

Before you begin, make sure you have the following installed:

• Java Development Kit (JDK): Version 8 or higher.
• Maven or Gradle: For building the Spring Boot application.
• Node.js and npm/yarn/pnpm: For building the Vite frontend.
• Docker: Docker Desktop or Docker Engine installed and running.
• Basic understanding of Spring Boot, Databases (e.g., PostgreSQL), and Vite.

Part 1: Setting Up the Spring Boot Application

1.1. Creating a Simple Spring Boot Application

Let’s start by creating a simple Spring Boot application using Spring Initializr (start.spring.io). Choose the following dependencies:

• Spring Web
• Spring Data JPA (for database interaction)
• PostgreSQL Driver (or your preferred database driver)
• Lombok (optional, for reducing boilerplate code)

Generate the project and import it into your IDE (e.g., IntelliJ IDEA, Eclipse).

1.2. Defining the Data Model

Create a simple entity class to represent your data. For example, let’s create a `Product` entity:

Product.java

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private String description;
    private Double price;

    // Getters and setters...

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public Double getPrice() {
        return price;
    }

    public void setPrice(Double price) {
        this.price = price;
    }
}

1.3. Creating the Repository Interface

Create a repository interface to interact with the database:

ProductRepository.java

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface ProductRepository extends JpaRepository<Product, Long> {
}

1.4. Building the REST Controller

Create a REST controller to expose endpoints for managing products:

ProductController.java

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @Autowired
    private ProductRepository productRepository;

    @GetMapping
    public List<Product> getAllProducts() {
        return productRepository.findAll();
    }

    @PostMapping
    public Product createProduct(@RequestBody Product product) {
        return productRepository.save(product);
    }

    @GetMapping("/{id}")
    public Product getProductById(@PathVariable Long id) {
        return productRepository.findById(id).orElse(null);
    }

    @PutMapping("/{id}")
    public Product updateProduct(@PathVariable Long id, @RequestBody Product product) {
        product.setId(id);
        return productRepository.save(product);
    }

    @DeleteMapping("/{id}")
    public void deleteProduct(@PathVariable Long id) {
        productRepository.deleteById(id);
    }
}

1.5. Configuring the Database Connection

Configure the database connection in your `application.properties` or `application.yml` file. For PostgreSQL, it might look like this:

application.properties

spring.datasource.url=jdbc:postgresql://localhost:5432/mydb
spring.datasource.username=myuser
spring.datasource.password=mypassword
spring.jpa.hibernate.ddl-auto=update

Remember to replace `mydb`, `myuser`, and `mypassword` with your actual database credentials.

Part 2: Setting Up the Vite Frontend

2.1. Creating a Vite Project

Create a new Vite project using your preferred framework (React, Vue, Svelte). For example, to create a React project:

npm create vite my-vite-app --template react
cd my-vite-app

2.2. Fetching Data from the Spring Boot API

In your frontend application, create components to fetch and display data from the Spring Boot API. For example, you might have a component that fetches the list of products and renders them in a table:

src/components/ProductList.jsx (React example)

import React, { useState, useEffect } from 'react';

function ProductList() {
  const [products, setProducts] = useState([]);

  useEffect(() => {
    fetch('http://localhost:8080/api/products') // Replace with your Spring Boot API URL
      .then(response => response.json())
      .then(data => setProducts(data));
  }, []);

  return (
    <div>
      <h2>Products</h2>
      <ul>
        {products.map(product => (
          <li key={product.id}>{product.name} - ${product.price}</li>
        ))}
      </ul>
    </div>
  );
}

export default ProductList;

Remember to replace `http://localhost:8080/api/products` with the actual URL of your Spring Boot API.

2.3. Building the Frontend

Build the frontend application for production:

npm run build

This will create a `dist` directory containing the production-ready frontend assets.

Part 3: Dockerizing the Spring Boot Application

3.1. Creating a Dockerfile for the Spring Boot Application

Create a `Dockerfile` in the root directory of your Spring Boot project:

Dockerfile

FROM openjdk:17-jdk-slim

ARG JAR_FILE=target/*.jar

COPY ${JAR_FILE} app.jar

ENTRYPOINT ["java","-jar","/app.jar"]

Explanation:

• `FROM openjdk:17-jdk-slim`: Uses the official OpenJDK 17 slim image as the base image. Adjust to your JDK version.
• `ARG JAR_FILE=target/*.jar`: Defines an argument for the JAR file path.
• `COPY ${JAR_FILE} app.jar`: Copies the JAR file to the container and renames it to `app.jar`.
• `ENTRYPOINT [“java”,”-jar”,”/app.jar”]`: Specifies the command to run when the container starts.

3.2. Building the Spring Boot Docker Image

Build the Docker image using the following command in the root directory of your Spring Boot project:

docker build -t spring-boot-app .

This will build an image named `spring-boot-app`.

Part 4: Dockerizing the Database (PostgreSQL)

4.1. Using the Official PostgreSQL Docker Image

We’ll use the official PostgreSQL Docker image to create a database container. This is the simplest approach.

4.2. Running the PostgreSQL Container

Run the PostgreSQL container with the following command:

docker run --name postgresdb -e POSTGRES_USER=myuser -e POSTGRES_PASSWORD=mypassword -e POSTGRES_DB=mydb -p 5432:5432 -d postgres:latest

Explanation:

• `–name postgresdb`: Assigns the name `postgresdb` to the container.
• `-e POSTGRES_USER=myuser`: Sets the PostgreSQL user to `myuser`.
• `-e POSTGRES_PASSWORD=mypassword`: Sets the PostgreSQL password to `mypassword`.
• `-e POSTGRES_DB=mydb`: Sets the database name to `mydb`.
• `-p 5432:5432`: Maps port 5432 on the host to port 5432 in the container.
• `-d postgres:latest`: Runs the `postgres:latest` image in detached mode (background).

Important: Make sure the database credentials in your `application.properties` file match the environment variables used when running the PostgreSQL container.

4.3. (Optional) Dockerfile for Database Initialization

For more advanced scenarios, you might want to create a Dockerfile to initialize the database with specific schemas and data. This involves creating SQL scripts and copying them into the container. This is beyond the scope of this basic tutorial but is a valuable optimization for production environments.

Part 5: Dockerizing the Vite Frontend

5.1. Creating a Dockerfile for the Vite Frontend

Create a `Dockerfile` in the root directory of your Vite project:

Dockerfile

# Stage 1: Build the application
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Stage 2: Serve the application with Nginx
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Explanation:

• Stage 1 (builder):
  • `FROM node:18-alpine AS builder`: Uses a Node.js image for building the application. Adjust the Node.js version as needed. The `AS builder` assigns the alias “builder” to this stage.
  • `WORKDIR /app`: Sets the working directory inside the container.
  • `COPY package*.json ./`: Copies the `package.json` and `package-lock.json` files to the container.
  • `RUN npm install`: Installs the dependencies.
  • `COPY . .`: Copies the rest of the source code to the container.
  • `RUN npm run build`: Builds the frontend application.
• Stage 2 (nginx):
  • `FROM nginx:alpine`: Uses the official Nginx Alpine image as the base image for serving the application.
  • `COPY –from=builder /app/dist /usr/share/nginx/html`: Copies the built frontend assets from the “builder” stage to the Nginx document root.
  • `EXPOSE 80`: Exposes port 80.
  • `CMD [“nginx”, “-g”, “daemon off;”]`: Starts the Nginx server.

5.2. Building the Frontend Docker Image

Build the Docker image using the following command in the root directory of your Vite project:

docker build -t vite-frontend .

This will build an image named `vite-frontend`.

Part 6: Docker Compose (Orchestration)

Docker Compose simplifies the process of managing multiple containers. We’ll create a `docker-compose.yml` file to define and run our Spring Boot application, database, and frontend together.

6.1. Creating the docker-compose.yml File

Create a `docker-compose.yml` file in the root directory of your project (one level above the Spring Boot and Vite project directories). It should look something like this:

docker-compose.yml

version: "3.8"
services:
  db:
    image: postgres:latest
    container_name: postgresdb
    environment:
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - mynetwork

  backend:
    build:
      context: ./spring-boot-app  # Path to your Spring Boot project directory
    container_name: spring-boot-app
    ports:
      - "8080:8080"
    depends_on:
      - db
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/mydb
      SPRING_DATASOURCE_USERNAME: myuser
      SPRING_DATASOURCE_PASSWORD: mypassword
    networks:
      - mynetwork

  frontend:
    build:
      context: ./vite-frontend  # Path to your Vite project directory
    container_name: vite-frontend
    ports:
      - "80:80"
    depends_on:
      - backend
    networks:
      - mynetwork

volumes:
  db_data:

networks:
  mynetwork:

Explanation:

• `version: “3.8”`: Specifies the Docker Compose file version.
• `services:`: Defines the services (containers) that will be run.
  • `db`: Defines the PostgreSQL database service.
    • `image: postgres:latest`: Uses the official PostgreSQL image.
    • `container_name: postgresdb`: Sets the container name.
    • `environment:`: Sets environment variables for the database.
    • `ports:`: Maps port 5432.
    • `volumes:`: Mounts a volume to persist the database data.
    • `networks`: Assigns the service to the `mynetwork` network.
  • `backend`: Defines the Spring Boot application service.
    • `build:`: Specifies the build context and Dockerfile.
    • `context: ./spring-boot-app`: Path to the Spring Boot project directory
    • `container_name: spring-boot-app`: Sets the container name.
    • `ports:`: Maps port 8080.
    • `depends_on:`: Specifies that the Spring Boot application depends on the database service.
    • `environment:`: Sets environment variables for the database connection. Crucially, the `SPRING_DATASOURCE_URL` now uses `db` as the hostname, resolving to the database container’s IP address within the Docker network.
    • `networks`: Assigns the service to the `mynetwork` network.
  • `frontend`: Defines the Vite frontend service.
    • `build:`: Specifies the build context and Dockerfile.
    • `context: ./vite-frontend`: Path to the Vite project directory
    • `container_name: vite-frontend`: Sets the container name.
    • `ports:`: Maps port 80.
    • `depends_on:`: Specifies that the frontend depends on the backend.
    • `networks`: Assigns the service to the `mynetwork` network.
• `volumes:`: Defines the named volume for persistent database storage.
• `networks`: Defines a Docker network called `mynetwork` so the services can communicate by their service names.

Important Considerations for `docker-compose.yml`

• Context Paths: Double-check the `context` paths in the `build` section for both `backend` and `frontend` to ensure they correctly point to your Spring Boot and Vite project directories.
• Database Hostname: Note that `SPRING_DATASOURCE_URL` uses `db` as the hostname for the database. This works because Docker Compose creates a network that allows containers to resolve each other by their service names.
• Depends_on: The `depends_on` directive tells Docker Compose to start the services in the specified order. The `frontend` depends on the `backend`, and the `backend` depends on the `db`. This ensures that the database is running before the Spring Boot application tries to connect to it.
• Volumes: The `db_data` volume ensures that your database data is persisted even when the container is stopped or removed. Without a volume, your data will be lost.

6.2. Running Docker Compose

Navigate to the directory containing the `docker-compose.yml` file and run the following command:

docker-compose up -d

This will build and start all the containers defined in the `docker-compose.yml` file in detached mode (background).

6.3. Accessing the Application

Once the containers are running, you can access the application in your browser at `http://localhost`. The frontend will be served by Nginx, and it will communicate with the Spring Boot API, which in turn will interact with the PostgreSQL database.

Part 7: Optimizations and Best Practices

7.1. Using Multi-Stage Builds

We already used a multi-stage build for the Vite frontend. Multi-stage builds are an excellent way to reduce the size of your Docker images. They allow you to use different base images for different stages of the build process, only copying the necessary artifacts to the final image. We used it for the frontend, but you can adapt the same approach for the Spring Boot application as well. This might involve using a builder image with the JDK and Maven/Gradle to build the application, and then copying the JAR file to a smaller JRE-only image for running the application.

7.2. Using .dockerignore

Create a `.dockerignore` file in the root directory of your Spring Boot and Vite projects to exclude unnecessary files and directories from being copied into the Docker image. This can significantly reduce the image size and build time. Common entries include:

• `target/` (for Spring Boot)
• `node_modules/` (for Vite)
• `.git/`
• `*.log`

7.3. Environment Variables

Use environment variables to configure your application instead of hardcoding values in your code or configuration files. This makes your application more flexible and portable. We already use environment variables for the database credentials, but you can extend this to other configuration options as well.

7.4. Health Checks

Define health checks in your `docker-compose.yml` file to monitor the health of your containers. This allows Docker Compose to automatically restart unhealthy containers. A simple health check for the Spring Boot application might involve making a request to a health endpoint (e.g., `/actuator/health`).

7.5. Logging

Configure your application to log to standard output (stdout). Docker will automatically capture and manage the logs from your containers.

7.6. Security

Follow security best practices when building and deploying your Docker images. This includes:

• Using minimal base images.
• Keeping your base images up to date.
• Running containers as non-root users.
• Scanning your images for vulnerabilities.
• Using secrets management tools to store sensitive information.

7.7 Database Migration Tools

Use a database migration tool like Flyway or Liquibase to manage database schema changes. This ensures that your database is always in a consistent state, even when deploying new versions of your application.

Part 8: Troubleshooting

8.1. Container Not Starting

If a container fails to start, check the logs using `docker logs `. The logs will often provide clues about the cause of the problem.

8.2. Database Connection Issues

If your Spring Boot application fails to connect to the database, make sure the database container is running and the database credentials in your `application.properties` or `application.yml` file are correct. Also, ensure that the `SPRING_DATASOURCE_URL` is correctly configured to use the database container’s hostname (`db` in our example).

8.3. Frontend Not Displaying

If the frontend is not displaying correctly, check the Nginx logs for errors. Also, make sure the frontend application is built correctly and the built assets are copied to the correct location in the Nginx container.

8.4. Port Conflicts

If you encounter port conflicts, make sure no other applications are using the same ports as your Docker containers. You can change the port mappings in your `docker-compose.yml` file.

Conclusion

This guide has provided a comprehensive walkthrough of Dockerizing a Spring Boot application with a database and a Vite frontend. By following these steps, you can create portable, consistent, and scalable applications that can be easily deployed to any environment. Remember to apply best practices for optimization and security to ensure the reliability and security of your applications. Dockerizing your full-stack applications significantly improves the development, deployment, and maintenance workflows. Good luck!