The Blue Alliance
The Blue Alliance is a FIRST Robotics tool to help teams scout for, compete at, and relive competitions. You can see how the whole site works here, or even write code to make it better!
Help Build The Blue Alliance
Stay in Touch
- Mailing List Join thebluealliance-developers on groups.google.com to stay up to date with development.
- Slack Ask to join the-blue-alliance.slack.com to hang out in our chat channels.
- Facebook Join our group, #moardata @ The Blue Alliance, to submit video and match data we're missing on the site.
- Submit missing videos using the "Add Video" links on the site.
- Submit missing webcasts, team photos, etc using other links on the site.
- Fork this project!
- Make a branch to hold your changes.
- Make changes!
- Send over a pull request from your fork.
- We'll review it, and push your changes to the site!
If you're having trouble getting set up, reach out to us at our mailing list and we'll help you through it!
We have a beta development container setup that uses
docker. Install those two dependencies for your system (run
vagrant --version and ensure what you have is newer than 1.8.1), then run
vagrant up --provider=docker && vagrant rsync-auto to bootstrap the environment and kick off file syncing.
To debug, ssh into the container using
vagrant ssh and then run
tmux attach to see the GAE devserver logs (use
^B-D to detach from tmux).
- Learn a bit about Git and GitHub:
- Specifically use the Standard Environment Python SDK
- Windows/OS X: Run the installer and allow it make symbolic links (it might ask you to enter your root password)
- Linux: Unzip the .zip file and add the location of your
google_appenginedirectory to your
- Get the latest version of The Blue Alliance
- Fork TBA by clicking on "Fork" in the top right of its GitHub page
git clone https://github.com/USERNAME/the-blue-alliance.gitwhere USERNAME is your GitHub username, or use GitHub's Windows or OS X app to clone it to your computer
- For detailed instructions see the GitHub guide on contributing
- Install initial required Python packages
pip install -r requirements.txt
- Install Node.js which includes Node Package Manager
- Install UglifyJS by running
npm install uglify-es -gand UglifyCSS by running
npm install uglifycss -g
- Install gulp by running
npm rm --global gulp && npm install --global gulp-cli. This removes any version of
gulpthat was previously installed globally so it doesn't conflict with
gulp-cli. Gulp is used as the build tool for Gameday2.
- Install all node dependencies by running
npm install. This includes
less, which is used to build CSS files for production, as well as a number of packages used in Gameday2.
- Fill out
tba_keys.js. It's okay to leave a key blank if you're not doing any development that requires it, but the file
- Fill out
test_keys_template.jsonand save it in the same directory as
test_keys.json. These are used for unit testing on your local machine only.
- Run the app in GoogleAppEngineLauncher according to the directions below, and visit the local URL to see your own copy of The Blue Alliance!
Run a Local Dev Server
- Import the project into Google App Engine Launcher
- NOTE: If you have the Linux version, skip to step 2, as it does not come packaged with the App Engine Launcher. You will be manually adding the ports and modules as options when launching the server.
- Open App Engine Launcher
- File > Add Existing Application...
- Set the Application Path to your
- Set port 8088
- Add modules (dispatch.yaml, app.yaml, app-backend-tasks.yaml, and app-backend-tasks-b2.yaml) as extra flags https://cloud.google.com/appengine/docs/python/modules/#devserver.
- Run the app in App Engine Launcher and view its Logs window
- If you are using the Linux version, you can start the application by moving into your
the-blue-alliancedirectory and running
dev_appserver.py --port 8088 dispatch.yaml app.yaml app-backend-tasks.yaml app-backend-tasks-b2.yamlon the command line.
- Alternatively, run
- You should now have a basic development installation!
- Get some data into the local server
- NOTE: These steps are intended for local dev servers. They might also work on a deployed server if you edit
DEBUG = True.
- NOTE: The /admin/ page's buttons "Get FMS Teams" and the existing import /tasks are broken due to the move to FMSAPI datafeed. "Create Test Events" still works if you have teams in the database. Try visiting the urls /tasks/enqueue/csv_restore_events/YEAR (for a chosen year) or /tasks/enqueue/csv_restore_events.
- Visit, say, localhost:8088/tasks/get/usfirst_teams_tpids/2015?skip=0, localhost:8088/tasks/get/usfirst_teams_tpids/2015?skip=1000, ...
- Also visit localhost:8088/tasks/enqueue/usfirst_event_details/2015, 2014, ...
- Once you have events for a certain year, you can visit localhost:8088/tasks/enqueue/csv_restore_events/2015, 2014, ... etc. to get data from github.com/the-blue-alliance/the-blue-alliance-data instead of hitting up usfirst.org lots of times.
- If you want to test development using the offical FMS API, you can request API keys here. Once you have your keys, you can input them in the admin panel
- Ignore these warnings in the local dev server:
pytz is required to calculate future run times for cron jobs with timezones(The pytz library is in the source tree and works fine.)
Run an App Engine Server
See myTBA Configuration for how to create and configure an App Engine server.
You could edit the
app.yamlfile to change its
tbatv-dev-hrdto your app's Project ID, but then you'll have to remember to not check in that edit. Better yet, write a script like the following
mydeploy.shfile (that filename is in
#!/bin/sh appcfg.py --oauth2 --application=<MY_PROJECT_ID> update app.yaml app-backend-tasks.yaml appcfg.py --oauth2 --application=<MY_PROJECT_ID> update_dispatch .
Note that it needs your application's "Project ID", not its "Project name".
appcfg.pysaves repeating the login steps each time. If you skip it or deploy via the App Engine Launcher, you'll have to enter your name and password each time. If you use 2-Step Verification for your Google account (you should!), that means generating an App password each time.
cron.yamlfile in master will create cron jobs that use up daily free AE Datastore quotas.
- To avoid that in a dev server, checkout a no-op version of cron.yaml.
- If it's already happening in a dev server, deploy a no-op
appcfg.py update_cron, then delete the tasks in the
- If you try to deploy a server while it's over Datastore quota, appcfg will say "there was an error updating your indexes. Please retry later with appcfg.py update_indexes." The fix is to wait until the next day's quota then use
When you set sitevars, the server automatically internalizes them.
You don't need a sitevar for
firebase.secretseven though that's the placeholder text for a new sitevar name.
Ignore these deployment warnings:
Cannot upload both <filename>.py and <filename>.pyc
Could not guess mimetype for static/ovp/<filename>.xap. Using application/octet-stream.
WARNING old_run.py:88 This function, oauth2client.tools.run(), and the use of the gflags library are deprecated and will be removed in a future version of the library.
Ignore these warnings in a deployed server's logs:
Exception: Missing sitevar: firebase.secrets. Can't write to Firebase(It just means that no push notifications to GameDay will be sent, which is OK for a dev server.)
Paver is an easy way automate repetitive tasks. For The Blue Alliance, these tasks are stored in pavement.py. To install paver, use one of the methods below:
- Download and install paver from http://pypi.python.org/pypi/Paver/
Paver commands include:
paver less-- translate LESS files to CSS and combine with other CSS files
paver test_fast-- run tests that don't require HTTP
CSS Icon Sprites
Icons get combined into single files called sprites to reduce the number of HTTP requests needed to render a page. To simplify development, we add icons normally (not to the sprite), and every so often we will combine them all into a sprite and fix all necessary CSS.
Potentially useful: http://spriteme.org/
Testing is implemented using a combination of unittest2 and the Google App Engine testbed framework. Test coverage is a work in progress, and focuses on maintaining datafeed integrity in the face of optimizations and changes to FIRST's data formats.
To run the tests, or just the offline (fast) tests: