Running CHORDS

CHORDS is packaged as a collection of Docker containers, which can be run on a Linux, MacOS or Windows system. Configuration and control of these containers are performed by running a python management script. The script shares the directory containing CHORDS configuration files. python chords_control --help explains the script options.

Note: On systems where docker requires root, you may need to use sudo to run these commands.

Requirements:

• python 2.7 (Linux and MacOS have this by default; install on Windows). If you prefer python 3, but have python 2 as well, you can alter the 'python' commands below to 'python2'.
• curl (Linux and MacOS have this by default; install on Windows)
• A running docker system
  • OSX: Docker for Mac is fantastic on the Mac.
  • W10 Pro: Docker for Windows
  • W7: For us hapless Windows 7 users, we have to use the less elegant Docker Toolbox.
  • Linux: See instructions for various flavors of this OS. It's quite likely that Docker is already available on your system.
  • Raspberry Pi: See the easy to follow instructions for bringing up a Docker enabled Raspberry Pi.
• Port 25 must be open. Port 3000 must be open for the Grafana visualization, but you can use CHORDs without this feature. In most systems these ports seem to be open.

Installation:

# Select the configuration directory
cd <configuration directory>

# Fetch the CHORDS management script
curl -O  https://raw.githubusercontent.com/NCAR/chords/master/chords_control

# Create configuration files (chords.yml and .env will be created)
# (Be prepared to enter an admin password of your choosing.)
python chords_control --config

# Update the CHORDS software
python chords_control --update

Running:

python chords_control --run

Verifying:

• Point your browser at the CHORDS portal by entering the IP address of the system into the address bar. This may be localhost if CHORDS is on the same machine as your browser. On W7 machines, get the IP from the output of: docker-machine ip
• It can take quite a while for the initial page load to finish, as the server initializes its caches. A Raspberry Pi can take up to a couple of minutes.
• Sign in with [email protected] (realtimedata). Immediately change this admin account password (under Users). You will probably also want to uncheck "Restrict viewing of data" (under Configure).

Shutting down:

python chords_control --stop  

• The CHORDS database will persist and be used the next time you run the CHORDS containers.

Updating:

curl -O  https://raw.githubusercontent.com/NCAR/chords/master/chords_control
python chords_control --config  # only if you need to choose a different CHORDS release
python chords_control --update
python chords_control --stop
python chords_control --run

Monitoring:

• You can watch the log for the chords application. It's not critical, but can be useful for diagnosing problems, and for monitoring the tedious startup procedure, which takes several minutes on the Raspberry Pi:

docker logs -f chords_app

Visualization

Hit the Visualization button to open a tab pointing to the builtin Grafana server.

Login with admin/admin to begin configuring Grafana (login on the Raspbery Pi is admin/changeme). You will want to change this password.

The Getting Started Guide is a good place to begin learning about Grafana. Data Source parameters are:

Parameter	Value
Name	CHORDS
Type	InfluxDB
URL	http://localhost:8086
Access	direct
Database	chords_ts_production
User	guest:guest

Tips

• You reconfigure the portal using python chords_control --config. Backup copies of the configuration files are created in case you need to go back. Once you have set the CHORDS admin password and the secret key base, you should not change them. Otherwise, the Rails application will not be able to access the CHORDS databases.

• If you sleep the machine that is running docker, the docker engine time can be wrong when the machine resumes, and so the container times will be wrong. The observable symptom is that the dashboard will not display correctly, since the data queries are made relative to the current system time. The only fix is to restart the docker engine. The clock sync problem is mentioned on the forums, with the claim that they are working on the issue.

• Note:: If you find that localhost is not responding, try bringing CHORDS down and back up.

More Information

• More CHORDS Docker tips are available on the project wiki.
• The CHORDS docker images are served from Docker Hub repository.