Deployment Guide

This guide is intended for new teams that would like to start using the StrangeScout system for scouting at FRC events. This is free software without warranty or support, but you're more than welcome to email [email protected] with any questions and we will help you if possible.

Requirements

• A server that meets the following requirements:
  • Runs a 64-bit Linux operating system. We use Ubuntu Server 18.04 LTS in production, hosted on Amazon AWS EC2 on a t2.small or t2.micro instance. You can get your first year of the later free when you sign up for an AWS account. You must have an account that can sudo to root; if you got the server from a commercial provider like AWS, GCP, Azure, etc. this won't be an issue.
  • Has Docker CE and Docker Compose installed and updated from the official repositories (instructions linked). We use the latest stable versions of each in production.
  • Has a static, public IP address and has ports HTTP (80), HTTPS (443), and MySQL (defaults to 3306 but can be changed as shown below) open in the firewall. If you are running in the cloud, do not block SSH (22) or you will lose access to the console. The default EC2 Ubuntu image is configured appropriately, although you may wish to lock it down some from the default. For higher security, you could restrict SSH and MySQL ports to only be available over a VPN, but this isn't needed if you use secure passwords. You cannot use a computer in your buildspace unless you pay your ISP for a static, public IP address and have your router configured to forward the aforementioned ports to that computer--for most teams, it makes sense to use a commercial cloud computing provider such as AWS, GCP, or Azure.
• A domain name or subdomain of a domain you control (ex. strangescout.team0001.org), with an A record configured with your DNS provider (we use AWS Route 53, but the free DNS hosting that comes with most domains is fine) to point to your server's public IP address (take care not to use the private address when setting this up, or it will not work). This domain will be used to access your server for scouting and administration.
• Client devices to scout with (laptops, phones, tablets, etc.) that can run a web browser (any browser from the past few years should work, although we only test with latest Chrome, Firefox, and Safari) and will have internet access (WiFi, wired, or LTE mobile data) throughout the duration of their use at the event. All data collection occurs in the browser, so Android, iOS, Windows, macOS, Chrome OS, and Linux devices are all supported. To view the data, you can use the built-in data viewing page to view a specific selection of data both as a table in the web page, or as a downloadable CSV spreadsheet file. You may also use one of the many programs that can connect to a MySQL/MariaDB server and import data. We like Tableau, which is free for students and FRC teams!

Deploying the server

1. Connect to your server over SSH. For new AWS EC2 users, this guide walks you through the process of creating the virtual machine and connecting to it with SSH. Be sure that you do not lose the SSH key or you will have to start over with a new server.
2. Clone this repository and enter it
3. Checkout your preferred branch
   • prod for a stable and production ready system (recommended)
   • master for a more recent system that may or may not have a few bugs or newer features
4. Choose your preferred method
   • For standalone deployment, do ln -s docker-compose.standalone.yml docker-compose.yml
   • If you want to use Traefik for a reverse proxy, do ln -s docker-compose.traefik.yml docker-compose.yml
5. Create your .env file with the following vars:

   	JSCOUT_DOMAIN=<your_domain.tld> # set the domain you're hosting your scouting service on
   	STRANGESCOUT_SQL_PASSWD=<secret_password1533> # password to access the MySQL database
   	GOSCOUT_EVENT_HARDCODE=<event_currently_scouting> # what event you're currently scouting
   

   • Optional vars:

   	MYSQL_PUBLIC_PORT=<1533> # set if you'd like to use a SQL port other than the default of 3306
   	PREFIX=<dev> # set if you'd like to set a prefix for the docker images (defaults to prod if not set)
   

   • If you're using traefik, you must also set the TRAEFIK_NETWORK var
   • If you're using a standalone install, you must also set the JSCOUT_LETS_ENCRYPT_EMAIL var
     • This specifies the email used to get Lets Encrypt certificates for HTTPS support
6. Run ./build.sh
7. Do docker-compose up -d