service-name

Branch	Status
develop
master

Table of content

• Table of content
• Description
• Versioning
• Local Development
  • Make Dependencies
  • Setting up to work
  • Linting and formatting your work
  • Test your work
  • Updating Packages
• Docker
• Deployment
  • 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.

Versioning

This service uses SemVer as versioning scheme. The versioning is automatically handled by .github/workflows/main.yml file.

See also Git Flow - 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

git clone [email protected]:geoadmin/service-name

Then, you can run the setup target to ensure you have everything needed to develop, test and serve locally

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:

make format-lint

Formatting and linting should be at best integrated inside the IDE, for this look at Integrate yapf and pylint into IDE

Test your work

Testing if what you developed work is made simple. You have four targets at your disposal. test, serve, gunicornserve, dockerrun

make test

This command run the integration and unit tests.

make serve

This will serve the application through Flask without any wsgi in front.

make gunicornserve

This will serve the application with the Gunicorn layer in front of the application

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:

pipenv update --dev

To see what major/incompatible releases would be available, run:

pipenv update --dev --outdated

To update packages to a new major release, run:

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 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

# 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

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 setting passed to gunicorn.