Skip to content

Commit 092838c

Browse files
christoph2806christoph2806
committed
feat: v1.1.0 - Comprehensive update with modern dependencies and documentation
- Update API version to 1.1.0 - Upgrade all dependencies to latest versions: - Python 3.8 → 3.12 - FastAPI 0.68.0 → 0.115.6 - Pydantic 1.8.2 → 2.10.3 - Gotenberg 7 → 8 - Create comprehensive documentation structure: - /docs folder with installation and usage guides - Detailed API documentation with templating examples - Jekyll setup for GitHub Pages - Add GitHub Actions workflows: - Docker build and publish to GHCR - Jekyll documentation deployment - Update main README to be concise and modern - Preserve original author attribution (PapiHack) - Add security scanning and multi-arch Docker builds
1 parent 77504ac commit 092838c

File tree

13 files changed

+1009
-156
lines changed

13 files changed

+1009
-156
lines changed

‎.github/workflows/docker.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
name: Build and Publish Docker Image
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
tags: [ 'v*' ]
7+
pull_request:
8+
branches: [ main, master ]
9+
10+
env:
11+
REGISTRY: ghcr.io
12+
IMAGE_NAME: ${{ github.repository }}
13+
14+
jobs:
15+
build-and-push:
16+
runs-on: ubuntu-latest
17+
permissions:
18+
contents: read
19+
packages: write
20+
21+
steps:
22+
- name: Checkout repository
23+
uses: actions/checkout@v4
24+
25+
- name: Set up Docker Buildx
26+
uses: docker/setup-buildx-action@v3
27+
28+
- name: Log in to Container Registry
29+
if: github.event_name != 'pull_request'
30+
uses: docker/login-action@v3
31+
with:
32+
registry: ${{ env.REGISTRY }}
33+
username: ${{ github.actor }}
34+
password: ${{ secrets.GITHUB_TOKEN }}
35+
36+
- name: Extract metadata
37+
id: meta
38+
uses: docker/metadata-action@v5
39+
with:
40+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
41+
tags: |
42+
type=ref,event=branch
43+
type=ref,event=pr
44+
type=semver,pattern={{version}}
45+
type=semver,pattern={{major}}.{{minor}}
46+
type=semver,pattern={{major}}
47+
type=raw,value=latest,enable={{is_default_branch}}
48+
49+
- name: Build and push Docker image
50+
uses: docker/build-push-action@v5
51+
with:
52+
context: .
53+
platforms: linux/amd64,linux/arm64
54+
push: ${{ github.event_name != 'pull_request' }}
55+
tags: ${{ steps.meta.outputs.tags }}
56+
labels: ${{ steps.meta.outputs.labels }}
57+
cache-from: type=gha
58+
cache-to: type=gha,mode=max
59+
60+
- name: Run Trivy vulnerability scanner
61+
if: github.event_name != 'pull_request'
62+
uses: aquasecurity/trivy-action@master
63+
with:
64+
image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
65+
format: 'sarif'
66+
output: 'trivy-results.sarif'
67+
68+
- name: Upload Trivy scan results to GitHub Security tab
69+
if: github.event_name != 'pull_request'
70+
uses: github/codeql-action/upload-sarif@v3
71+
with:
72+
sarif_file: 'trivy-results.sarif'

‎.github/workflows/pages.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Build and Deploy GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
paths:
7+
- 'docs/**'
8+
- '_config.yml'
9+
- 'Gemfile*'
10+
- '.github/workflows/pages.yml'
11+
workflow_dispatch:
12+
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
concurrency:
19+
group: "pages"
20+
cancel-in-progress: false
21+
22+
jobs:
23+
build:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
29+
- name: Setup Ruby
30+
uses: ruby/setup-ruby@v1
31+
with:
32+
ruby-version: '3.1'
33+
bundler-cache: true
34+
cache-version: 0
35+
36+
- name: Setup Pages
37+
id: pages
38+
uses: actions/configure-pages@v4
39+
40+
- name: Build with Jekyll
41+
run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
42+
env:
43+
JEKYLL_ENV: production
44+
45+
- name: Upload artifact
46+
uses: actions/upload-pages-artifact@v3
47+
48+
deploy:
49+
environment:
50+
name: github-pages
51+
url: ${{ steps.deployment.outputs.page_url }}
52+
runs-on: ubuntu-latest
53+
needs: build
54+
steps:
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@v4

‎Dockerfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
FROM python:3.8.13-slim-buster
1+
FROM python:3.12-slim-bookworm
22

33
WORKDIR /code
44

