https://github.com/geoadmin/template-service-flask
Basic template for almost all Flask services developed by the geoadmin team.
https://github.com/geoadmin/template-service-flask
managed-by-tf
Last synced: about 1 month ago
JSON representation
Basic template for almost all Flask services developed by the geoadmin team.
- Host: GitHub
- URL: https://github.com/geoadmin/template-service-flask
- Owner: geoadmin
- License: bsd-3-clause
- Created: 2020-07-07T14:34:14.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-10-25T19:35:20.000Z (over 2 years ago)
- Last Synced: 2025-01-11T08:08:32.143Z (over 1 year ago)
- Topics: managed-by-tf
- Language: Python
- Homepage:
- Size: 218 KB
- Stars: 1
- Watchers: 17
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# service-name
| Branch | Status |
|--------|-----------|
| develop | ![Build Status]() |
| master | ![Build Status]() |
## Table of content
- [Table of content](#table-of-content)
- [Description](#description)
- [Versioning](#versioning)
- [Local Development](#local-development)
- [Make Dependencies](#make-dependencies)
- [Setting up to work](#setting-up-to-work)
- [Linting and formatting your work](#linting-and-formatting-your-work)
- [Test your work](#test-your-work)
- [Updating Packages](#updating-packages)
- [Docker](#docker)
- [Deployment](#deployment)
- [Deployment configuration](#deployment-configuration)
## Description
A simple description of the service should go here
A detailed descriptions of the endpoints can be found in the [OpenAPI Spec](openapi.yaml).
## Versioning
This service uses [SemVer](https://semver.org/) as versioning scheme. The versioning is automatically handled by `.github/workflows/main.yml` file.
See also [Git Flow - Versioning](https://github.com/geoadmin/doc-guidelines/blob/master/GIT_FLOW.md#versioning) for more information on the versioning guidelines.
## Local Development
### Make Dependencies
The **Make** targets assume you have **python3.13**, **pipenv**, **bash**, **curl**, **tar**, **docker** and **docker-compose** installed.
### Setting up to work
First, you'll need to clone the repo
```bash
git clone git@github.com:geoadmin/service-name
```
Then, you can run the setup target to ensure you have everything needed to develop, test and serve locally
```bash
make setup
```
That's it, you're ready to work.
### Linting and formatting your work
In order to have a consistent code style the code should be formatted using `yapf`. Also to avoid syntax errors and non
pythonic idioms code, the project uses the `pylint` linter. Both formatting and linter can be manually run using the
following command:
```bash
make format-lint
```
**Formatting and linting should be at best integrated inside the IDE, for this look at
[Integrate yapf and pylint into IDE](https://github.com/geoadmin/doc-guidelines/blob/master/PYTHON.md#yapf-and-pylint-ide-integration)**
### Test your work
Testing if what you developed work is made simple. You have four targets at your disposal. **test, serve, gunicornserve, dockerrun**
```bash
make test
```
This command run the integration and unit tests.
```bash
make serve
```
This will serve the application through Flask without any wsgi in front.
```bash
make gunicornserve
```
This will serve the application with the Gunicorn layer in front of the application
```bash
make dockerrun
```
This will serve the application with the wsgi server, inside a container.
### Updating Packages
All packages used in production are pinned to a major version. Automatically updating these packages
will use the latest minor (or patch) version available. Packages used for development, on the other
hand, are not pinned unless they need to be used with a specific version of a production package
(for example, boto3-stubs for boto3).
To update the packages to the latest minor/compatible versions, run:
```bash
pipenv update --dev
```
To see what major/incompatible releases would be available, run:
```bash
pipenv update --dev --outdated
```
To update packages to a new major release, run:
```bash
pipenv install logging-utilities~=5.0
```
## Docker
The service is encapsulated in a Docker image. Images are pushed on the `swisstopo-bgdi-builder` account of [AWS ECR](https://eu-central-1.console.aws.amazon.com/ecr/repositories?region=eu-central-1) registry. From each github PR that is merged into develop branch, one Docker image is built and pushed with the following tags:
- `develop.latest`
- `CURRENT_VERSION-beta.INCREMENTAL_NUMBER`
From each github PR that is merged into master, one Docker image is built an pushed with the following tag:
- `VERSION`
Each image contains the following metadata:
- author
- git.branch
- git.hash
- git.dirty
- version
These metadata can be seen directly on the dockerhub registry in the image layers or can be read with the following command
```bash
# NOTE: jq is only used for pretty printing the json output,
# you can install it with `apt install jq` or simply enter the command without it
docker image inspect --format='{{json .Config.Labels}}' 974517877189.dkr.ecr.eu-central-1.amazonaws.com/service-name:develop.latest | jq
```
You can also check these metadata on a running container as follows
```bash
docker ps --format="table {{.ID}}\t{{.Image}}\t{{.Labels}}"
```
## Deployment
### Deployment configuration
The service is configured by Environment Variable:
| Env | Default | Description |
| ----------- | --------------------- | -------------------------- |
| LOGGING_CFG | logging-cfg-local.yml | Logging configuration file |
| FORWARED_ALLOW_IPS | `*` | Sets the gunicorn `forwarded_allow_ips` (see https://docs.gunicorn.org/en/stable/settings.html#forwarded-allow-ips). This is required in order to `secure_scheme_headers` to works. |
| FORWARDED_PROTO_HEADER_NAME | `X-Forwarded-Proto` | Sets gunicorn `secure_scheme_headers` parameter to `{FORWARDED_PROTO_HEADER_NAME: 'https'}`, see https://docs.gunicorn.org/en/stable/settings.html#secure-scheme-headers. |
| SCRIPT_NAME | `''` | If the service is behind a reverse proxy and not served at the root, the route prefix must be set in `SCRIPT_NAME`. |
| WSGI_WORKERS | `2` | WSGI service number of workers. 0 or negative value means that the number of worker are computed from the number of cpu. |
| WSGI_TIMEOUT | `30`| WSGI timeout. |
| GUNICORN_KEEPALIVE | `2` | The [`keepalive`](https://docs.gunicorn.org/en/stable/settings.html#keepalive) setting passed to gunicorn. |