Branch	Status
develop
master

• Table of content
• Description
• Dependencies
• Service API
• Versioning
• Local Development
  • Make Dependencies
  • Setting up to work
  • Linting and formatting your work
  • Test your work
• Docker
• Maintenance
  • Convert Symbols from svg to png
• Deployment
  • Deployment configuration

A simple REST microservice meant to take a symbol (defined by a filename), to colorized it with a color defined by r, g and b values and to return the colorized symbol.

This service doesn't have any external dependencies

The service has the following endpoints:

• GET /checker
• GET /sets
• GET /sets/<icon_set_name>
• GET /sets/<icon_set_name>/icons
• GET /sets/<icon_set_name>/icons/<icon_name>
• GET /sets/<icon_set_name>/icons/<icon_name>.png
• GET /sets/<icon_set_name>/icons/<icon_name>-<red>,<green>,<blue>.png
• GET /sets/<icon_set_name>/icons/<icon_name>@<scale>.png
• GET /sets/<icon_set_name>/icons/<icon_name>@<scale>-<red>,<green>,<blue>.png

A detailed descriptions of the endpoints can be found in the OpenAPI Spec repository.

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.

The Make targets assume you have python3.12, pipenv, bash, curl, tar, docker and docker-compose installed.

First, you'll need to clone the repo

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

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

make dev

That's it, you're ready to 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

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.

Here below are simple examples of how to test the service after serving on localhost:5000:

curl -H "Origin: www.example.com" http://localhost:5000/sets/default/icons
curl -H "Origin: www.example.com" http://localhost:5000/sets/default/icons/001-marker@2x-255,133,133.png --output out.png

NOTE: if you serve using gunicorn or docker, you need to add the route prefix /api/icons

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 and 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}}"

Sometimes it may happen, that we get a new set of icons. In general these icons have to be quadratic in a resolution of 48px x 48px in the format .png. Neverthanless there is a script to convert .svg images towards .png images. This script is located in the folder scripts/svg2png.py. There is a help provided

pipenv run python scripts/svg2png.py --help

Here is an example of such a convertion

pipenv run python scripts/svg2png.py --help
```pipenv run python scripts/svg2png.py -I ./tmp/new-icons -O ./static/images/babs2 -W 48 -H 48

The service is configured by Environment Variable: