Help:Toolforge/Build Service/My first Buildpack Python tool

From Wikitech
Jump to navigation Jump to search

Python webservices are used by many existing tools. Python is a high-level, interpreted programming language with many available libraries for making webservices and integrating with MediaWiki.

This stub webservice is designed to get a sample Python application installed onto Toolforge using the new build service, as quickly as possible. The application is written using the Flask framework.

The guide will teach you how to:

Getting started

Prerequisites

Skills

Accounts

Step-by-step guide

Step 1: Create a new tool account

  1. Follow the Toolforge quickstart guide to create a Toolforge tool and SSH into Toolforge.
    • For the examples in this tutorial, sample-python-buildpack-app is used to indicate places where your unique tool name is used in another command.
  2. Make sure to create a git repository for the tool, you can get one like this:
    1. Log into the toolforge admin page
    2. Select your tool
    3. On the left side panel, under Git repositories click create repository
    4. Copy the url in the Clone section
      1. There's a private url, that we will use to clone it locally, starting with "git": git@gitlab.wikimedia.org:toolforge-repos/sample-python-buildpack-app.git
      2. And a public one, that we will use to build the app in toolforge, starting with "https": https://gitlab.wikimedia.org/toolforge-repos/sample-python-buildpack-app.git

Step 2: Create a basic Flask WSGI webservice for gunicorn

What is Flask?

Flask is a popular web development framework for Python.

What is gunicorn?

Gunicorn is a web server popular for running Python applications.

How to create a basic Flask WSGI webservice

Clone your tool git repository

You will have to clone the tool repository to be able to add code to it, on your local computer (with git installed) you can run:

laptop:~$ git clone git@gitlab.wikimedia.org:toolforge-repos/sample-python-buildpack-app.git
laptop:~$ cd sample-python-buildpack-app

That will create a folder called sample-python-buildpack-app. We are going to put the code in that folder.

Add the Flask and gunicorn dependencies
It is Python best practice to use a file named requirements.txt to keep track of the library dependencies of applications.
laptop:~sample-python-buildpack-app$ cat > requirements.txt << EOF
flask
gunicorn
EOF

NOTE: There's currently no other way to specify your dependencies, you can find some workaround in task T353762

Create a 'hello world' WSGI application
app.py
# -*- coding: utf-8 -*-
#
# This file is part of the Toolforge flask WSGI tutorial
#
# Copyright (C) 2017 Bryan Davis and contributors
#
# This program is free software: you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the Free
# Software Foundation, either version 3 of the License, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
# more details.
#
# You should have received a copy of the GNU General Public License along
# with this program.  If not, see <http://www.gnu.org/licenses/>.

import flask


app = flask.Flask(__name__)


@app.route('/')
def index():
  return 'Hello World!'
The 'Hello World!' file above starts with a license header that places it under the GPLv3+ license.

Code on Toolforge must always be licensed under an Open Source Initiative (OSI) approved license. See the Right to fork policy for more information on this Toolforge policy.

Create the Procfile

The Procfile is based on heroku's procfile, though we don't support all it's features, for now we only use the web entry point to get the command your server will be start with:

laptop:~sample-python-buildpack-app$ cat > Procfile << EOF
web: gunicorn --workers=4 --bind=0.0.0.0 app:app
EOF
Commit your changes and push
laptop:~sample-python-buildpack-app$ git add .
laptop:~sample-python-buildpack-app$ git commit -m "First commit"
laptop:~sample-python-buildpack-app$ git push origin main
EOF


Build the image

Now we have to ssh to login.toolforge.org and start the build for the image:

laptop:~sample-python-buildpack-app$ ssh login.toolforge.org  # or the equivalent with PuTTY
dcaro@tools-sgebastion-10$ become sample-python-buildpack-app
tools.sample-python-buildpack-app@tools-sgebastion-10$ toolforge build start https://gitlab.wikimedia.org/toolforge-repos/sample-python-buildpack-app.git
You have to pass the public url of the git repository (for gitlab, you can get it from), otherwise it will not be able to clone it.
Wait for the build to finish

You can check the status of the build like this:

tools.sample-python-buildpack-app@tools-sgebastion-10:~$ toolforge build show

You have to wait for the status to be ok(Succeeded).

Start the webservice
tools.sample-python-buildpack-app@tools-sgebastion-10$ toolforge webservice buildservice start --mount=none 
Starting webservice.

Once the webservice is started, navigate to https://sample-python-buildpack-app.toolforge.org in your web browser, and see a 'Hello World!' message. It might take a few minutes until it is reachable.

Notes

You can see the code used in this example here: https://gitlab.wikimedia.org/toolforge-repos/sample-python-buildpack-app

Troubleshooting

See Help:Toolforge/Build_Service#Troubleshooting.

See also

Communication and support

Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support
Stay aware of critical changes and plans
Track work tasks and report bugs

Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself

Read stories and WMCS blog posts

Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)