Getting Started

This page is going to be long. It's split up into multiple sections. Some of which are for users, some for developers, and some for both. Please try to bear with us as you're going through the instructions. We promise it's not as overwhelming as it seems!

Dependencies

We use both Docker and Bundler to provide consistent performance between machines during development, however you will only need to download Docker. (Bundler and all other Rails dependencies are installed inside the Docker container.) Start by downloading the latest version of Docker on your machine (Windows, Mac, or Linux).

Docker Desktop: https://www.docker.com/products/docker-desktop

If you are using Windows and do not have Windows 10 Pro, please instead use Docker Toolbox: https://docs.docker.com/toolbox/toolbox_install_windows/

The next section is different for users and developers. Please follow the correct instructions!!!

[Users] Downloading the dashboard repo

First we are going to ask that you please clone the main dashboard repository. You can do that by running git clone https://github.com/fuseumass/dashboard.git

Next please create a fork of the redpandahacks-config repository. You can do this by clicking the "fork" button at the top right hand corner of this page.

Open the .gitmodules file from the Dashboard repo that you've cloned. It should look something like this:

[submodule "hackathon-config"]
    path = hackathon-config
    url = https://github.com/fuseumass/redpandahacks-config

Inside this file, please replace the url with your url to the forked config repo. It should look something like this https://github.com/your-username/yourhackathon-config. Save this file.

Next, you should look in your .git/config file for the checked-out Dashboard repo. If the file contains this...

[submodule "hackathon-config"]
        active = true
        url = https://github.com/fuseumass/redpandahacks-config

...then you should update this URL as well.

Now you'll want to open a terminal and navigate to the folder containing the dashboard folder. Here, you'll want to run the following commands:

rm -rf hackathon-config
git submodule sync
git submodule update --init --recursive --remote

Now the hackathon-config folder is a submodule that tracks the github repository you created for your fork. Once you've got the repo downloaded and you have verified that the hackathon-config folder contains files. Please proceed to building and running the docker container.

[Developers] Downloading the dashboard repo

In order to allow for custom configuration, Dashboard uses git submodules. In order to properly install these, head to your terminal and cd into the directory that you wish to download the project to. Then clone the repo by typing:

git clone --recursive https://github.com/fuseumass/dashboard.git && git submodule update --init --remote

This will initialize the submodule for configuration, which by default is https://github.com/fuseumass/redpandahacks-config. It's very important that if you are developing new feature for dashboard that you use the redpandahacks configuration repository. This will ensure that when you make a pull request you aren't inadvertently changing the default configuration repository.

Once you've got the repo downloaded and you have verified that the hackathon-config folder contains files. Please proceed to building and running the docker container.

Building and running the docker container

For local testing and development, we have written tooling around Docker to make this simple. We provide these helper shell/bash scripts:

./docker_build.sh or ./docker_build.bat will build the Docker container. You only need to do this once, or whenever dependencies are changed in the repository.

./docker_run.sh or ./docker_run.bat will start the already-built Docker container. This will start the rails webserver.

./docker_shell.sh or ./docker_shell.bat will open a bash shell in an already-running Docker container, or will start one with the bash shell if it's not running. This is useful for debugging or doing things like a database migrate and running rake tasks.

should install all of the dependencies on a docker image and then runs a rails server on a container based off that image with the db configurations done.

Note: The database is filled in with dummy data and a fake admin account is auto-created whenever a database file isn't found. This behavior can be changed in the ./docker_set_up.sh file.

Running the server

Once you've built the docker container with docker_build and started it with docker_run, you can go to http://localhost:3000/ in your browser view the login screen.

One of a few things which might have happened if this doesn't immediately work:

• You might need to perform a database migration. ./docker_shell.sh rails db:migrate
• You might need to sync the feature flags. ./docker_shell.sh rails feature_flags:feature_flags
• You might need to re-run the database setup script. ./docker_shell.sh ./docker_set_up.sh
  • You can also try deleting the development database with rm -rf db/development.sqlite3 and then run this script again.
• You might not have configured your git submodule correctly, or the git submodule might need to be pulled.
  • First, check whether there are any files inside the hackathon-config folder. If it's empty, then run git submodule update --init --recursive
  • Second, cd hackathon-config and run git pull origin master to sync to the latest changes in the configuration repo.
• If you've already tried these three fixes to no avail, then collect your Rails application logs in the console and web browser error message(s), Google them, and if that fails then reach out to us and we will be happy to debug!

Now you can login as an admin with these automatically generated credentials:
Email: [email protected]
Password: testpass

Dashboard uses a concept known as feature flags to enable/disable functionality. This allows you to, for example, hide the hardware checkout or mentorship components before the day of the event from participants. Here is the current list of feature flags (all default to disabled):

• Mentorship Requests
• Hardware Requests
• Projects
• Check-Ins
• Prizes
• Schedules
• Applications

Once you're logged in, make sure to go to the admin tab and enable whichever features you want to test. If you're just starting out with testing Dashboard, then you probably want to enable the Event Applications feature flag so you can create a participant account and apply!

Since the admin-facing interface is not reflective of the interface which participants and mentors see, you should next register as a participant. Go to http://localhost:3000 again while logged out of the admin account and hit Register. You should be automatically logged in after you create an account, and if event applications are enabled then you can begin from there.