<img alt="Welcome to Gratipay" src="https://raw.githubusercontent.com/gratipay/gratipay.com/master/img-src/readme-banner.png"/>

Gratipay helps companies pay for open source, in order to cultivate an economy of gratitude, generosity, and love.

| Scope | Documentation | |:-------|:------| | company<br>policies, procedures, etc. | http://inside.gratipay.com | | product<br>customer-facing pages | https://gratipay.com/about | | software installation | ← You are here! | | python library | https://gratipay.readthedocs.io/ |

Quick Start
Installing
Installing with Vagrant
Installing with Docker
Configuring
Developing
Testing
API
- Implementations
Glossary
License

Quick Start

Thanks for hacking on Gratipay! Be sure to review CONTRIBUTING as well if that's what you're planning to do.

Unix-like

Given Python 2.7, Postgres 9.6, and a C/make toolchain:

git clone https://github.com/gratipay/gratipay.com.git
cd gratipay.com
createdb gratipay
make schema fake

Now make run to boot the app or make test to run the tests.

Vagrant

Given VirtualBox 4.3 and Vagrant 1.7.x:

vagrant up

Docker

Given some version(?) of Docker:

docker build -t gratipay .
docker run -p 8537:8537 gratipay

Installing

Satisfying Dependencies

Building, launching, developing and testing gratipay.com requires several pieces of software:

a C/make toolchain,
Python version 2.7,
Postgres version 9.6, and
Firefox and geckodriver for testing.

Unix-like operating systems (Ubuntu, macOS, etc.) generally include a C/make toolchain. If you're on Windows, your best bet is to use Vagrant or Docker.

All Python dependencies are bundled in our repo (under vendor/), but some include C extensions with additional operating-system level dependencies that need to be met. Here are notes for psycopg2. Other candidates for trouble are libsass and cryptography. Good luck!

Debian/Ubuntu

Maybe try scripts/bootstrap-debian.sh?

macOS

If make env gives you an Operation not permitted error from shutil.copytree then you're probably using the system Python and you should try Homebrew instead:

brew install python

Here are the installation options for Postgres.

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):

ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future make clean env

Setting up a Database

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_statements and pg_trgm extensions.

To setup Postgres for Gratipay's needs run:

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

You can speed up the test suite when using a regular HDD by running:

psql -q gratipay-test -c 'alter database "gratipay-test" set synchronous_commit to off'

Schema

Once Postgres is set up, run:

make schema

Which populates the database named by DATABASE_URL with the schema from sql/schema.sql.

Example data

The gratipay database created in the last step is empty. To populate it with some fake data, so that more of the site is functional, run this command:

make fake

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 (a Python-specific sandboxing mechanism) directly and you don't download its dependencies at build time but rather at clone time. To create a virtualenv with all Python dependencies installed:

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.

If Gratipay launches successfully it will look like this:

$ make run
PATH=env/bin:{lots-more-of-your-own-PATH} env/bin/honcho run -e defaults.env,local.env web
[2017-08-25 15:05:18 -0400] [18093] [INFO] Starting gunicorn 19.7.1
[2017-08-25 15:05:18 -0400] [18093] [INFO] Listening at: http://0.0.0.0:8537 (18093)
[2017-08-25 15:05:18 -0400] [18093] [INFO] Using worker: sync
[2017-08-25 15:05:18 -0400] [18096] [INFO] Booting worker with pid: 18096
pid-18096 thread-140736833041344 (MainThread) Instantiating Application from gunicorn_entrypoint
pid-18096 thread-140736833041344 (MainThread) Reading configuration from defaults, environment, and kwargs.
pid-18096 thread-140736833041344 (MainThread)   base_url                                              default                 
pid-18096 thread-140736833041344 (MainThread)   changes_reload         False                          default                 
pid-18096 thread-140736833041344 (MainThread)   changes_reload         True                           environment variable ASPEN_CHANGES_RELOAD=yes
pid-18096 thread-140736833041344 (MainThread)   charset_dynamic        UTF-8                          default                 
pid-18096 thread-140736833041344 (MainThread)   charset_static         None                           default                 
pid-18096 thread-140736833041344 (MainThread)   colorize_tracebacks    True                           default                 
pid-18096 thread-140736833041344 (MainThread)   indices                [u'index.html', u'index.json', u'index', u'index.html.spt', u'index.json.spt', u'index.spt'] default                 
pid-18096 thread-140736833041344 (MainThread)   list_directories       False                          default                 
pid-18096 thread-140736833041344 (MainThread)   logging_threshold      0                              default                 
pid-18096 thread-140736833041344 (MainThread)   media_type_default     text/plain                     default                 
pid-18096 thread-140736833041344 (MainThread)   media_type_json        application/json               default                 
pid-18096 thread-140736833041344 (MainThread)   project_root           None                           default                 
pid-18096 thread-140736833041344 (MainThread)   project_root           .                              environment variable ASPEN_PROJECT_ROOT=.
pid-18096 thread-140736833041344 (MainThread)   renderer_default       stdlib_percent                 default                 
pid-18096 thread-140736833041344 (MainThread)   show_tracebacks        False                          default                 
pid-18096 thread-140736833041344 (MainThread)   show_tracebacks        True                           environment variable ASPEN_SHOW_TRACEBACKS=yes
pid-18096 thread-140736833041344 (MainThread)   www_root               None                           default                 
pid-18096 thread-140736833041344 (MainThread)   www_root               www/                           environment variable ASPEN_WWW_ROOT=www/
pid-18096 thread-140736833041344 (MainThread) project_root is relative to CWD: '.'.
pid-18096 thread-140736833041344 (MainThread) project_root set to /Users/whit537/personal/gratipay/gratipay.com.
pid-18096 thread-140736833041344 (MainThread) Found plugin for renderer 'jinja2'
pid-18096 thread-140736833041344 (MainThread) Renderers (*ed are unavailable, CAPS is default):
pid-18096 thread-140736833041344 (MainThread)   json_dump        
pid-18096 thread-140736833041344 (MainThread)   jsonp_dump       
pid-18096 thread-140736833041344 (MainThread)   stdlib_template  
pid-18096 thread-140736833041344 (MainThread)   stdlib_format    
pid-18096 thread-140736833041344 (MainThread)   jinja2           
pid-18096 thread-140736833041344 (MainThread)   STDLIB_PERCENT   
pid-18096 thread-140736833041344 (MainThread) Won't log to Sentry (SENTRY_DSN

Gratipay.com

Install / Use

README