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.
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:
- Issues: GitHub Issues
- Email: [email protected]
Your input is invaluable to us as we continue to grow and improve beabee. Don't hesitate to get in touch!
⚠️ ⚠️ ⚠️ 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 -ddocker compose run --rm app node built/tools/new-userdocker 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.
Need some test data? Download it here: coming soon
docker compose run --rm -T app node built/tools/database/import.js < <import file>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 is containerized, in general you should be able to use the following to get started
npm startYou can also use the following when just working on the API (faster reloading)
npm run dev:apiIf you make changes to .env you need to recreate the Docker containers
docker compose up -ddocker 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
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:runIf 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:revertTo find out more about this topic, take a look at the TypeORM Migration Guide.
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
The backend and frontend share some code through the beabee-common NPM package.
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 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.
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/configureIf 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 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.
We are using stripe for membership payments.
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/configureYou 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/stripeNow 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.
Browser testing with
