Hackathon

A hackathon web application with a comprehensive administrative backend, email infrastructure, attendee registration, and optional MLH integration.

Deployment

Platform

Heroku

Automatic

Click on the following button to deploy the web application to Heroku:

Manual

Perform the following steps:

1. Sign up for an account at Heroku and install the Heroku CLI if you have not already done so.
2. Clone the repository and change your current working directory to the newly created hackathon directory:
   • SSH (use if you have configured an SSH key with GitHub):

     $ git clone git@github.com:TomerAberbach/hackathon.git
     $ cd hackathon

   • HTTPS:

     $ git clone https://github.com/TomerAberbach/hackathon.git
     $ cd hackathon

3. Log in to Heroku through the Heroku CLI:

   $ heroku login

4. Create a Heroku application:
   • SSH (use if you have configured an SSH key with Heroku):

     $ heroku create --ssh-git

   • HTTPS:

     $ heroku create --ssh-git

5. Configure the application's buildpacks (Active Storage preview and Ruby):

   $ heroku buildpacks:add -i 1 https://github.com/heroku/heroku-buildpack-activestorage-preview
   $ heroku buildpacks:add -i 2 heroku/ruby

6. Configure the application's Heroku addons (SendGrid and Cloudinary):

   $ heroku addons:create sendgrid
   $ heroku addons:create cloudinary

   The previous commands set the SENDGRID_USERNAME, SENDGRID_PASSWORD, and CLOUDINARY_URL environment variables for you on Heroku.
7. Set the application's ADMIN_EMAIL and DOMAIN. Refer to the Environment Variables section for a description of each environment variable:

   $ heroku config:set ADMIN_EMAIL=youradmin@email.com
   $ heroku config:set DOMAIN=yourdomain.com

   You may choose to set the DOMAIN environment variable to Heroku's randomly generated hostname initially, and then update it upon securing and configuring a custom domain name with Heroku.
8. Run the following command and verify that each environment variable in the Environment Variables section is included in the output:

   $ heroku config

9. Determine the current Git branch using by running git branch and then deploy the application to Heroku:

   $ git push heroku current_branch_name:master

10. Migrate and seed the application's database:

    $ heroku run rails db:migrate db:seed

    At this point the email address set in the ADMIN_EMAIL environment variable should have received an invitation email, but the link in the email will not work until the next step is completed.
11. Scale the application to use a single dyno, a lightweight Linux container:

    $ heroku ps:scale web=1

You can now view the application home page by running heroku open or navigating to its URL in a web browser. Additionally, the link in the invitation email sent to the email address set in the ADMIN_EMAIL environment variable should now be used to create the super admin account. Lastly, the application dashboard is accessible at the /dashboard path. For example, if your DOMAIN environment variable is set to hacktcnj.com, then the application dashboard can be found at hacktcnj.com/dashboard.

Appendix

In general, you can run any command on your Heroku dyno using heroku run <your-command>. To start a remote interactive shell session on your heroku dyno run the following command (press Ctrl+C to stop viewing the logs):

$ heroku run bash

If you need to clear the application's database run the following command, which is irreversible:

$ heroku run DISABLE_DATABASE_ENVIRONMENT_CHECK=1 rails db:schema:load

You will probably want to reseed the database afterwards:

$ heroku run rails db:seed

If view your application's logs in realtime run the following command (press Ctrl+C to stop viewing the logs):

$ heroku logs --tail

Environment Variables

Sign up for an account at SendGrid and set the SENDGRID_USERNAME and SENDGRID_PASSWORD environment variables. The website requires SendGrid to send emails.

Set the ADMIN_EMAIL environment variable to an email address. The email address will receive a super admin account invitation email when the website's database is initially populated. The super admin can then invite additional admins if necessary.

Set the DOMAIN environment variable to the domain name, without a protocol prefix or path suffix, that targets the website. For example, hacktcnj.com is a valid value.

In the development and test environments, Active Storage, which is responsible for storing images and documents, is configured to use the local file system. However, in the production environment, Active Storage is configured to use Cloudinary, a cloud storage provider, because many website hosting providers provide an ephemeral file system, which cannot persist data. Sign up for an account at Cloudinary set the CLOUDINARY_URL environment variable in the production environment.

Development

1. Install Ruby and Rails and PostgreSQL.
2. Clone the repository and change your current working directory to the newly created hackathon directory:
   • SSH (use if you have configured an SSH key with GitHub):

     $ git clone git@github.com:TomerAberbach/hackathon.git
     $ cd hackathon

   • HTTPS:

     $ git clone https://github.com/TomerAberbach/hackathon.git
     $ cd hackathon

3. Set the environment variables listed in the Environment Variables section by creating an application.yml file in the config directory and setting the appropriate environment variable values like so:

   SENDGRID_USERNAME: "your SendGrid username"
   SENDGRID_Password: "your SendGrid password"
   ADMIN_EMAIL: "your email address"
   DOMAIN: "localhost:3000"

   DO NOT CHECK THIS FILE INTO VERSION CONTROL.
4. Install the project dependencies:

   $ bundle install

   If you encounter errors, try restarting PostgreSQL and installing additional updates.
5. Set up the database:

   $ rails db:setup

6. Run the application (visit at [localhost:3000]):

   $ rails server

   Modify code and refresh web pages to see the difference.

Resources

• Getting Started with Rails

Models

• What is ActiveRecord?
• Model Querying
• Model Validation
• Model Callbacks
• Migrations
• Model Associations

Controllers

• What is a Controller?
• Routing

Views

• Layouts and Rendering
• Forms

Other

• File Storage
• Sending Emails

Contributing

See CONTRIBUTING.md for contributing guidelines.

License

Copyright © 2019 Tomer Aberbach and Thomas Orth Released under the MIT license.