Open Collective API

Foreword

If you see a step below that could be improved (or is outdated), please update the instructions. We rarely go through this process ourselves, so your fresh pair of eyes and your recent experience with it, makes you the best candidate to improve them for other users. Thank you!

Development

Prerequisite

1. Make sure you have Node.js version 24.x and NPM version 11.x.

• We recommend using nvm: nvm install && nvm use.

2. Make sure you have a PostgreSQL database available

• Check the version: 16.x or newer
• More info in our PostgreSQL Database documentation

3. For node-gyp, make sure you have Python 2 available and configured as the active version.

• You can use pyenv to manage Python versions.

Install

We recommend cloning the repository in a folder dedicated to opencollective projects.

git clone git@github.com:opencollective/opencollective-api.git opencollective/api
cd opencollective/api
npm install

Start

npm run dev

• API is started on http://localhost:3060
• A local email inbox is started on http://localhost:1080

See the dev docs for querying basics.

Troubleshooting

• If you're running into node-gyp issues related to Python 3 vs Python 2, you can run: npm rebuild
• If you have issues with PostgreSQL, check our dedicated documentation

Running tests

If your setup requires some specific values (e.g. custom database URL), create a .env.test file in the root of the project and set the values there.

To setup the test database, run npm run db:restore:test.

Tests can then be run with npm run test or npm run test:watch (watch mode). Since the full test suite can be quite heavy, we recommend passing the files you want to test as arguments to the command:

npm run test test/server/models/SocialLink.test.ts

Deployment

Summary: This project is currently deployed to staging and production with Heroku. To deploy, you need to be a core member of the Open Collective team.

See: docs/deployment.md

More documentation:

• PostgreSQL Database
• List of supported environment variables
• Developing with Emails

Discussion

If you have any questions, ping us on Discord.

License

MIT