‎Gemfile‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
source "https://rubygems.org"
2+
3+
gem "jekyll", "~> 4.3.0"
4+
gem "just-the-docs", "0.7.0"
5+
6+
group :jekyll_plugins do
7+
gem "jekyll-feed", "~> 0.12"
8+
gem "jekyll-sitemap"
9+
gem "jekyll-seo-tag"
10+
end
11+
12+
# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
13+
# and associated library.
14+
platforms :mingw, :x64_mingw, :mswin, :jruby do
15+
gem "tzinfo", ">= 1", "< 3"
16+
gem "tzinfo-data"
17+
end
18+
19+
# Performance-booster for watching directories on Windows
20+
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
21+
22+
# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
23+
# do not have a Java counterpart.
24+
gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

‎README.md‎

Lines changed: 46 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,67 @@
1-
# 🚀 Document Template Processing Service 🚀
1+
# 🚀 Document Template Processing Service
22

3-
[![python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white)
4-
![FastAPI](https://img.shields.io/badge/FastAPI-3776AB?style=for-the-badge&logo=fastapi&logoColor=white)
5-
[![docker](https://img.shields.io/badge/Docker-3776AB?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/r/papihack/document-template-processor)
6-
[![kubernetes](https://img.shields.io/badge/kubernetes-3776AB?style=for-the-badge&logo=kubernetes&logoColor=white)](https://github.com/PapiHack/document-templating-service/tree/master/k8s)
7-
![Issues](https://img.shields.io/github/issues/PapiHack/document-templating-service?style=for-the-badge&logo=appveyor)
8-
![PR](https://img.shields.io/github/issues-pr/PapiHack/document-templating-service?style=for-the-badge&logo=appveyor)
9-
[![MIT licensed](https://img.shields.io/badge/license-mit-blue?style=for-the-badge&logo=appveyor)](./LICENSE)
10-
[![Open Source Love](https://badges.frapsoft.com/os/v1/open-source-175x29.png?v=103)](https://github.com/ellerbrock/open-source-badges/)
3+
[![Python](https://img.shields.io/badge/Python-3.12-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
4+
[![FastAPI](https://img.shields.io/badge/FastAPI-1.1.0-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
5+
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com)
6+
[![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](./LICENSE)
7+
[![Documentation](https://img.shields.io/badge/Documentation-Available-green?style=for-the-badge)](./docs/)
118

12-
This is a simple and lightweight microservice that allow you to process your `Word` documents with a `templating system`, in order to hydrate it by injecting data or variables defined in it and get back its associated `PDF` result.
9+
A lightweight microservice for processing Word document templates with data injection and PDF conversion. Combines the power of [docxtpl](https://docxtpl.readthedocs.io/) templating with [Gotenberg](https://gotenberg.dev) PDF generation.
1310

14-
Feel free to checkout the [official docker image](https://hub.docker.com/r/papihack/document-template-processor) on my docker hub.
11+
## ✨ Features
1512

16-
## Notes
13+
- 📄 Process `.docx` templates with dynamic data
14+
- 🔄 Convert results to PDF automatically
15+
- 🚀 Fast REST API built with FastAPI
16+
- 🐳 Docker-ready with compose setup
17+
- ☸️ Kubernetes deployment manifests
18+
- 📚 Comprehensive documentation and examples
1719

18-
For transforming the `docx` result to `PDF` you'll need have an instance of [Gotenberg](https://gotenberg.dev) up and running and provide its `ROOT URL` as an environment variable to the microservice.
20+
## 🚀 Quick Start
1921

20-
## Installation
22+
```bash
23+
# Clone and start with Docker Compose
24+
git clone <repository-url>
25+
cd document-templating-service
26+
docker compose up -d
2127

22-
- First and foremost you'll need to have an instance of Gotenberg. You can easily have one by running the following docker command :
28+
# API will be available at http://localhost:8000/docs
29+
```
2330

24-
docker run --name gotenberg -d -p 3000:3000 gotenberg/gotenberg:7
31+
## 📖 Documentation
2532

33+
- **[📋 Installation Guide](docs/installation.md)** - Complete setup instructions
34+
- **[🔧 Usage Guide](docs/usage.md)** - API documentation and templating examples
35+
- **[📑 API Docs](http://localhost:8000/docs)** - Interactive API documentation (when running)
2636

27-
- After this step done, you have the two (2) options in order to run this service :
37+
## 🛠️ Technology Stack
2838

29-
- Direct run by following the steps below :
39+
- **Backend:** FastAPI 0.115.6, Python 3.12
40+
- **Templating:** docxtpl 0.19.0 (Jinja2-based)
41+
- **PDF Generation:** Gotenberg 8
42+
- **Deployment:** Docker, Kubernetes
3043

31-
- Rename the file `.env.example` at the root level of this project by simply `.env`
44+
## 📊 Updated Dependencies (v1.1.0)
3245

33-
- Set the value of the `GOTENBERG_API_URL` environment variable defined in it with yours (in our example => http://localhost:3000)
46+
This version includes major dependency updates:
47+
- Python 3.8 → 3.12
48+
- FastAPI 0.68.0 → 0.115.6
49+
- Pydantic 1.8.2 → 2.10.3
50+
- All dependencies updated to latest stable versions
3451

35-
- Install the necessary dependencies by running :
36-
37-
pip install -r requirements.txt (you can create virtual env if you want it)
52+
## 🤝 Contributing
3853

39-
- Start the microservice by running:
40-
41-
uvicorn main:app
54+
Feel free to open issues and pull requests. Please include a description with your PR.
4255

43-
- Visit the `API Documentation` at <http://localhost:8000/docs> or <http://localhost:8000/redoc>
56+
## 📜 License
4457

45-
- Using docker to build and launch a container :
58+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
4659

47-
- In your terminal, at the root of this project, build an image of this service by running :
48-
49-
docker build -t document-template-processing-service .
60+
## 👨‍💻 Original Author
5061

51-
- Start the service by creating a container with :
52-
53-
docker run -d -p 8000:8000 -e GOTENBERG_API_URL=your-host-ip:3000 --name dtps document-template-processing-service
62+
**[M.B.C.M (PapiHack)](https://github.com/PapiHack)**
63+
[![Twitter](https://img.shields.io/twitter/follow/the_it_dev?style=social)](https://twitter.com/the_it_dev)
5464

55-
- An official image is also available on my [docker hub](https://hub.docker.com/r/papihack/document-template-processor), so you can simply run
56-
the following command and skip the build step if you want too :
57-
58-
docker run -d -p 8000:8000 -e GOTENBERG_API_URL=your-host-ip:3000 --name dtps papihack/document-template-processor
65+
---
5966

60-
- Visit the `API Documentation` at <http://localhost:8000/docs> or <http://localhost:8000/redoc>
61-
62-
63-
## Up & Running with Docker Compose
64-
65-
If you are lazy like me 😄, you can setup the project by just running the following command :
66-
67-
docker-compose up -d
68-
69-
And stop all the service with :
70-
71-
docker-compose stop
72-
73-
Or stop and remove all the service with :
74-
75-
docker-compose down
76-
77-
78-
## Up & Running with Kubernetes
79-
80-
If you want to deploy this project on your kubernetes cluster, you can inspect and/or edit the manifest files available in the
81-
`k8s` directory before apply them.
82-
83-
Start by creating the namespace named `utils` by running :
84-
85-
kubectl apply -f k8s/namespace.yaml
86-
87-
Then, you can deploy the necessary components by running :
88-
89-
kubectl apply -f k8s/gotenberg -f k8s/document-template-processing
90-
91-
After that, feel free to create an `ingress` for `svc/document-template-processing` if you are using such kind of k8s component.
92-
93-
Otherwise, you can port forward the api service by running the following command before visiting <http://localhost:8000/docs> :
94-
95-
kubectl port-forward svc/document-template-processing 8000:8000 -n utils
96-
97-
98-
## Usage
99-
100-
For now, you have an endpoint named `/api/v1/process-template-document` that will allow you to make a `POST HTTP REQUEST` by sending two (2) required parameters :
101-
102-
- The `file` parameter that contains your `Word Document Template`
103-
104-
- The `data` parameter that is a `JSON object` with data or variable that we are going to inject in the `file` parameter
105-
106-
As a response, you'll get back its corresponding `PDF` file as a result.
107-
108-
### Example
109-
110-
<table>
111-
<tr>
112-
<th>Template Example</th>
113-
<th>Postman Test Result</th>
114-
</tr>
115-
<tr>
116-
<td><img src="./screenshots/invoice-template-doc-example.png"/></td>
117-
<td><img src="./screenshots/postman-test-screenshot.png"/></td>
118-
</tr>
119-
</table>
120-
121-
## 🚨 Cautions for Cloud Run 🚨
122-
123-
If you plan to run this on cloud, please change the `gotenberg` docker image with `gotenberg/gotenberg:7-cloudrun` or `thecodingmachine/gotenberg:7-cloudrun` in `docker-compose.yaml` file. This will allow you to save cost and so on.
124-
125-
For more infos, please look at [Gotenberg Docs](https://gotenberg.dev/docs/get-started/cloud-run).
126-
127-
128-
### Screenshots
129-
130-
![screenshot](./screenshots/swagger-doc.png)
131-
132-
## Contributing
133-
134-
Feel free to make a PR or report an issue 😃
135-
136-
Oh, one more thing, please do not forget to put a description when you make your PR 🙂
137-
138-
## Author
139-
140-
- [M.B.C.M](https://github.com/PapiHack)
141-
[![My Twitter Link](https://img.shields.io/twitter/follow/the_it_dev?style=social)](https://twitter.com/the_it_dev)
67+
> 💡 **Need help?** Check the [documentation](docs/) or open an issue!

0 commit comments

Comments
 (0)