fibasile/ticket-gateway

A flask gateway to manage git repository issues

Ticket Gateway

This project aims to create a single interface API for different issue trackers, including Gitlab, Github, Trello, etc

The initial goal is to abstract the issue tracker from i.e. Gitlab and make it available to other applications, wrapping the native interface and adding other features like issue templates.

On top of this the gateway can create useful automation, leveraging web-hooks and integrating with external systems.

Table of Contents

• Ticket Gateway
  • Dependencies
  • Getting Started
  • Commands
  • Database
  • Application Structure
  • Development
  • Testing
  • Lint
  • Swagger
    • Credits

Dependencies

You will need docker and docker-compose.

Getting Started

First, clone the project:

$ git clone https://gitlab.fabcloud.org/fibasile/ticket-gateway.git ticket-gateway
$ cd ticket-gateway

Then install dependencies and check that it works

$ make install      # Install the pip dependencies on the docker container
$ make start        # Run the container containing your local python server

If everything works, you should see the available routes here.

The API runs locally on docker containers.

Commands

While developing, you will probably rely mostly on make start; however, there are additional scripts at your disposal:

make <script>	Description
install	Install the pip dependencies on the server's container.
start	Run your local server in its own docker container.
daemon	Run your local server in its own docker container as a daemon.
db/connect	Connect to your docker database.
db/migrate	Generate a database migration file using alembic, based on your model files.
db/upgrade	Run the migrations until your database is up to date.
db/downgrade	Downgrade your database by one migration.
test	Run unit tests with pytest in its own container.
coverage	Run test coverage using pytest-cov.
lint	Run flake8 on the src and test directories.
safety	Run safety to check if your vendors have security issues.

Database

The database is in PostgreSql.

Locally, you can connect to your database using :

$ make db/connect

However, you will need before using this command to change the docker database container's name in package.json

This kit contains a built in database versioning using alembic. Once you've changed your models, which should reflect your database's state, you can generate the migration, then upgrade or downgrade your database as you want. See Commands for more information.

The migration will be generated by the container, it may possible that you can only edit it via sudo or by running chown on the generated file.

Application Structure

The application structure is the following:

.
├── devops                   # Project devops configuration settings
│   └── deploy               # Environment-specific configuration files for shipit
├── migrations               # Database's migrations settings
│   └── versions             # Database's migrations versions generated by alembic
├── src                      # Application source code
│   ├── models               # Python classes modeling the database
│   │   ├── abc.py           # Abstract base class model
│   │   └── user.py          # Definition of the user model
│   ├── repositories         # Python classes allowing you to interact with your models
│   │   └── user.py          # Methods to easily handle user models
│   ├── resources            # Python classes containing the HTTP verbs of your routes
│   │   └── user.py          # Rest verbs related to the user routes
│   ├── routes               # Routes definitions and links to their associated resources
│   │   ├── __init__.py      # Contains every blueprint of your API
│   │   └── user.py          # The blueprint related to the user
│   ├── swagger              # Resources documentation
│   │   └── user             # Documentation of the user resource
│   │       └── GET.yml      # Documentation of the GET method on the user resource
│   ├── util                 # Some helpfull, non-business Python functions for your project
│   │   └── parse_params.py  # Wrapper for the resources to easily handle parameters
│   ├── config.py            # Project configuration settings
│   ├── manage.py            # Project commands
│   └── server.py            # Server configuration
└── test                     # Unit tests source code

Development

To develop locally, here are your two options:

$ make start           # Create the containers containing your python server in your terminal
$ make daemon          # Create the containers containing your python server as a daemon

The containers will reload by themselves as your source code is changed. You can check the logs in the ./server.log file.

Testing

To add a unit test, simply create a test_*.py file anywhere in ./test/, prefix your test classes with Test and your testing methods with test_. Unittest will run them automaticaly. You can add objects in your database that will only be used in your tests, see example. You can run your tests in their own container with the command:

$ make test

Lint

To lint your code using flake8, just run in your terminal:

$ make lint

It will run the flake8 commands on your project in your server container, and display any lint error you may have in your code.

Swagger

Your API needs a description of it's routes and how to interact with them. You can easily do that with the swagger package included in the starter kit. Simply add a docstring to the resources of your API like in the user example. The API description will be available here. The Swagger UI will be available here.

Credits

This project is based on the Flask API Starter KIT.