Skip to content

Commit 983b87a

Browse files
jagalindojagalindo
committed
fix: improving docker image creation to tag properly
1 parent 3a081b1 commit 983b87a

2 files changed

Lines changed: 142 additions & 51 deletions

File tree

‎.github/workflows/docker-image.yml‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
name: Docker Image CI
22

3+
# Tag-driven release, mirroring the .dev tag schema of the flamapy packages.
4+
# v1.2.3 -> docker :latest + :v1.2.3
5+
# v1.2.3.dev0 -> docker :dev + :v1.2.3.dev0 (preview only)
36
on:
47
push:
58
tags:
@@ -86,11 +89,25 @@ jobs:
8689
username: ${{ secrets.DOCKERHUB_USERNAME }}
8790
password: ${{ secrets.DOCKERHUB_API_TOKEN }}
8891

92+
# .dev tags move the floating ":dev" tag; real releases move ":latest".
93+
- name: Compute moving tag
94+
id: meta
95+
run: |
96+
if [[ "${GITHUB_REF_NAME}" == *dev* ]]; then
97+
echo "moving=dev" >> "$GITHUB_OUTPUT"
98+
else
99+
echo "moving=latest" >> "$GITHUB_OUTPUT"
100+
fi
101+
89102
- name: Create and push the manifest list
90103
working-directory: /tmp/digests
91104
run: |
92-
docker buildx imagetools create -t "${IMAGE}:${GITHUB_REF_NAME}" \
105+
docker buildx imagetools create \
106+
-t "${IMAGE}:${GITHUB_REF_NAME}" \
107+
-t "${IMAGE}:${MOVING}" \
93108
$(printf "${IMAGE}@sha256:%s " *)
109+
env:
110+
MOVING: ${{ steps.meta.outputs.moving }}
94111

95112
- name: Inspect the published image
96113
run: docker buildx imagetools inspect "${IMAGE}:${GITHUB_REF_NAME}"

‎README.md‎

Lines changed: 124 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,169 @@
11
<div align="center">
22

3-
<a href="">[![Pytest Testing Suite](https://github.com/flamapy/flamapy-rest/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/flamapy/flamapy-rest/actions/workflows/tests.yml)</a>
4-
<a href="">[![Commits Syntax Checker](https://github.com/flamapy/flamapy-rest/actions/workflows/commits.yml/badge.svg?branch=main)](https://github.com/flamapy/flamapy-rest/actions/workflows/commits.yml)</a>
5-
<a href="">![PyPI](https://img.shields.io/pypi/v/flamapy-rest?label=pypi%20package)
6-
<a href="">![PyPI - Downloads](https://img.shields.io/pypi/dm/flamapy-rest)
3+
<a href="https://github.com/flamapy/flamapy-rest/actions/workflows/main.yml">![Python analysis](https://github.com/flamapy/flamapy-rest/actions/workflows/main.yml/badge.svg?branch=main)</a>
4+
<a href="https://github.com/flamapy/flamapy-rest/actions/workflows/conventionalpr.yml">![Conventional Commits](https://github.com/flamapy/flamapy-rest/actions/workflows/conventionalpr.yml/badge.svg?branch=main)</a>
5+
<a href="https://github.com/flamapy/flamapy-rest/actions/workflows/docker-image.yml">![Docker Image CI](https://github.com/flamapy/flamapy-rest/actions/workflows/docker-image.yml/badge.svg)</a>
6+
<a href="https://pypi.org/project/flamapy-rest/">![PyPI](https://img.shields.io/pypi/v/flamapy-rest?label=pypi%20package)</a>
7+
<a href="https://hub.docker.com/r/flamapy/flamapy-rest">![Docker Pulls](https://img.shields.io/docker/pulls/flamapy/flamapy-rest)</a>
8+
<a href="https://pypi.org/project/flamapy-rest/">![PyPI - Downloads](https://img.shields.io/pypi/dm/flamapy-rest)</a>
79
</div>
810

9-
#
10-
1111
<div id="top"></div>
1212
<br />
1313
<div align="center">
1414

15-
<h3 align="center">FLAMAPY rest API</h3>
15+
<h3 align="center">FLAMAPY REST API</h3>
1616

1717
<p align="center">
1818
A new and easy way to use FLAMA
1919
<br />
20-
<a href="https://github.com/flamapy/flamapy-fm-dist/issues">Report Bug</a>
20+
<a href="https://github.com/flamapy/flamapy-rest/issues">Report Bug</a>
2121
·
22-
<a href="https://github.com/flamapy/flamapy-fm-dist/issues">Request Feature</a>
22+
<a href="https://github.com/flamapy/flamapy-rest/issues">Request Feature</a>
2323
</p>
2424
</div>
25-
<!-- ABOUT THE PROJECT -->
2625

26+
<!-- ABOUT THE PROJECT -->
2727
## About The Project
2828

29-
FLAMAPY Feature model distribution provides an easier way of using FLAMA when analysing feature models. It packs the most used plugins for analyis of feature models adding a layer of convenience to use the framework or integrate it.
29+
`flamapy-rest` is a [Flask](https://flask.palletsprojects.com/) REST API that wraps the
30+
[FLAMAPY](https://flamapy.github.io/) framework for **feature model analysis**. It dynamically
31+
exposes FLAMAPY operations (dead features, false-optional features, configurations, satisfiability,
32+
diagnosis, …) as HTTP endpoints, with self-generated [Swagger](https://swagger.io/) documentation.
33+
34+
Feature model analysis has a crucial role in software product line engineering, enabling us to
35+
understand, design, and validate the complex relationships among features in a software product
36+
line. These models can be complex and challenging to analyze due to their variability, making it
37+
difficult to identify conflicts, dead features, and potential optimizations. This REST API makes
38+
that analysis available to any tool or language that can speak HTTP.
39+
40+
Please note: this is a living document and we will continue to update and improve it as we release
41+
new versions of the plugins and receive feedback from our users. If there's anything you don't
42+
understand or if you have any suggestions for improvement, don't hesitate to
43+
[open an issue](https://github.com/flamapy/flamapy-rest/issues). We're here to help!
44+
45+
### Built With
46+
47+
* [Docker](https://www.docker.com/)
48+
* [Flask](https://flask.palletsprojects.com/)
49+
* [FLAMAPY](https://github.com/flamapy)
50+
* [Flasgger](https://github.com/flasgger/flasgger)
3051

31-
Feature Model Analysis has a crucial role in software product line engineering, enabling us to understand, design, and validate the complex relationships among features in a software product line. These feature models can often be complex and challenging to analyze due to their variability, making it difficult to identify conflicts, dead features, and potential optimizations. This is where this distribution comes in.
52+
<p align="right">(<a href="#top">back to top</a>)</p>
3253

33-
Please note: This is a living document and we will continue to update and improve it as we release new versions of the plugins and receive feedback from our users. If there's anything you don't understand or if you have any suggestions for improvement, don't hesitate to contact us. We're here to help!
54+
<!-- GETTING STARTED -->
55+
## Getting Started
3456

35-
Three main interfaces are provided:
36-
* A REST API: The REST API allows for easy integration with other tools and applications. It is also a more user friendly interface for those who are not familiar with the command line.
57+
There are three supported ways to run the API. **Using the published Docker image is the easiest** —
58+
nothing to build, and it already bundles FLAMAPY and all of its analysis plugins.
59+
60+
### Option 1 — Run the published Docker image (recommended)
61+
62+
The CI publishes a multi-arch image (`linux/amd64` and `linux/arm64`) to Docker Hub at
63+
[`flamapy/flamapy-rest`](https://hub.docker.com/r/flamapy/flamapy-rest) on every version tag.
3764

38-
Whant it to runint, simply run
3965
```bash
40-
pip install flamapy-rest
41-
gunicorn --bind 0.0.0.0:8000 app:app
66+
# Pull and run the latest release
67+
docker run --rm -p 8000:8000 flamapy/flamapy-rest
68+
```
69+
70+
Then open:
71+
72+
* API home: <http://localhost:8000/>
73+
* Swagger UI / API docs: <http://localhost:8000/docs/>
74+
75+
To pin a specific version, use its tag (matching a release, e.g. `v2.6.0`):
76+
77+
```bash
78+
docker run --rm -p 8000:8000 flamapy/flamapy-rest:v2.6.0
79+
```
80+
81+
Run it detached and give the container a name so it's easy to stop later:
82+
83+
```bash
84+
docker run -d --name flamapy-rest -p 8000:8000 flamapy/flamapy-rest
85+
docker logs -f flamapy-rest # follow the logs
86+
docker stop flamapy-rest # stop it
87+
docker rm flamapy-rest # remove it
4288
```
4389

44-
Alternatively, you can use docker in this way:
90+
### Option 2 — Build the Docker image from source
91+
92+
If you want to run your local changes, clone the repo and build the image yourself. A helper script
93+
is provided that builds, runs, and (on exit) cleans up the container and image:
94+
4595
```bash
46-
chmod +x start-server.sh
96+
# Linux / macOS
4797
./start-server.sh
98+
99+
# Windows
100+
start-server.cmd
48101
```
49-
Or go to [the render deployed version]() it isn't fast, but its free.
50102

51-
<p align="right">(<a href="#top">back to top</a>)</p>
103+
Or do it by hand:
52104

53-
### Built With
105+
```bash
106+
docker build --tag flamapy-rest .
107+
docker run --rm -p 8000:8000 flamapy-rest
108+
```
54109

55-
* [Docker](https://www.docker.com/)
56-
* [Flask](https://flask.palletsprojects.com/en/2.2.x/)
57-
* [FLAMAPY](https://github.com/flamapy)
58-
* [Flasgger](https://github.com/flasgger/flasgger)
110+
### Option 3 — Install from PyPI and run locally
111+
112+
The API is also published on PyPI as [`flamapy-rest`](https://pypi.org/project/flamapy-rest/)
113+
(requires **Python 3.11+**). Because the WSGI entrypoint lives in `app.py`, clone the repo to get it:
114+
115+
```bash
116+
git clone https://github.com/flamapy/flamapy-rest.git
117+
cd flamapy-rest
118+
pip install .
119+
120+
# Production server
121+
gunicorn --bind 0.0.0.0:8000 app:app
122+
123+
# …or the Flask development server
124+
python -m flask run --host=0.0.0.0
125+
```
59126

60127
<p align="right">(<a href="#top">back to top</a>)</p>
61128

62-
# Using the distribution REST API
63-
The easies way is to execute the following command: docker run -p 8000:8000 flamapy/flamapy-fm-dist and open localhost:8000
64-
<!-- GETTING STARTED -->
65-
## Getting Started
129+
## Usage
66130

67-
To get a local copy up and running follow these simple example steps.
131+
Every public operation of FLAMAPY's `FLAMAFeatureModel` facade is exposed as a `POST` endpoint under
132+
`/api/v1/operations/<operation_name>`. Each call uploads a feature model file (e.g. UVL) as
133+
multipart form data; some operations also accept an optional `feature` or `configuration` parameter.
68134

69-
First, you will need to install [Docker](https://docs.docker.com/desktop/).
135+
```bash
136+
# Example: count the number of valid configurations of a model
137+
curl -X POST http://localhost:8000/api/v1/operations/configurations_number \
138+
-F "model=@resources/models/simple/valid_model.uvl"
139+
```
70140

71-
### Instalation
141+
The full, interactive list of endpoints — with parameters and "try it out" support — is available
142+
in the Swagger UI at <http://localhost:8000/docs/>.
72143

73-
1. Clone the repository
144+
<p align="right">(<a href="#top">back to top</a>)</p>
145+
146+
## API Documentation
74147

75-
2. If you are running Windows, run
76-
```sh
77-
$ cd flamapy-dm-dist
78-
$ ./start-server.cmd
79-
```
80-
81-
3. If you are running Linux or MacOS, run
82-
```sh
83-
$ cd flamapy-dm-dist
84-
$ ./start-server.sh
85-
```
86-
87-
This script will build, install and deploy the API in http://localhost:8000, you can access all the endpoints through an application like [Postman](https://www.postman.com/)
148+
All documentation is registered with Swagger UI and OAS 3.0, served at
149+
[`/docs/`](http://localhost:8000/docs/). It is generated dynamically by
150+
[Flasgger](https://github.com/flasgger/flasgger) from the route docstrings and method signatures, so
151+
**don't forget to document your code in the route files** — new operations show up automatically.
88152

89153
<p align="right">(<a href="#top">back to top</a>)</p>
90154

91-
### API Documentation
155+
## Contributing
156+
157+
Contributions are welcome. This repo enforces
158+
[Conventional Commits](https://www.conventionalcommits.org/) on pull request titles, and runs Ruff,
159+
mypy, and pytest in CI.
92160

93-
All the documentation is registered with Swagger UI and OAS 3.0. It is accesible through /api/v1/docs. This documentation is generated dinamically by relyin gon flasgger. DO not forget to document your code in the route files!
161+
```bash
162+
pip install .[dev] # install dev tooling
163+
164+
ruff check . # lint
165+
mypy -p flamapy # static type checking
166+
pytest # tests
167+
```
94168

95169
<p align="right">(<a href="#top">back to top</a>)</p>

0 commit comments

Comments
 (0)