https://github.com/dieperid/bucket-adapter
Bucket Adapter repository for BI1.
https://github.com/dieperid/bucket-adapter
docker java openapi swagger-ui
Last synced: 2 months ago
JSON representation
Bucket Adapter repository for BI1.
- Host: GitHub
- URL: https://github.com/dieperid/bucket-adapter
- Owner: dieperid
- Created: 2025-11-21T15:27:35.000Z (4 months ago)
- Default Branch: develop
- Last Pushed: 2026-01-02T19:20:12.000Z (3 months ago)
- Last Synced: 2026-01-02T20:18:49.404Z (3 months ago)
- Topics: docker, java, openapi, swagger-ui
- Language: Java
- Homepage: https://dieperid.github.io/bucket-adapter/
- Size: 129 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Bucket Adapter
## Description
Bucket Adapter API is a Spring Boot application designed to provide **a unified interface for cloud storage buckets** (AWS S3, and in the future GCP, Azure, and other providers).
The application exposes a REST API that allows clients to:
- upload files
- download files
- update existing files
- delete files (single or recursive)
- list bucket contents
- check if an object exists
- generate temporary shareable URLs
The architecture is based on the **Adapter + Factory pattern**, enabling easy integration of new cloud providers without impacting the business logic.
## Getting Started
### Documentation
1. Generate documentation with Doxygen
```bash
doxygen Doxyfile
```
The documentaion will be located in the `html` folder in `/docs`
2. View the documentation
```bash
# Start a PHP server
php -S localhost:8000 -t docs/html
```
Go on [http://localhost:8000](http://localhost:8000) and look at the amazing doc generated by Doxygen
### Kanban video
You can find the video explaining my Kanban here : https://youtu.be/Hqd9vmJnb0Q
### Prerequisites
The following tools and dependencies are required:
* **Language / Runtime**
* Java JDK 21 `openjdk 21.0.9 2025-10-21`
* OpenJDK Runtime Environment `(Red_Hat-21.0.9.0.10-1) (build 21.0.9+10)`
* JVM compatible with Java 21
* **Frameworks & Libraries**
* Spring Boot 4.0.0
* Spring Framework 7.0.1
* AWS SDK v2 (S3, Presigner)
* JUnit 5
* Mockito
* **Build & Dependency Management**
* Maven Wrapper (`./mvnw` or `mvn`)
* **IDE used**
* Visual Studio Code with [Java extension](https://marketplace.visualstudio.com/items?itemName=redhat.java)
* **Supported OS (tested)**
* Linux (`Fedora Linux 42 (Workstation Edition)`)
* **Cloud Providers**
* AWS S3 (currently implemented)
* Google Cloud Storage (planned)
* Azure Blob Storage (planned)
* **Virtualization**
* Docker version 29.1.3, build f52814d
---
### Configuration
#### Environment variables / system properties
The application relies on external configuration to select the storage provider and access the bucket.
1. Copy the `.env.example` file to a `.env` file using this command : `cp .env.example .env`.
2. Configure **Spring Configuration** variables in `.env` file :
```bash
# Spring Configuration
SPRING_APPLICATION_NAME=yourappname
SERVER_PORT=8080
```
#### AWS configuration
Required variables:
```bash
AWS_REGION=your-region
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
```
Provider selection:
```bash
PROVIDER_IMPL=AWS
```
#### GCP configuration
Required variables :
```bash
GCP_PROJECT_ID=your-project-id
GOOGLE_APPLICATION_CREDENTIALS=./path-to-credentials.json
```
> Note : You'll have to put the path of your `credentials.json` file in the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
Provider selection:
```bash
PROVIDER_IMPL=GCP
```
#### Azure configuration
...
## Deployment
### On dev environment
#### Build the project
```bash
mvn clean install
```
#### Run tests
**Generate "data" folder for testing**
1. Make the script executable :
```bash
chmod +x setup-test-data.sh
```
2. Execute the script to create the **data** folder with sample files for testing :
```bash
./setup-test-data.sh
```
3. Run tests
```bash
nvn test
```
4. Check for coverage
```bash
# Generate coverage report
mvn jacoco:report
# Show coverage report
php -S localhost:8000 -t target/site/jacoco
```
#### Run the application
```bash
mvn spring-boot:run
```
### On integration environment
#### Maven build
```bash
# Make sure Maven wrapper is executable
chmod +x mvnw
# Clean and compile, skip tests
mvn clean package -DskipTests
# (Optional) Run tests
mvn test
```
#### Docker build & run
```bash
# Build Docker image
docker compose up --build
```
### How to use the application ?
#### API
1. To use the API you can read this [documentation](docs/api-documentation.md).
2. You can also find the [online documentation](https://dieperid.github.io/bucket-adapter/) using Redoc to publish the API documentation.
**How to update the API documentation ?**
To update the documentation, first you'll have to start run the project using **maven** or **docker** :
```bash
# Maven
mvn spring-boot:run
# Docker
docker compose up --build
```
When your app is running, you'll be able generate the API documentaion in `json` format or `yaml` format.
> Note : Redoc use the `yaml` format to display the API documentation in web interface
To generate run one if these command :
```bash
# JSON format
curl http://localhost:8080/v3/api-docs > docs/openapi.json
# YAML format
curl http://localhost:8080/v3/api-docs > docs/openapi.yaml
```
## Directory structure
```bash
.
├── docker-compose.yml
├── Dockerfile
├── .env.example
├── .gcp-credentials.example.json
├── checkstyle.xml
├── Doxyfile
├── mvnw
├── mvnw.cmd
├── pom.xml
├── README.md
├── setup-test-data.sh
├── docs # Documentation folder
└── src # Source code
├── main
│ ├── java
│ │ └── com
│ │ └── example
│ │ └── bucketadapter
│ │ ├── adapter
│ │ │ ├── BucketAdapter.java
│ │ │ └── impl # Adapter implementation
│ │ ├── BucketAdapterApplication.java
│ │ ├── config
│ │ ├── controller
│ │ ├── exception # Bucket exception
│ │ ├── factory
│ │ ├── helper # Helpers
│ │ └── service
│ └── resources
│ ├── application.properties
│ ├── static
│ └── templates
└── test # Tests folder
└── java
└── com
└── example
└── bucketadapter
├── adapter
│ └── impl
└── BucketAdapterApplicationTests.java
```
## Collaborate
### Proposing a new feature
- Create an **issue** describing the feature or bug
- Submit a **Pull Request** linked to the issue
### Commit convention
This project follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
Examples :
```bash
feat: add GCP bucket adapter
fix: handle S3 presigner exception
test: add unit tests for recursive delete
```
### Git branch workflow
This projects use the [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)
Examples :
```bash
feature/implement-aws-s3
release/1.0.0
hotfix/fix-servor-error-on-s3-upload
```
## License
[MIT License](LICENSE)
## Contact
For questions or contributions:
- GitHub Issues
- Pull Request discussions
For personal interactions:
- Dieperink David
- contact@daviddieperink.ch