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 Docker, Docker-compose, and Bundler to provide consistent performance between machines during development. Bundler is handled on the docker container we set up, but this requires you to download the latest version of Docker and Docker-compose on your machine (Windows, Mac, or Linux).

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

Docker Compose: https://docs.docker.com/compose/install/

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
rm -rf .git/modules/hackathon-config
git submodule sync
git submodule update --init --recursive --remote

Double check that Git has updated the configuration repo properly by seeing whether any of the files in the hackathon-config folder were updated with those from the yourhackathon-config repo. If it still shows up as redpandahacks, try this to bypass the flawed behavior of the git submodule update command above:

• rm -rf hackathon-config
• git clone https://github.com/your-username/yourhackathon-config hackathon-config

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 use Docker-compose to maintain the use of our containers.

Running docker-compose build then docker-compose up

should install all of the dependencies on a docker image and then runs 2 containers, one for postgres and another for rails.

Getting into the shell of the docker container once you've ran these commands is simple when running our provided helper method,

bash docker_shell.sh

This will get you access to the console of the container even if the ruby container is shut down.

Note: The database is filled in with dummy data and a fake admin account is auto-created whenever a database file isn't found. Any changes to this and the docker container can be found in the docker folder

Accessing the server

You should be all set to develop!

The rails server is set to run on localhost:3000, going to this page on a browser will allow you to test some of the features listed in this wiki.

Some Dummy data has already been added to the app, with the admin account being:

Email: [email protected] Password: testpass

Congratulations! You now have a functional local version of Dashboard. From here, you can do the following things:

• Head over to the Feature Overview to get started testing the code
• Deploy your local version of dashboard to a hosting service: Deployment

Debugging

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 while logged out of the admin account (or open a new Incognito windows) 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.

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

• If you encounter the following error: rm: cannot remove 'tmp/pids/server.pid'$'\r': No such file or directory
  • If you're a Windows user, it means that End of Line Sequence in docker\docker_set_up.sh is in CRLF. You need to change it to LF
• 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!