January 8, 2020

965 words 5 mins read



A self-hosted event management tool for nonprofits

repo name freeCodeCamp/chapter
repo link https://github.com/freeCodeCamp/chapter
language TypeScript
size (curr.) 1520 kB
stars (curr.) 1603
created 2019-10-14
license BSD 3-Clause “New” or “Revised” License

Welcome to Chapter

All Contributors

After several years of being dissatisfied with existing group event tools (Meetup, Facebook events) we decided to build our own.

This will be a self-hosted Docker container deployed to the cloud with a one-click and then configured by the owner. No coding required.

Your organization can host an instance of Chapter under a sub-domain of your website, such as chapter.sierraclub.org or chapter.womenwhocode.org.

All of an organization’s user data will remain under their control.

Our Vision statement provides more details on the reasons for Chapter.


To better communicate and more easily build an API and UI, the current contributors have decided on a collection of terminology to clarify discussions surrounding the Chapter project:

Term Definition Example
instance a web server deployment of the “Chapter” application, managed by an organization. a Docker container running on a web host
organization a non-profit with multiple chapters Women Who Code at the sub-domain: chapter.womenwhocode.org
chapter a container for events and users Women Who Code - New York City
event a meeting with a specific location and time to which users can RSVP Coffee And Code - BistroOne, New York City, NY - April 9, 2020
user an authenticated user who is authorized based on their role(s) Sally Gold - SallyG@example.com
visitor an non-authenticated web browser session with view-only access to public content Anonymous Web Browser Client
owner the role of a user who can configure the “Chapter” application instance and manage administrators for an entire organization Women Who Code - Global IT
administrator the role of a user who can setup and manage chapters and organizers for an organization Women Who Code - European Administrator
organizer the role of a user who can manage a chapter’s events, RSVPs, communications, and members Women Who Code - Edinburgh, Local Organizer
member the role of a user who can follow and receive notifications from a chapter and RSVP to events Women Who Code - Edinburgh, Local Member

Tech Stack

We are planning to use the following tools:

A lot of people know these tools, and they’re proven to work well at scale.

We will focus on building an open API first. Then, developers can use the API to build their own mobile clients and voice interface clients.

Development Setup

Requirements: Node.js, Docker, internet access

Installing Node.js

Follow instructions for downloading and installing Node.js for your operating system from the official Node.js website.

Ensure you are installing Node 13 and npm 6 or greater.

Installing Docker

See the Docker installation “Supported platforms” section and follow the instructions to download & install Docker Desktop for your operating system (or Docker CE for Linux).

You can find more resources on Docker here:

Starting the Development Server

Open up Terminal/Powershell/bash and navigate to the directory where you want the project to live.

Clone this repository:

git clone https://github.com/freeCodeCamp/chapter

Navigate to the newly cloned repo:

cd chapter

Install dependencies:

npm install

If you’re using local setup (no docker), make sure you add your DB credentials to .env file

Running the server:

Ensure that Docker Desktop is up and running, then run the following command:

docker-compose up

Wait for the logs to show “server started on port 8000”, then navigate to localhost:8000 to view the app.

The server will automatically restart anytime you save a .ts or .js file within the server/ directory.

You can run any command within the container by prefixing it with docker-compose exec app, e.g. docker-compose exec app npm install express

Natively running node in Windows/MacOS/Linux (no docker)

DISCLAIMER: This is a more hands on approach.

This is a lot lighter setup, but you need to provide your own Postgres DB. If you don’t want to run one locally you can get it as a service on ElephantSQL.

After you setup the DB instance local or remote, create a database, add the DB name and credentials to .env

MAKE SURE TO SET IS_DOCKER= in .env to blank

npm run dev

Additional DB docs can be found in server/docs/README.md


Run tests

npm run test

If you’re running in docker compose prefix the command with docker-compose exec

NODE_ENV=test docker-compose exec app npm run test

Run tests in watch mode

npm run test:watch

API Specification

We use Open API 3.0 to define the API structure of the application.

You can see our full API documentation by navigating to http://localhost:8000/api/v1/docs.


a diagram illustrating the proposed schema for Chapter

created with DBeaver.io

User Stories


The MVP user stories are shown in the MVP Project kanban / cards and as issues marked with “MVP”.


We are maintaining a list of post-MVP conversations and user stories using the “Roadmap” tag.

Quincy Larson is the project lead. FreeCodeCamp will start “dogfooding” the MVP with several of its local study groups.

Here’s an out-dated example of an app with similar functionality: The freeCodeCamp Study Group Directory.



Copyright © 2020 freeCodeCamp.org

The computer software is licensed under the BSD-3-Clause license.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

comments powered by Disqus