-
Notifications
You must be signed in to change notification settings - Fork 27
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #237 from membermatters/feature/update-readme
Update README.md
- Loading branch information
Showing
1 changed file
with
99 additions
and
55 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,88 +1,132 @@ | ||
| # MemberMatters | ||
| MemberMatters is an open source membership and access management solution. | ||
|
|
||
| MemberMatters is an open source membership, billing and access control solution for makerspaces and community groups. | ||
|
|
||
| ### Main Features | ||
| * Supports all major browsers with first class mobile support, dark mode, and native mobile app (capacitor). | ||
| * Kiosk mode with site sign/sign out feature (electron). | ||
| * Member registration system (signup, login, profile etc) with recurring membership payments via Stripe. | ||
| * Single Sign On (SSO) system implemented via the discourse protocol. | ||
| * Issue reporting tool. | ||
| * Access system built in with granular door and tool/machines permissions - read below for access control hardware resources. | ||
| * Admin Interface for managing all aspects of the system. | ||
| * Webcam snapshots, last swipes, who's on site, and other member tools. | ||
| * Full "Memberbucks" Support for on site payments via tapping a membership card. | ||
| * And many more! Look through the screenshots below or setup your own instance to play around. | ||
|
|
||
| ### Deprecation Warning | ||
| The following features have been removed: | ||
| * Sendgrid integration - please use our Postmark integration instead. | ||
| * Xero integration - please use Stripe billing to manage payments. | ||
|
|
||
| * Supports all major browsers with mobile support and dark mode. | ||
| * Kiosk mode (electron) with site sign/sign out feature to restrict access to tools. | ||
| * Member registration system (signup, login, profile etc). | ||
| * Recurring membership payments via credit card with Stripe including: | ||
| * Integration with Canvas or Moodle for a mandatory online induction course during sign up. | ||
| * Support for manual account activation/deactivations for members without a Stripe subscription. | ||
| * Self service billing (ie members can cancel their membership or update credit card themselves). | ||
| * Automatic swipe card deactivation on overdue payments. | ||
| * Automatic swipe card activation for returning members. | ||
| * Single Sign On (SSO) provider with support for both OIDC and the discourse protocol. | ||
| * Issue reporting form with Trello integration. | ||
| * Access Control system built in including: | ||
| * Access permissions checking screen for members. | ||
| * Default access permissions for new members. | ||
| * Audit logs (including interlock time used and posts to Discord) for every successful/failed swipe. | ||
| * Integration with our Access Control firmware which supports: | ||
| * Communication over websockets for flexibility in placement (your MM server can be offsite!). | ||
| * Offline cache that is updated automatically in realtime as permissions change. | ||
| * Remote unlocking, syncing and rebooting of devices. | ||
| * Controlling access to most types of doors and tools. | ||
| * Memberbucks purchases via RFID and integration with some vending machines (MDB support coming soon). | ||
| * Integration with Sendgrid/Postmark for emails and Twilio for SMS notifications including: | ||
| * SMS and email alerts for swipe card deactivation/failed swipes etc. | ||
| * Manual SMS notifications to members for urgent issues (they can take a while to check emails) | ||
| * Admin Interface for managing all aspects of the system (and Django admin fills in the gaps). | ||
| * Show members Webcam snapshots, latest swipes, who's on site, and other member tools. | ||
| * Full "Memberbucks" Support for on site and in-portal payments. | ||
| * And many more! Feel free to open an issue or discussion if you see anything missing or want to suggest new features. | ||
|
|
||
| ## Getting Started | ||
| See the [getting started](/docs/GETTING_STARTED.md) instructions for how to run the MemberMatters software for your | ||
| organisation. Once you've finished installing MemberMatters, your should read the [post installation steps](/docs/POST_INSTALL_STEPS.md) for important instructions on setting up and customising your instance. | ||
|
|
||
| See the [getting started](/docs/GETTING_STARTED.md) instructions for how to run the MemberMatters software for your organisation. Once you've finished installing MemberMatters, your should read the [post installation steps](/docs/POST_INSTALL_STEPS.md) for important instructions on setting up and configuring your instance. | ||
|
|
||
| MemberMatters is production quality software and has been used by several makerspaces for over 5 years. However, as an open source project, we focus our limited resources on features and bug fixes so our documentation can always be improved. Please open an issue if you have any suggestions to make it better. | ||
|
|
||
| ### Compatibility | ||
| Currently, MemberMatters is only officially supported on the latest LTS release of Ubuntu Server. Being Docker, you should be able to run it on various other platforms, but minimal support will be available. We currently offer AMD64, ARM64 and ARMv7 builds on Dockerhub. | ||
|
|
||
| Officially, the only supported way to run MemberMatters is with the official Docker Hub image on a Ubuntu Server LTS host. Being Docker, you should be able to run it on various other platforms, but minimal support will be available. There is both an AMD64 and ARM64 build on Dockerhub for each release. | ||
|
|
||
| ## Updates and Releases | ||
| The official changelog is available on the website [here](https://membermatters.org/CHANGELOG). You will also find each release [here](https://github.com/membermatters/MemberMatters/releases) on GitHub. | ||
|
|
||
| ## Getting Started (Developers) | ||
| ### Pre-Commit Hooks | ||
| We use husky and lint-staged to manage pre commit hooks. The first thing you should do is run `npm install` in this | ||
| directory. This installs and configures the pre commit hooks automatically. After doing this, you should see them run | ||
| when you try to commit a file (for example, with `git commit -m "update thing"`). | ||
| The official changelog is available on the website [here](/CHANGELOG.md). You will also find each release [here](https://github.com/membermatters/MemberMatters/releases) on GitHub. | ||
|
|
||
| ### Vue.js JavaScript frontend | ||
| Please see the [readme](src-frontend/README.md) file inside the `src-frontend` folder. This folder contains all of the source | ||
| code and other assets needed by the frontend. | ||
| ## Door, Interlock & Vending Machine Hardware | ||
|
|
||
| ### Django Python backend | ||
| Please see the [readme](memberportal/README.md) file inside the `memberportal` folder. This folder contains all of the source | ||
| code and other assets needed by the backend. | ||
| As part of our access control system (including doors, tool interlocks & vending machine payments) @jabelone has developed a "mainboard" PCB and firmware that is compatible with MemberMatters. The second iteration of this PCB has proven quite reliable over the last ~2yrs, despite a handful of hardware bugs. This PCB will be published eventually as the "standard" access control hardware for use with MemberMatters once (if) this design reaches production ready quality. It will not be published before this to prevent issues/disappointment/support requests. | ||
|
|
||
| ### Development tip (dev server proxy) | ||
| The Vue.js (Quasar) frontend and Django backend run different dev servers on different ports. Due to | ||
| this you will run into issues with sharing cookies etc across the different URIs. To get around | ||
| this, the webpack dev server has been setup to proxy all requests to `/api` to `localhost:8000` so | ||
| you'll need to make sure the django dev server is running there. | ||
| However, our Access Control Firmware should run on most ESP32 devices. It is also compatible with many off the shelf dev boards and peripherals including UART and Wiegand RFID readers, 16x2 i2c LCD screens, etc. To use this firmware, connect a compatible RFID reader, some sort of output (contactor for a tool interlock, electronic door strike, vend relay etc.) and configure it to connect to your MemberMatters instance. Once connected, you can authorise it and use it within MemberMatters. | ||
|
|
||
| ## Door, Interlock & Vending Machine Resources | ||
| This software was initially developed by Jaimyn Mayer for HSBNE, and later adopted for use at Brisbane Makerspace and others. As part of our access control system (including doors and machine interlocks) we have developed a set of standard hardware components and firmware that is compatible with MemberMatters. Below is a list of useful resources for building your own hardware using off the shelf components. Once the hardware is built and firmware is flashed, you can add them to MemberMatters for a complete access system and/or billing system for physical purchases. | ||
| You can read more about how to use the firmware in it's repo at [MemberMatters Access Control Firmware](https://github.com/membermatters/mainboard-firmware). | ||
|
|
||
| * [HSBNE Inc Access Control Wiki Page](https://wiki.hsbne.org/infrastructure/services/accesscontrol) - Information about our current and past access control hardware. | ||
| * [Member Matters Access Control Firmware](https://github.com/membermatters/mainboard-firmware) - Micropython based software that runs on ESP32 devices that powers our interlock/door controllers. | ||
| * [DEPRECATED] ~[HSBNE Access Control Firmware](https://github.com/HSBNE/AccessControl) - Arduino based software that runs on ESPxx devices that run each of our interlock/door controllers.~ | ||
| * [HSBNE Access Control Hardware BOM](https://docs.google.com/spreadsheets/d/1sQvaxc8gp7CUdddq65luUwCwQNSQK4HCsXnodN-CSEk/edit#gid=0) - A list of materials that go into our access control system hardware. | ||
| * [Vending Machine RFID Panel Firmware](https://github.com/HSBNE/VendingMachine) - Arduino based software that powers our Spacebucks (memberbucks) enabled vending machines. | ||
|
|
||
| ## Screenshots | ||
|
|
||
| ### Mobile | ||
|
|
||
| <img src="screenshots/m1.png" width="200"> <img src="screenshots/m2.png" width="200"> <img src="screenshots/m3.png" width="200"> <img src="screenshots/m4.png" width="200"> <img src="screenshots/m5.png" width="200"> | ||
|
|
||
| ### Desktop | ||
|
|
||
| <img src="screenshots/1.png" width="500"> <img src="screenshots/2.png" width="500"> <img src="screenshots/3.png" width="500"> <img src="screenshots/4.png" width="500"> <img src="screenshots/5.png" width="500"> | ||
|
|
||
| ### Desktop (Dark Mode) | ||
|
|
||
| <img src="screenshots/d1.png" width="500"> <img src="screenshots/d2.png" width="500"> <img src="screenshots/d3.png" width="500"> | ||
|
|
||
| See the [screenshots](screenshots) folder for more screenshots. | ||
|
|
||
| # Developers Information | ||
|
|
||
| ## Getting Started | ||
|
|
||
| ### Pre-Commit Hooks | ||
|
|
||
| We use husky and lint-staged to manage pre commit hooks. The first thing you should do is run `npm install` in this | ||
| directory. This installs and configures the pre commit hooks automatically. After doing this, you should see them run | ||
| when you try to commit a file (for example, with `git commit -m "update thing"`). | ||
|
|
||
| ### Development tip (dev server proxy) | ||
|
|
||
| The Vue.js (Quasar) frontend and Django backend run different dev servers on different ports. Due to | ||
| this you will run into issues with sharing cookies etc across the different URIs. To get around | ||
| this, the webpack dev server has been setup to proxy all requests to `/api` to `localhost:8000` so | ||
| you'll need to make sure the django dev server is running there. | ||
|
|
||
| ### Vue.js JavaScript frontend | ||
|
|
||
| Please see the [readme](src-frontend/README.md) file inside the `src-frontend` folder. This folder contains all of the source | ||
| code and other assets needed by the frontend. | ||
|
|
||
| ### Django Python backend | ||
|
|
||
| Please see the [readme](memberportal/README.md) file inside the `memberportal` folder. This folder contains all of the source | ||
| code and other assets needed by the backend. | ||
|
|
||
| ## Contributing guidelines | ||
|
|
||
| By contributing code, or any other resource to this repository, you agree to license it | ||
| under the open source MIT license. Please use good coding practices, comment | ||
| your code well and ensure compliance with any code formatting or linting that's in place. Also | ||
| avoid "weird tricks" and optimisations that don't read easily - this is a web app, not a high | ||
| under the open source MIT license. Please use good coding practices, comment | ||
| your code well and ensure compliance with any code formatting or linting that's in place. Also | ||
| avoid "weird tricks" and optimisations that don't read easily - this is a web app, not a high | ||
| performance algorithm. Your contributions *will* be rejected if you do not follow these guidelines so please be careful. | ||
|
|
||
| All PRs should be made from your own branch/fork into the `dev` branch. Every now and again we'll collect the changes in | ||
| dev, do up a release, and push to `main`. | ||
| All PRs should be made from your own branch/fork into the `dev` branch. Every now and again we'll collect the changes in dev, do up a release, and push to `main`. The `main` branch should always contain the most recent release. | ||
|
|
||
| ## Release Checklist | ||
|
|
||
| We use [semantic versioning](https://semver.org). | ||
|
|
||
| * Update package.json version. | ||
| * Update src-frontend/package.json version. | ||
| * Update CHANGELOG.md with all changes since the last version. | ||
| * Make a new commit with above changes and commit title in the format of e.g. `v3.4.5`. | ||
| * Once this is merged into the `main` branch, tag the merge commit with the same name and GHA will build/deploy the docker image. | ||
| * Create a [new release on GitHub](https://github.com/membermatters/MemberMatters/releases/new) | ||
| * Choose the tag you just created. | ||
| * For the title use the version number as above e.g. `v3.4.5`. | ||
| * For the description use the new entries added to the changelog. | ||
| * Close out any issues fixed by this release (preferably after confirming that it fixes it). | ||
|
|
||
| # Organisations using MemberMatters | ||
|
|
||
| ## Organisations using MemberMatters | ||
| Feel free to add your organisation to this list (via a pull request) if you're actively using or trialling MemberMatters and are a not for profit or similar. Make sure to include a link to your website and the date you added it. | ||
| Feel free to add your organisation to this list (via a pull request) if you're actively using or trialling MemberMatters. Make sure to include a link to your website and the date you added it. | ||
|
|
||
| * [Brisbane Makerspace](https://brisbanemaker.space) (October 2021) - A community workshop for makers in Brisbane, with a focus on high quality tools. | ||
| * [HSBNE Inc](https://hsbne.org) (January 2020) - A hackerspace based in Brisbane, QLD. | ||
| * [Make Monmouth](https://www.makemonmouth.co.uk/) (November 2023) - A community makerspace based in Monmouth, Wales, UK | ||
| * [SparkCC](https://www.sparkcc.org) (September 2021) - A community of makers on the NSW Central Coast | ||
| * [BMS (Brisbane Makerspace)](https://brisbanemaker.space) (October 2021) - Brisbane's friendliest community workshop based in Brisbane, QLD, Australia. | ||
| * [Make Monmouth](https://www.makemonmouth.co.uk/) (November 2023) - A community makerspace based in Monmouth, Wales, UK. | ||
| * [SparkCC](https://www.sparkcc.org) (September 2021) - A community of makers on the NSW Central Coast based in Palmdale, NSW, Australia. |