Skip to content

Latest commit

 

History

History
300 lines (218 loc) · 13.8 KB

README.md

File metadata and controls

300 lines (218 loc) · 13.8 KB
Raw

BrigadeHub

Build Status npm Slack Status OSS Manifesto Keep A Changelog JS Standard

Table of Contents

Simplify your brigade's website maintenance

BrigadeHub is an alpha stage data portal for Code for America Brigades. It's being built to consolidate the efforts of maintaining a brigade's information into a single location, to distribute the task of content creation across the various non-technical brigade roles, and to enhance the experience of both members and admins of local volunteer brigades.

brigadehub, while deployed for Code for San Francisco, has not yet been optimized for wide adoption yet. If you deploy this to your production brigade site, you do so at your own risk.

For a complete top-down view of the roadmap, take a look at our active Roadmap Wiki

In short, BrigadeHub is designed to meet some very specific goals:

  • Be the external face for the brigade
  • Show Leadership / Contact info / member bios
  • Brigade Blogging
  • Show upcoming events and calendars through Meetup and Google Calendar API integration
  • Give new users a place to onboard through tight integration with Github oauth and expandable API integrations
  • Display and market active projects through Github API integration
  • Allow non-developers to update website info at-will
  • Allow developers to hack and customize as desired
  • Allow brigades to launch with a single non-dev step to their own environment (most likely Heroku)
  • Allow brigades to communicate with each other more effectively

This project is originally based on sahat/hackathon-starter, but the codebase has been heavily modified to meet our needs. We're striving to match feross/standard javascript styling, though the original boilerplate didn't conform to that, so it's a wip.

Inspirations

Similar projects have been conceived and implemented previously, most prominently by CodeForPhilly in the form of Laddr. The reason we're building a parallel system is for a few reasons:

  • a system that isn't based in PHP, and didn't require a custom Linux VM to run
  • to utilize the cross-discipline talents of Node.js developers, who generally can move from front-back end quickly
  • a one-click deploy system, preferably to Heroku, that would make deployment of a new hub effortless
  • a platform tightly coupled with the Github API, for oauth, handling permissioning and adminning of the github repos easily
  • a system that easily lent itself to additional onboarding steps for new members.

Another project which this is pulling inspiration from is CodeForAtlanta's Connector. Chime was also a CMS that had similar goals, but focused on local governments, rather than brigades.

Installation and usage

There are two methods of install at the moment: via cloning the source repo or docker. The prerequisites for each change depending on which you choose to use.

source docker

Source

Prerequisites
  • Command Line Tools
  •  Mac OS X:
    • Xcode (or OS X 10.9 Mavericks: xcode-select --install)
    • HomeBrew /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  •  Windows: Visual Studio
  •  Ubuntu /  Linux Mint: sudo apt-get install build-essential
  •  Fedora: sudo dnf groupinstall "Development Tools"
  •  OpenSUSE: sudo zypper install --type pattern devel_basis
  • MongoDB
    •  Mac OS X: brew install mongodb
    • run by typing in mongod
    • If you get a permissions error when running, you may need to make additional changes to your system post install:
      • type in whoami and note the username of the computer you're working on
      • sudo mkdir /data /data/db
      • sudo chown USERNAME:staff /data /data/db
      • You should be able to now run mongod without a permissions error.
  • Node.js v4+
    • Standard Install
      • Download the binary from the Node.js website that corresponds to your system
      • Follow the accompanying installation instructions to install
    • via NVM
      • *NVM gives you the a few extra nice-to-haves that makes development in Node a lot easier:
        • User Sandboxing
        • No need for sudo
        • Ability to run parallel versions of Node separate from each other
      • Uninstall any previously installed Node versions (if you don't already have nvm installed)
      • Install NVM using the script found on the nvm repo), or the following: curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash && echo 'export NVM_DIR="$HOME/.nvm"' >> $HOME/.bashrc && echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" # This loads nvm' >> $HOME/.bashrc && . $HOME/.bashrc && nvm install 6 && nvm alias default 6 && nvm use 6

Note: If you are new to Node or Express, I recommend to watch Node.js and Express 101 screencast by Alex Ford that teaches Node and Express from scratch. Alternatively, here is another great tutorial for complete beginners - Getting Started With Node.js, Express, MongoDB.

Install (source)
# Get the latest snapshot
git clone https://github.com/brigadehub/brigadehub.git

# Change directory
cd brigadehub

# Install NPM dependencies
npm install

# Copy the .env variables to your own file
cp .env.example .env

# If needed, start mongodb in a separate tab
mongod

Usage

To run the server in production, run:

npm start

or if starting for local development:

npm run develop

Docker

Prerequisites
Mac and Windows
Linux
Running

Simply run the following:

docker-compose up

This will build up a docker app and a dockerized mongodb and connect the two together. The docker compose file also runs nodemon, which will also listen to changes in your code and redeploy those changes in your docker container.

Testing

Linting

js-standard-style

For details on our linting / js coding style, visit `feross/standard'. Linting occurs automatically on commit, but you can run it manually by running:

npm run lint

Unit tests

Unit tests are being run via tap. Any file with the *.tap.js naming scheme will be run in unit tests. We are sorely lacking on unit testing, so anyone willing to take these on are very welcome. Unit tests are run automatically on commit, but you can run them manually anytime by running:

npm run test:unit

To run linting and unit tests together, you can run npm test.

End to end (e2e) tests

For end-to-end testing, we are using a Selenium standalone server, PhantomJS headless browser, and Nightwatch. Since end to end tests involve testing all aspects of the application, including UI interactions, all three of these services need to be running simultaneously to the development server.

Installing Selenium
npm run selenium:install
Runnning e2e tests

When you are ready to run e2e tests, you'll need to run the following commands in separate terminals:

  • npm run selenium:start
  • npm run develop
  • npm run test:e2e

To stop the selenium server after the tests, run npm run selenium:stop.

If for some reason, you need to stop the selenium server

npm selenium:stop

Deploy

brigadehub, while deployed for Code for San Francisco, has not yet been optimized for wide adoption yet. If you deploy this to your production brigade site, you do so at your own risk.

If you are outside Code for San Francisco and you want to get a version of brigadehub up for your brigade, fork brigadehub/brigadehub into your own brigade's organization. Updates should be done using upstream fetches. Contributing back should be done via Pull Request back to this repository :)

These instructions will be updated as the project emerges from the Alpha-release haze :P

Troubleshooting

Using a SCM client with Mac OS

There are issues, because of the way Mac OS and Node work together, or don't. Here's an example of people having problems

The most effective way of solving this, besides learning how to use the git CLI, would be to create an alias in your .bash_profile

Something like this

ghdc="open Applications/GitHub\ Desktop.app/Contents/MacOS/GitHub\ Desktop"

And instead of opening your client from an alias in applications

  1. open a terminal,
  2. cd to the brigadehubhub repo root
  3. run your alias

Changelog

To see what has changed in recent versions of brigadehub, see the CHANGELOG.

Core Contributors

Resources

will be adding resources soon

Other questions

Feel free to chat with the brigadehub core team (and many other users) on brigadehub Slack in the #brigadehub channel (join here), on IRC in the #brigadehub channel on Freenode, or via opening a new Github Issue here in the repo.

Contributing

Refer to our CONTRIBUTING.md doc.

License

This can be found in brigadehub's wiki as well.