Skip to content
Source code of the recurrent donations platform Liberapay
Branch: master
Clone or download
Latest commit ee8a720 May 19, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.ebextensions add workaround for glibc bug Jan 27, 2019
cli prune `__future__` imports and encoding comments Jan 29, 2019
docker Update tests.yml for postgresql 9.4 to 9.6 May 15, 2018
emails modify the default behavior of `to_age` Mar 1, 2019
i18n merge translations May 19, 2019
js always collect the payer's name for Stripe Feb 15, 2019
liberapay fix rounding of standard tips and donation limits May 19, 2019
sql failing test for #1503 May 18, 2019
style create a page about Liberapay's logo (#1427) May 6, 2019
templates reword donation form to disambiguate currencies May 7, 2019
tests add a test for donation limits May 19, 2019
www prune link to FAQ item about Mangopay's fees May 14, 2019
.babel_extract create a `liberapay.i18n` submodule Nov 27, 2018
.editorconfig rename, clean up, adapt, internationalize May 26, 2015
.flake8 fix or ignore flake8 warnings Jan 19, 2019
.gitattributes also send `environment` and `release` to Sentry Jan 15, 2018
.gitignore commit the new test fixture Mar 4, 2018
.lfsconfig adapt LFS config for gitlab (#1388) Jan 17, 2019
.travis.yml improve compatibility with macOS and Python 3.7 (#1467) Mar 25, 2019
Dockerfile Update Debian version from Dockerfile Aug 16, 2018
Makefile improve compatibility with macOS and Python 3.7 (#1467) Mar 25, 2019
_i18n_warning.html add a warning at the top of partially translated pages Jan 10, 2018 modify gunicorn logs to include Host header Feb 22, 2016 Refactor Shell Scripts based on ShellCheck's suggestion (#828) Dec 30, 2017
defaults.env implement encrypted storage of identity information Jan 22, 2019
docker-compose.yml Update Docker PostgreSQL version to match requirements. Apr 25, 2018
error.spt add a blank line between two paragraphs in `error.spt` Apr 3, 2019
pytest.ini rename, clean up, adapt, internationalize May 26, 2015 improve handling of DB changes in `` Feb 6, 2019
requirements-prod.txt don't install prod requirements locally Feb 7, 2017
requirements_base.txt upgrade urllib3 from 1.24.1 to 1.25.1 (#1487) Apr 27, 2019
requirements_dev.txt fix requirements Jan 25, 2019
requirements_tests.txt improve compatibility with macOS and Python 3.7 (#1467) Mar 25, 2019
tox.ini drop support for python 2.7 Jan 29, 2019


Build Status Weblate Gitter Income Donate

Liberapay is a recurrent donations platform. We help you fund the creators and projects you appreciate.

Note: This webapp is not self-hostable.

Table of Contents


You want to chat? Join us on Gitter. (If you use IRC, Gitter has a gateway, and we're also in the #liberapay channel on Freenode.)

Alternatively you can post a message in our GitHub salon.

Contributing to the translations

You can help translate Liberapay via Weblate. Current status:

global translation status

translation status by language

If you have questions about translating Liberapay, you can ask them in the salon.

Contributing to the code


Liberapay was originally forked from Gratipay and inherited its web micro-framework Pando ( Aspen), which is based on filesystem routing and simplates. Don't worry, it's quite simple. For example to make Liberapay return a Hello $user, your id is $userid message for requests to the URL /$user/hello, you only need to create the file www/%username/hello.spt with this inside:

from liberapay.utils import get_participant
participant = get_participant(state)
[---] text/html
{{ _("Hello {0}, your id is {1}", request.path['username'], }}

As illustrated by the last line our default template engine is Jinja.

The _ function attempts to translate the message into the user's language and escapes the variables properly (it knows that it's generating a message for an HTML page).

The python code inside simplates is only for request-specific logic, common backend code is in the liberapay/ directory.


Firstly, make sure you have the following dependencies installed:

  • python ≥ 3.6
    • including the C headers of python and libffi, which are packaged separately in many Linux distributions
  • postgresql 9.6 (see the official download & install docs)
  • make

Then run:

make env

Now you need to give yourself superuser postgres powers (if it hasn't been done already), and create two databases:

su postgres -c "createuser --superuser $(whoami)"

createdb liberapay
createdb liberapay_tests

If you need a deeper understanding take a look at the Database Roles and Managing Databases sections of PostgreSQL's documentation.

Then you can set up the DB:

make schema


Environment variables are used for configuration, the default values are in defaults.env and tests/test.env. You can override them in local.env and tests/local.env respectively.


Once you've installed everything and set up the database, you can run the app:

make run

It should now be accessible at http://localhost:8339/.

By default there are no users. You can create accounts like you would on the real website, and if you want you can also create a bunch of fake users (but they're not great):

make data

To grant admin permissions to an account, modify the database like so:

psql liberapay -c "update participants set privileges = 1 where username = 'account-username'"


To run a local payday open http://localhost:8339/admin/payday and click the "Run payday" button. You can add OVERRIDE_PAYDAY_CHECKS=yes in the local.env file to disable the safety checks that prevent running payday at the wrong time.


The python code interacts with the database by sending raw SQL queries through the library.

The official PostgreSQL documentation is your friend when dealing with SQL, especially the sections "The SQL Language" and "SQL Commands".

The DB schema is in sql/schema.sql, but don't modify that file directly, instead put the changes in sql/branch.sql. During deployment that script will be run on the production DB and the changes will be merged into sql/schema.sql. That process is semi-automated by

CSS and JavaScript

For our styles we use SASS and Bootstrap 3. Stylesheets are in the style/ directory and our JavaScript code is in js/. Our policy for both is to have as little as possible of them: the website should be almost entirely usable without JS, and our CSS should leverage Bootstrap as much as possible instead of containing lots of custom rules that would become a burden to maintain.

We compile Bootstrap ourselves from the SASS source in the style/bootstrap/ directory. We do that to be able to easily customize it by changing values in style/variables.scss. Modifying the files in style/bootstrap/ is probably not a good idea.


The easiest way to run the test suite is:

make test

That recreates the test DB's schema and runs all the tests. To speed things up you can also use the following commands:

  • make pytest only runs the python tests without recreating the test DB
  • make pytest-re does the same but only runs the tests that failed in the previous run

Updating test fixtures

Some of our tests include interactions with external services. In order to speed up those tests we record the requests and responses automatically using vcr. The records are in the tests/py/fixtures directory, one per test class.

If you add or modify interactions with external services, then the tests will fail, because VCR will not find the new or modified request in the records, and will refuse to record the new request by default (see Record Modes for more information). When that happens you can either switch the record mode from once to new_episodes (in liberapay/testing/ or delete the obsolete fixture files.

If the new interactions are with MangoPay you have to delete the file tests/py/fixtures/MangopayOAuth.yml, otherwise you'll be using an expired authentication token and the requests will be rejected.

Speeding up the tests

PostgreSQL is designed to prevent data loss, so by default it does a lot of synchronous disk writes. To reduce the number of those blocking writes our script automatically switches the synchronous_commit option to off for the test database, however this doesn't completely disable syncing. If your PostgreSQL instance only contains data that you can afford to lose, then you can speed things up further by setting fsync to off in the server's configuration file (postgresql.conf).

Tinkering with payments

Liberapay was built on top of MangoPay for payments, however they kicked us out so we've shifted to integrating with multiple payment processors. We currently support Stripe and PayPal. Support for Mangopay hasn't been completely removed yet.

Modifying python dependencies

All new dependencies need to be audited to check that they don't contain malicious code or security vulnerabilities.

We use pip's Hash-Checking Mode to protect ourselves from dependency tampering. Thus when adding or upgrading a dependency the new hashes need to computed and put in the requirements file. For that you can use hashin:

pip install hashin
hashin package==x.y -r requirements_base.txt -p 3.4 -p 3.6
# note: we have several requirements files, use the right one

If for some reason you need to rehash all requirements, run make rehash-requirements.

Processing personal data

When writing code that handles personal information keep in mind the principles enshrined in the GDPR.

Deploying the app

Note: Liberapay cannot be self-hosted, this section is only meant to document how we deploy new versions.

Liberapay is currently hosted on AWS (Ireland).

To deploy the app simply run, it'll guide you through it. Of course you need to be given access first.

Setting up a development environment using Docker

If you don't want to install directly dependencies on your machine, you can spin up a development environment easily, assuming you have Docker and docker-compose installed:

# build the local container
docker-compose build

# initialize the database
docker-compose run web bash

# populate the database with fake data
docker-compose run web python -m liberapay.utils.fake_data

# launch the database and the web server
# the application should be available on http://localhost:8339
docker-compose up

You can also run tests in the Docker environment:

docker-compose -f docker/tests.yml run tests

All arguments are passed to the underlying py.test command, so you can use -x for failing fast or --ff to retry failed tests first:

docker-compose -f docker/tests.yml run tests -x --ff


CC0 Public Domain Dedication (See this discussion for details.)

You can’t perform that action at this time.