Skip to content
This repository has been archived by the owner on Aug 11, 2024. It is now read-only.

beabee-communityrm/beabee

Repository files navigation

๐Ÿ beabee

Welcome to the official GitHub repository for beabee, where you'll find both the backend API and the legacy frontend application for beabee. Discover more about beabee by visiting our website at beabee.io.

beabee was initially developed for the South London Makerspace and later adapted for use by The Bristol Cable.

Deploy Status Known Vulnerabilities

Contact Us

We're always excited to connect with our community, hear feedback, and answer any questions you might have! If you're interested in learning more about beabee or have any questions, please feel free to reach out:

Your input is invaluable to us as we continue to grow and improve beabee. Don't hesitate to get in touch!

๐Ÿ’ป Install

โš ๏ธโš ๏ธโš ๏ธ WARNING โš ๏ธโš ๏ธโš ๏ธ

If you want to deploy beabee on a server refer to beabee/beabee-deploy instead. The instructions below are for running beabee locally for development

You need:

  • Docker >= 19.03.8
  • Docker Compose >= 2
  • Node.js >= 20.10.0

NOTE: Lower non-major versions probably work but haven't been tested

To just look around the system you can just use the example env file (.env.example) as is, but you'll need to create a sandbox GoCardless account to test any payment flows.

cp .env.example .env

npm install
npm run build
docker compose build

# Initialise database
docker compose up -d db
docker compose run --rm app npm run typeorm migration:run

# Do the rest
docker compose up -d

To get started

Create a new super admin

docker compose run --rm app node built/tools/new-user

Payment methods and email domain

docker compose exec app node built/tools/configure

โš ๏ธ If you only set up the system locally, it doesn't matter what email domain you specify, but it still has to be valid, e.g. example.org.

Import some data

Need some test data? Download it here: coming soon

docker compose run --rm -T app node built/tools/database/import.js < <import file>

Go to the frontend

Now check out the frontend in parallel in a separate directory and start it as described in the README.md.

By default, this should now be accessible via http://localhost:3000 and communicate with the backend API over http://localhost:3001.

</> Development

Development is containerized, in general you should be able to use the following to get started

npm start

You can also use the following when just working on the API (faster reloading)

npm run dev:api

Rebuilding containers

If you make changes to .env you need to recreate the Docker containers

docker compose up -d

docker compose up -d


If you change the dependencies in `package.json` you must rebuild and recreate the Docker containers

```bash
docker compose build
docker compose up -d

Generating database migrations

Whenever you make changes to a database model, you need to create a migration file. TypeORM will automatically generate a migration file based on your schema changes

docker compose start db
docker compose run app npm run typeorm migration:generate src/migrations/MigrationName && npm run fix:prettier
npm run build
docker compose run app npm run typeorm migration:run

If you are still in the development phase, you may want to undo your last database migration as follows:

docker compose run app npm run typeorm migration:revert

To find out more about this topic, take a look at the TypeORM Migration Guide.

๐Ÿ“ฐ Documentation

Documentation is currently very limited, please contact us and we will try to adapt the documentation accordingly.

The codebase is broadly split into a few different parts

  • beabee core

    Shared between all services (API, webhooks and legacy)

./src/core
./src/models - Data models and database entities
./src/config - Config loader
  • API service
./src/api
  • Webhook service

Handlers for webhooks from beabee's integrations (currently GoCardless, Mailchimp and Stripe)

./src/webhook
  • Legacy app

This is slowly being removed, with business logic being moved into the API and frontend into the new frontend.

./src/apps
./src/static
./src/views
  • Tools

Various tools for administration, including nightly cron jobs

./src/tools
  • Database migrations

Autogenerated by TypeORM

./src/migrations

๐Ÿคฒ Common Package

The backend and frontend share some code through the beabee-common NPM package.

๐Ÿ–ผ๏ธ Frontend

You are currently browsing the repository that includes our legacy frontend application. This version is phased out and will be deprecated in due course. The revamped and currently active frontend, built with Vite and Vue, is accessible here.

๐Ÿ“ก Webhooks

Webhooks are handled by the webhook_app service. This is a separate service from the API to allow for scaling independently.

/webhook/ping - Used to check if the webhook service is running and available, e.g. http://localhost:3001/webhook/ping

/webhook/stripe - Stripe webhooks are handled by the stripe service, see Payment Providers for more information.

/webhook/gocardless - GoCardless webhooks are handled by the gocardless service, see Payment Providers for more information.

/webhook/mailchimp - Mailchimp webhooks are handled by the mailchimp service, see MailChimp for more information.

๐Ÿ“ง E-mail

Prepare for local development

By default we are using MailDev for local development. For this to work it must be configured the first time, run the following command if not already done:

docker compose exec app node built/tools/configure

If the Docker Compose Stack is started, you can reach MailDev via http://localhost:3025/ by default. If you now receive an e-mail during your tests, you will find it there.

๐Ÿ“ฎ MailChimp

MailChimp is used for sending newsletters and other marketing emails.

To be able to send emails you need to create a MailChimp account and create a new API key in the MailChimp dashboard.

The API key can be found in the MailChimp dashboard under the API keys section.

๐Ÿ’ฐ Payment Providers

We are using stripe for membership payments.

Prepare for local development

Make sure you have defined the environment variables in the .env file:

BEABEE_STRIPE_PUBLICKEY=<public key>
BEABEE_STRIPE_SECRETKEY=<secret key>

And also that you have configured the payment methods using

docker compose exec app node built/tools/configure

You can get the public key and secret key in the Stripe dashboard.

To be able to receive webhooks from stripe you need to forward them to your local environment and create a webhook secret using the Stripe CLI:

stripe login
stripe listen --forward-to localhost:3001/webhook/stripe

Now the stripe CLI prints out the webhook secret, copy it and add it to the .env file while you keep the forwarding process running:

BEABEE_STRIPE_WEBHOOKSECRET=<webhook secret>

โš ๏ธ To be able to create a payment in the frontend you need to be able to receive confirmation emails, so make sure you have setup E-Mail.

โš ๏ธ Since the environment variable has changed you also need to rebuild the containers.

๐Ÿค Advertising

Browser testing with