Skip to content

Latest commit

 

History

History
133 lines (91 loc) · 7.06 KB

README.md

File metadata and controls

133 lines (91 loc) · 7.06 KB
Raw

BKKHackMap   Build Status Gitter chat

The hackmap is a visual tool developed by the BKK/hack community to help members find one another and collaborate at hack night meetup events. See it in action at https://bkkhack.github.io/hackmap.

Some of our main design goals for this application were:

  • Make it easy and inexpensive to operate. The hackmap runs on GitHub Pages and a small free Heroku Dyno as an authentication proxy. Data persistence is done entirely through GitHub issues with the GitHub API.
  • Reduce friction for new community members to join and participate. You need only a GitHub account, which we think is a good step even for beginning developers.

If you'd like to use and enhance the hackmap for your own community, we welcome contributions to generalize it and make it more configurable.

Development

If you want to contribute, we'd love it! Feel free to open issues or pull requests in this repository. There are number of issues already tracking feature wishes and known bugs, dive in!

If you have any questions, ask @waf, @djay or @ches in the Gitter chat.

Overview

This webapp is a single page application, and contains client-side code only. The server-side functionality is provided by:

  • GitHub Issues - This is the primary data store. The client-side code makes GitHub API calls to persist data as GitHub issue comments.
  • Heroku - A very small, free instance running GateKeeper to hide the GitHub OAuth secret.

The client-side code is written in ES6, with Vue.js for the UI. It uses webpack and babel for transpilation to ES5.

Working on the code

To get started, clone this repo and run:

  1. npm install -- downloads development and runtime dependencies.
  2. npm start -- starts up webpack development webserver to serve the application, monitor changes and rebuild assets on change.

The following commands are also available:

  • npm test -- starts the unit test runner, and reruns unit tests as files change.
  • npm run lint -- checks code style according to eslint setup.
  • npm run build -- builds the assets (js, sourcemaps, etc.) into the dist folder.
  • npm run deploy -- deploys dist folder to gh-pages branch.

Editor Setup

This project uses Vue.js Components (i.e. .vue files) to organize the code. You'll probably want to install an extension to your editor to get syntax highlighting, code completion, etc. Most major editors are supported.

Additionally, we use an .editorconfig file to automatically configure coding style (e.g. indent levels, tabs vs spaces). Again, most major editors have an editorconfig plugin, or already support it natively.

Navigating the code

src
├── components
│   ├── app.vue - top-level component, controls the main application behavior using github-issues.js 
│   ├── hack-map.vue - the center panel with the map
│   ├── header-bar.vue - the header with the help and login buttons
│   └── side-bar.vue - the left sidebar that lists the projects
├── github-issues.js - main entry point for the application logic, handles polling.
├── github-api-client.js - configures the axios http library to talk with github
├── github-oauth.js - contains the oauth dance logic for github authentication
├── github-serialization.js - converts projects to github comments for storage, and vice versa
└── main.js - Vue.js bootstrapping code (e.g. vue.js initialization, router configuration)

test
└── unit tests

build
└── build scripts for webpack, from https://github.com/vuejs-templates/webpack

Testing Authentication

When authenticating with GitHub, GitHub will check the referring URL, and it must match exactly with the URL configured for the OAuth integration. The URL configured for hackmap is https://bkkhack.github.io/hackmap/ (note the trailing slash!). This means that you cannot test authentication on http://localhost:8080/hackmap/, the URL that the webpack dev server uses. This can be fixed in 2 steps: adding a hosts file entry and reverse proxying port 8080 to port 80:

Hosts file entry

Add a line in your hosts file (Linux and Mac OS: /etc/hosts; Windows: C:\Windows\System32\drivers\etc\hosts) to map 127.0.0.1 to bkkhack.github.io:

127.0.0.1       bkkhack.github.io

Reverse proxy set up

Windows

Use IIS to set up a reverse proxy with SSL offloading.

Mac OS / Debian / Ubuntu

Enable the nginx configuration included in the repository. It will proxy port 8080 to port 80, and use a self-signed cert.

For Debian or Ubuntu, you can simply enable the nginx configuration:

# debian / ubuntu instructions
> cd /etc/nginx/sites-enabled/
> sudo ln -s ~/path/to/hackmap/config/nginx-bkkhack-linux
> sudo service nginx reload

For Mac OS, if you installed nginx using homebrew, the default nginx config (/usr/local/etc/nginx/nginx.conf) sets up an empty website on port 8080, so you'll want to disable that so it doesn't conflict with the webpack dev server. You'll also need to generate your own OpenSSL certificate:

# mac os instructions
> sudo openssl genrsa -out /usr/local/etc/openssl/private/localhost-hackmap.key 2048
> sudo openssl req -new -x509 -key /usr/local/etc/openssl/private/localhost-hackmap.key -out /usr/local/etc/openssl/certs/localhost-hackmap.crt -days 3650 -subj /CN=bkkhack.github.io
> cd /usr/local/etc/nginx/servers/
> sudo ln -s ~/path/to/hackmap/config/nginx-bkkhack-macos
> sudo nginx -s reload || sudo nginx

Now, after starting the webpack development webserver, navigating to https://bkkhack.github.io/hackmap/ and accepting the self-signed cert, you should be able to access your code and test authentication.

Initial Deployment

  1. For GitHub authentication, create a GitHub app. You will receive a client id and a secret token.
    • The client id should be set in src/github-oauth.js
    • The secret token should be configured in the bkkhackmap heroku instance.
  2. Create a new GitHub issue tagged with "BKKHack Main Thread". This issue will be used as the back-end data store.
  3. Create a black and transparent SVG that represents the floor plan of the hack night venue. Upload it to the GitHub issue (i.e. paste it into the textarea) and refer to it in an html comment of the form <!-- floorplan: http://example.com/floorplan.svg -->.