From 00b4e6e33478ee3d334416e879c388f567519cbc Mon Sep 17 00:00:00 2001 From: Andres Contreras Date: Wed, 11 Feb 2026 09:59:09 +0100 Subject: [PATCH] docs: add professional README with unified template (#5) Standardize README.md with a consistent template including CI badge, features, installation, quick start, configuration, and documentation sections. Add paths-ignore to ci.yml to skip CI for docs-only changes. --- .github/workflows/ci.yml | 19 ++++-- README.md | 126 ++++++++++++++++++++++----------------- 2 files changed, 86 insertions(+), 59 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b9093b6..9567aee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,8 +2,22 @@ name: CI on: push: branches: [develop] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' pull_request: branches: [develop, main] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' workflow_dispatch: inputs: triggered-by: @@ -13,10 +27,5 @@ on: jobs: build: uses: fireflyframework/.github/.github/workflows/java-ci.yml@main - permissions: - packages: read - contents: read - actions: write with: java-version: '25' - secrets: inherit diff --git a/README.md b/README.md index 6f8ca49..d4a894a 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,95 @@ -# Firefly ECM Storage – AWS S3 +# Firefly Framework - ECM Storage - AWS S3 [![CI](https://github.com/fireflyframework/fireflyframework-ecm-storage-aws/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-ecm-storage-aws/actions/workflows/ci.yml) - [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) -[![Java](https://img.shields.io/badge/Java-21+-orange.svg)](https://openjdk.java.net/) -[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-brightgreen.svg)](https://spring.io/projects/spring-boot) +[![Java](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://openjdk.org) +[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot) + +> Amazon S3 storage adapter for Firefly ECM document content management. + +--- + +## Table of Contents + +- [Overview](#overview) +- [Features](#features) +- [Requirements](#requirements) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [Configuration](#configuration) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) + +## Overview -Amazon S3 storage adapter for Firefly lib‑ecm. Implements DocumentContentPort with streaming downloads, buffered/multipart uploads, checksums, size/existence, deletes, and pre‑signed upload URLs. +This module implements the Firefly ECM `DocumentContentPort` using Amazon S3 as the storage backend. It provides `S3DocumentContentAdapter` for storing, retrieving, and managing document content in S3 buckets with configurable bucket policies and access controls. + +The adapter auto-configures via `S3AdapterAutoConfiguration` with AWS SDK v2 and is activated by including this module on the classpath alongside the ECM core module. ## Features -- Streaming downloads via Flux -- Buffered uploads with optional multipart threshold -- Byte‑range reads; exists/size; delete by ID or path -- Optional SSE‑KMS (via kmsKeyId) and storage class selection -- Pre‑signed upload URL generation (PUT) -- Conditional auto‑wiring when `firefly.ecm.adapter-type=s3` + +- Amazon S3 integration for document content storage and retrieval +- Spring Boot auto-configuration for seamless activation +- Implements Firefly ECM DocumentContentPort +- Configurable via application properties +- Standalone provider library (include alongside fireflyframework-ecm) + +## Requirements + +- Java 21+ +- Spring Boot 3.x +- Maven 3.9+ +- Amazon S3 account and API credentials ## Installation + ```xml - org.fireflyframework - fireflyframework-ecm-storage-aws - ${firefly.version} + org.fireflyframework + fireflyframework-ecm-storage-aws + 26.01.01 ``` +## Quick Start + +The adapter is automatically activated when included on the classpath with the ECM core module: + +```xml + + + org.fireflyframework + fireflyframework-ecm + + + org.fireflyframework + fireflyframework-ecm-storage-aws + + +``` + ## Configuration + ```yaml firefly: ecm: - enabled: true - adapter-type: s3 - adapter: - s3: - bucket-name: ${S3_BUCKET_NAME} - region: ${AWS_REGION:us-east-1} - # auth (prefer IAM roles) - access-key: ${AWS_ACCESS_KEY_ID:} - secret-key: ${AWS_SECRET_ACCESS_KEY:} - # optional - endpoint: ${S3_ENDPOINT:} - path-prefix: ${S3_PATH_PREFIX:documents/} - enable-versioning: ${S3_ENABLE_VERSIONING:true} - path-style-access: ${S3_PATH_STYLE_ACCESS:false} - connection-timeout: 30s - socket-timeout: 30s - max-retries: 3 - enable-encryption: true - kms-key-id: ${S3_KMS_KEY_ID:} - storage-class: STANDARD - enable-multipart: true - multipart-threshold: 5242880 # 5MB - multipart-part-size: 5242880 # 5MB + storage: + aws-s3: + bucket: my-documents-bucket + region: us-east-1 ``` -## Usage -```java -@Autowired DocumentContentPort contentPort; -UUID id = UUID.randomUUID(); -// upload (buffers stream in memory before put) -Mono path = contentPort.storeContentStream(id, bodyFlux, "application/pdf", null); -// download streaming -Flux stream = contentPort.getContentStream(id); -// pre-signed PUT URL (direct-to-S3) -String url = ((S3DocumentContentAdapter) contentPort).generateUploadUrl(id, 15).block(); -``` +## Documentation + +No additional documentation available for this project. -Notes -- Upload method buffers the incoming stream before S3 PUT; for very large files consider using pre‑signed URLs or extending to true multipart streaming. -- Prefer IAM roles or environment credentials; avoid static keys in configuration. +## Contributing -## Testing -- Includes Spring Boot auto‑configuration test validating bean wiring and sample properties. +Contributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests. ## License -Apache 2.0 + +Copyright 2024-2026 Firefly Software Solutions Inc. + +Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.