To configure local Postgres create default role (if it hasn’t been created already) and database.

sudo -u postgres createuser --superuser $USER
createdb gratipay

If you are getting an error about unknown argument: '-mno-fused-madd' when
running make, then add
Wno-error=unused-command-line-argument-hard-error-in-future to your
ARCHFLAGS environment variable and run make clean env again (see this Stack Overflow answer
for more information):

Building

All Python dependencies (including virtualenv) are bundled with Gratipay in the
vendor/ directory. Gratipay is designed so that you don't manage its
virtualenv directly and you don't download its dependencies at build
time.

The included Makefile contains several targets. Configuration options
are stored in default_local.env file while overrides are in local.env.

To create virtualenv enviroment with all python dependencies installed
in a sandbox:

make env

If you haven't run Gratipay for a while, you can reinstall the dependencies:

make clean env

Add the necessary schemas and insert dummy data into postgres:

make schema
make fake

Launching

Once you've installed Python and Postgres and set up a database, you can use
make to build and launch Gratipay:

make run

If you don't have make, look at the Makefile to see what steps you need
to perform to build and launch Gratipay. The Makefile is pretty simple and
straightforward.

Congratulations! Sign in using Twitter or GitHub and you're off and
running. At some point, try running the test suite.

Configuring

Gratipay's default configuration lives in defaults.env.
If you'd like to override some settings, create a file named local.env to store them.

The following explains some of the content of that file:

The GITHUB_* keys are for a gratipay-dev application in the Gratipay
organization on Github. It points back to localhost:8537, which is where
Gratipay will be running if you start it locally with make run. Similarly
with the TWITTER_* keys, but there they required us to spell it 127.0.0.1.

If you are running Gratipay somewhere other than localhost:8537, then you'll
need to set BASE_URL, but your options are limited because we use proprietary
fonts from Typography.com, and they filter by
Referer. You won't get the right fonts unless you use an approved domain.
We've configured gratipay.dev as well as localhost, so if you don't want to
run on localhost then configure gratipay.dev in your
/etc/hosts file and set this in
local.env:

If you wish to use a different username or database name for the database, you
should override the DATABASE_URL in local.env using the following format:

DATABASE_URL=postgres://<username>@localhost/<database name>

We use Amazon Web Services' Simple Email Service (AWS SES) for sending emails.
In development, we dump outbound mail to the console by default. This is fine
if all you need to do is, e.g., copy/paste verification links. If you need to
receive emails within a proper mail client during development, then sign up for
AWS's free tier and override the AWS_*
credentials from defaults.env in your local.env. You'll have to verify the
email addresses you want to receive email with on SES.

Vagrant

Vagrant provides a convenient interface to VirtualBox to run and test
Gratipay in virtual machine. This may be handy if you're on Windows.

You will need Vagrant and VirtualBox
installed. On Linux you may need to install nfs-kernel-server as well.

With Vagrant, you can run Gratipay by running vagrant up from the project
directory. Please note that if you ever switch between running Gratipay on your
own machine to Vagrant or vice versa, you will need to run make clean.

The Vagrantfile will download a pristine Ubuntu image (base box), save it,
and create a virtual machine (VM) in VirtualBox. Then it will set up Gratipay
prerequisites (the process is known as "provisioning") and show a welcome message.

The next time you run vagrant up, it will reuse the VM. Vagrant uses SSH
based authentication. To login to VM, use the vagrant ssh command. If you're
prompted for a password when logging in, please use vagrant.

Mac users: If you're prompted for a password during initial installation,
it's sudo and you should enter your Mac OS password.

Ubuntu users: If you experience problems, please see this
issue.
As mentioned there, you will also need to be wary of projects that are nested
in encrypted directories.

Help!

If you get stuck somewhere along the way, make an
issue here on GitHub.

Thanks for installing Gratipay! 😃

Modifying CSS and JavaScript

We use SCSS, with files stored in scss/. All of the individual files are
combined in scss/gratipay.scss which itself is compiled by libsass in
www/assets/gratipay.css.spt
on each request (it's behind a CDN in production).

We use a similar pattern for JavaScript. Individual files are in js/, and
they're concatenated on the fly (and put behind a CDN in production) in
www/assets/gratipay.js.spt

Modifying the Database

We write SQL, specifically the PostgreSQL
variant. We keep our database
schema in
schema.sql,
and we write schema changes for each PR branch in a sql/branch.sql file, which
then gets run against production and merged into sql/schema.sql during
deployment.

Testing

Our test suite is divided into through-the-web (TTW) tests and Python tests.
You need to install Firefox and
geckodriver separately in
order to run the TTW tests. For both suites we use the
pytest test runner; it's installed automatically as part
of make env.

The easiest way to run the whole test suite is:

make test

You can also do:

make ttwtest

and/or:

make pytest

To invoke py.test directly you should use the honcho utility that comes
with the install. First make tests/env, then activate the virtualenv by
running source env/bin/activate, and then:

Be careful! The test suite deletes data in all tables in the public schema of the
database configured in your testing environment.

Local Database Setup

For the best development experience, you need a local installation of
Postgres. The best version of Postgres
to use is 9.6.2, because that's what we're using in production at Heroku. You
need at least 9.5 to support the features we depend on, along with the
pg_stat_statments and pg_trgm extensions.

/~username/payment-instructions.json
(source)—private—Responds
to GET with an array of objects representing your current payment
instructions. A payment instruction is created when a ~user instructs Gratipay
to make voluntary payments to a Team. Pass a team_slug with GET to fetch
payment instruction only for that particular team. POST an array of objects
containing team_slug and amount to bulk upsert payment instructions (make
sure to set Content-Type to application/json). The amount must be encoded
as a string rather than a number. In case the upsert is not successful for any
object, there will be an error attribute in the response explaining the error
along with the team_slug to identify the object for which the error occurred.

This endpoint requires authentication. Look up your user ID and API key on your
account page and pass them using
basic auth.