A fullstack Todo List Application using Docker for easy development, testing, and deployment. Features a Spring Boot backend, React.js frontend, PostgreSQL database, and Jaeger tracing for observability.
The Todo List Application is a fullstack web application that provides a convenient interface for managing a to-do list. It utilizes Docker containers to encapsulate the backend, frontend, and database components, ensuring a consistent and easily reproducible environment for development, testing, and production.
This application is designed to run using Docker Compose, which orchestrates multiple containers to work together. The provided docker-compose.yml
file contains the configuration needed to build and run the application services.
Before you can use Docker Compose to run the application, you must install:
- Docker
- Docker Compose
Refer to the official Docker documentation for instructions on installing Docker, and the Docker Compose documentation for Docker Compose installation steps.
-
Clone the repository to your local machine.
-
Navigate to the directory containing the
docker-compose.yml
file. -
Run the following command to build and start the services:
docker-compose up --build
This will start the backend, frontend, and database services as well as a Jaeger instance for tracing. The frontend will be accessible at http://localhost:3000, and the backend will be available at http://localhost:8080.
The database service is configured to use a named volume (db-data) to persist data. This means your database data will remain intact even if the container is stopped or removed.
Jaeger is included in the Docker Compose setup for tracing the application requests. It provides a web interface accessible at http://localhost:16686 to view traces.
If you need to customize the environment variables or any other settings, you can modify the docker-compose.yml file accordingly. For example, to change database credentials, update the POSTGRES_USER and POSTGRES_PASSWORD environment variables under the database service.
This documentation covers the following areas:
- Backend Documentation: Details the RESTful API provided by the backend service, including available endpoints and data models.
- Frontend Documentation: Describes the React-based frontend service, including its setup, features, and how to interact with the backend API.
- Overview
- Prerequisites
- Installation and Setup
- Running the Application
- User Interface Components
- Interaction with Backend API
- Error Handling and Notifications
These instructions will guide you through setting up the frontend on your local machine for development and testing purposes.
Before starting the frontend, ensure you have the following installed:
- Node.js (LTS version recommended)
- npm (Node Package Manager)
- Todo List API running on the backend (see Backend Documentation)
- Clone the frontend repository to your local machine.
- Navigate to the cloned directory.
- Install the necessary npm packages with:
npm install
Start the development server with:
npm start
The application will be served at http://localhost:3000 and will communicate with the Todo List API.
Renders the list of todo items and handles state management.
Displays individual todo items and provides options to edit or delete.
A form component that captures user input for new todo items.
Ensure the backend API is running and accessible. By default, the frontend will attempt to connect to the API at http://localhost:8080/api/todos.
The frontend application communicates errors from the API to the user via alerts or error messages displayed in the UI. It also handles exceptions in the user interface gracefully.
The Todo List API is a simple RESTful service that allows users to manage their todo items.
- Overview
- Prerequisites
- Installation and Setup
- Running the Application
- API Endpoints
- Data Models
- Error Handling and Responses
- Database Configuration and Management
- Observability and Tracing
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
Before running the service, you need to have the following installed:
- Java JDK 17 or higher
- Maven
- PostgreSQL database
- Clone the repository to your local machine.
- Set up your PostgreSQL database using the provided connection details.
- Run the following command to build the project:
mvn clean install
Start the application with:
java -jar target/todo-list-backend-0.0.1-SNAPSHOT.jar
The API will be available at http://localhost:8080/api.
GET /api/todos Retrieves a list of all todo items.
POST /api/todos/add Accepts a JSON object representing a todo item to be added.
GET /api/todos/search Query Parameters(only one required):
- title: Search by the title of the todo item.
- id: Search by the ID of the todo item.
PUT /api/todos/update/{id} Path Variable:
- id: The ID of the todo item to update.
Accepts a JSON object representing the updated fields of the todo item.
DELETE /api/todos/delete Query Parameters:
- title: Delete by the title of the todo item.
- id: Delete by the ID of the todo item.
- id (Integer): Unique identifier for the TodoItem (autogenerated)
- title (String): Title of the TodoItem.
- isChecked (boolean): Status of the TodoItem.
Ensure the application connects to your PostgreSQL database with the following settings:
spring.datasource.url=jdbc:postgresql://database:5432/todolist
spring.datasource.username=robert
spring.datasource.password=securepassword
The API uses HTTP status codes to indicate the success or failure of an API request. In the case of errors, a JSON object with error details is returned.
In a distributed system, it's crucial to have insights into the application's performance and to trace the flow of requests through various services. To achieve this, the application is integrated with Jaeger, an open-source tracing system.
Jaeger is a tracing system released by Uber, which provides monitoring and troubleshooting capabilities for microservice-based architectures. It allows developers to track request flows, measure performance, and monitor distributed transactions.
Our backend service is configured to send trace data to a Jaeger agent. This is achieved through the use of OpenTracing libraries, which are compatible with Jaeger.
To enable tracing with Jaeger, the following environment variables are set for the backend service in the docker-compose.yml
:
environment:
JAEGER_SERVICE_NAME: todo-list-backend
JAEGER_AGENT_HOST: jaeger
JAEGER_AGENT_PORT: 6831
These settings direct the backend service to send trace data to the Jaeger agent hosted within our Docker environment.
To view traces:
Navigate to http://localhost:16686 - this is the default port where the Jaeger UI is accessible. Select the service name from the drop-down list. Use the search functionality to filter specific traces.
The Jaeger UI provides a detailed view of the traces, showing the spans of each trace with timings, which can be used to identify performance bottlenecks or failures in the request flow.
In addition to tracing, logs and metrics can be observed through Jaeger's integration, providing a comprehensive overview of the system's health and performance.
When adding new services to the application, they can be instrumented using the OpenTracing API and configured to report to the same Jaeger instance, ensuring a unified view of the system's traces.