This guide assumes you have a Tool Labs account and some knowledge of getting around. The Help pages are a good place to get started.
The goal of this guide is to:
- Create a new tool, which
- Runs a Python web site using Flask, which
- Allows the user to log in using their Wikimedia SUL account.
Step 1: Creating a new tool
- Create a new tool. In this tutorial, I've used
<TOOL NAME>everywhere the tool name should be used.
- Log in to
tools-login.wmflabs.org. If you are already logged in, log out and log in again.
become <TOOL NAME>to change to the tool user.
Step 2: Install a basic Flask web app
Start by creating a virtual environment for the app:
# working directory is /data/project/<TOOL NAME>/ mkdir -p www/python cd www/python # wd is now ~/www/python virtualenv venv source venv/bin/activate
Then create a source directory, define dependencies and install those:
mkdir src cd src # wd is now ~/www/python/src cat > requirements.txt << EOF flask flask-mwoauth>=0.1.14 werkzeug>=0.9 EOF pip install -r requirements.txt
Finally, download the example app bundled with flask-mwoauth.
wget https://raw.githubusercontent.com/valhallasw/flask-mwoauth/master/demo.py -O app.py
Step 3: Set up OAuth
We will store secret tokens in app.py, so start by denying read access to
chmod 600 app.py
Then, register a new consumer, and enter the secret token and key you get in app.py.
- As callback URL, use:
- As contact e-mail address, use the e-mail address linked to your mediawiki.org account.
- Keep the default grant settings ('Request authorization for specific permissions.' with just 'Basic rights' selected)
Keep all other settings as they are
Don't worry about approval for now; you can use your own account before the consumer has been approved.
After submitting the form, you get two tokens.
- Fill in the consumer token as
- Fill in the secret token as
Finally, generate a secret key using
python -c "import os; print repr(os.urandom(24))"
and use that for the
app.secret_key in app.py.
Step 4: Configure the web server
cd .. # wd is now ~/www/python cat > uwsgi.ini << EOF [uwsgi] wsgi-file=app.py EOF webservice2 uwsgi-python start
and follow the status using
tail -f ~/uwsgi.log
where you should see something like:
thunder lock: disabled (you can enable it with --thunder-lock) uwsgi socket 0 bound to TCP address :46438 fd 3 Python version: 2.7.6 (default, Mar 22 2014, 23:03:41) [GCC 4.8.2] Set PythonHome to /data/project/<TOOL NAME>/www/python/venv *** Python threads support is disabled. You can enable it with --enable-threads *** Python main interpreter initialized at 0xe56820 your server socket listen backlog is limited to 100 connections your mercy for graceful operations on workers is 60 seconds mapped 363960 bytes (355 KB) for 4 cores *** Operational MODE: preforking *** WSGI app 0 (mountpoint='') ready in 4 seconds on interpreter 0xe56820 pid: 10851 (default app) mounting /data/project/<TOOL NAME>/www/python/src/app.py on /<TOOL NAME>
Step 5: Test!
https://tools.wmflabs.org/<TOOL NAME>/ with your browser. You should see something like this:
logged in as: None
login / logout
Click login. This should redirect you to mediawiki.org, with the following message:
In order to complete your request,
<TOOL NAME>needs permission to access information on all projects of this site on your behalf. No changes will be made with your account.
Click Allow. You are now redirected back to the main page, which should now show:
logged in as: u'
login / logout
Click logout. This shows:
Click back and refresh. The page shows
logged in as: None
Congratulations! Your basic flask-mwoauth is ready!
app.debug = True to
app.py and check
uwsgi.log for more information. Note that this needs
This can be caused e.g. by a copy-paste error of the consumer key and secret. You will get an HTTP/500 on
/login, and the stack trace in
uwsgi.log looks like this:
Traceback (most recent call last): File "/data/project/valhallasw-testing-tool/www/python/venv/local/lib/python2.7/site-packages/flask_oauth.py", line 331, in authorize token = self.generate_request_token(callback) File "/data/project/valhallasw-testing-tool/www/python/venv/local/lib/python2.7/site-packages/flask_oauth.py", line 304, in generate_request_token tup = (data['oauth_token'], data['oauth_token_secret']) KeyError: 'oauth_token'
Check your key and secret, or try re-registering.