Heimdall is Make Salt Lake's member management and access control system. It consists of a few different parts:
First, clone Heimdall:
git clone --recurse-submodules https://github.com/makesaltlake/heimdall.git
cd heimdallYou'll need a compatible Ruby version. rbenv is recommended, but plenty of other tools like RVM will work as well.
The easiest way to install rbenv is to use Homebrew. Follow the directions to install Homebrew if you don't have it already, then install rbenv:
brew install rbenvThen run:
rbenv initand follow the directions it prints out to set up rbenv to load whenever you open a shell. Close your current shell and reopen it to pick up the changes, then, inside your local clone of Heimdall, install Ruby:
rbenv installThere's a bug that sometimes causes rbenv to hang while waiting for the answer to a prompt that's never printed out. If you don't see any progress after a few minutes, type y and hit enter a few times, then wait a few more minutes.
Then install Bundler:
gem install bundlerIf you see a warning stating that you don't have write permissions for a directory under /Library/Ruby/Gems, you may need to restart your shell to pick up one of the shims rbenv created and then try to install bundler again.
(Node.js and Yarn are only needed if you're building the single-page application portion of Heimdall, which isn't actually used just yet. You can probably skip this section.)
TBD - Install NVM, then nvm install, then nvm use, then npm install -g yarn, then cd frontend && yarn
Heimdall uses Postgres as its database.
On Mac, the easiest way to install Postgres is via Postgres.app. Follow the instructions here to install it and create a new database server.
On Windows, download Postgres directly and install it, and create a database server if needed. (Yours Truly does not have a Windows machine handy, so you're on your own with this one.)
Redis is used to synchronize Action Cable state between Heimdall servers and job workers.
On Mac, the easiest way to install Redis is via Homebrew:
brew install redis
brew services start redisOn Windows, you'll want to download and install it directly.
By default, Heimdall will use database #5; if you're using that one for some other purpose, you'll want to export REDIS_URL=redis://localhost/6 to use e.g. database #6 before starting Heimdall.
Stripe setup is optional; if you're not working on Heimdall features that use Stripe, you can skip this section.
Make Salt Lake uses Stripe to process membership dues. Heimdall integrates with Stripe to automatically create users for new members and deactivate badge access when a user cancels their membership. (Feel free to submit a PR if you're looking to use Heimdall and would like it to support another payment processor.)
Head on over to https://dashboard.stripe.com/register, create yourself an account, then go to your dashboard, grab your test mode secret key, and set it into an environment variable named STRIPE_SECRET_KEY.
Heimdall supports Stripe webhooks to proactively update membership information the moment something changes in Stripe. If you're making changes to the webhook code, you'll also want to install the Stripe CLI and forward test webhook events to your local Heimdall instance. When Stripe prints out your webhook signing secret (which should remain constant across runs), you'll want to set it into an environment variable named STRIPE_WEBHOOK_SECRET.
Install Heimdall's Ruby dependencies using Bundler. You'll want to do this every time you git pull.
bundle installIf you get an error saying pg failed to compile/install, you may need to install postgresql to supply libpq-fe.h.
ImageMagick is required to transform uploaded user profile images into smaller variants that are rendered on the admin pages. On Mac, the easiest way to install it is via Homebrew:
brew install imagemagickFirst, create a database for Heimdall and populate it with the tables Heimdall needs:
bundle exec rake db:setupThis will also create a default admin user whose email is admin@example.com and whose password is password.
After you've done that once, on future git pulls you'll want to instead do:
bundle exec rake db:migrateto run migrations and update your database with anything that's changed without blowing it away and starting from scratch every time.
At this point you're ready to fire up Heimdall and log in.
Open three terminal windows. In the first, start Heimdall's web server:
bundle exec rails serverHeimdall will listen on port 3000 by default. If you want it to listen on a different port, add -p <port> to the end of your command line.
Then, in the second terminal window, start a background job worker:
bundle exec inst_jobs runThe third terminal window is only needed if you're building the single-page application portion of Heimdall; if you are, start the frontend development server in this terminal:
cd frontend && yarn startThen browse to http://localhost:3000, log in, and you're off to the races.
Whoops - we kinda skipped writing tests when building Heimdall. There are a few and we're always adding more - help us out and code some up!
To run what we've got, you'll need to install Chrome and ChromeDriver. On Mac, you can snag it with brew cask install chromedriver. (Note that every time you upgrade to a new Chrome major version, you'll need to upgrade ChromeDriver with brew cask upgrade chromedriver.)
Then run the tests:
bundle exec rspecWe've also got GitHub Actions set up to run tests on every push. You can view the latest test runs at https://github.com/makesaltlake/heimdall/actions.
Make Salt Lake's Heimdall instance is deployed on Heroku. More details to come, but if Alex gets hit by a bus in the mean time, ask someone with admin access to Make Salt Lake's Google organization to reset the password to Alex's email account, then use it to reset the password to the Heroku account under his email address and have at it. (Probably we should have the main account be owned by a mailing list or something and stick the password into a 1Password shared vault...)
Join Make Salt Lake's Slack team, then head over to #rfid-strikeforce if you'd like to get in touch.