pyCast is the newest version of ShakeCast with a backend written in Python and a robust Angular frontend. Although there are new features in the web application, pyCast is generally lighter weight and new users should find that it’s relatively easy to install. Existing ShakeCast users will find that pyCast has a powerful interface for downloading and running scenarios as well as notification customization.
Windows Installation
The newest ShakeCast windows installer is available here.
Run the Windows installer as an administrator. Python will automatically be installed before the ShakeCast and you may see some command windows open and close; that’s okay, this is just the application initializing! In order to determine if ShakeCast was installed correctly, use your web browser to navigate to your localhost. You can login using the default administrator account by entering “scadmin” for both the username and password.
Your application is ready to go! Checkout Inventory Setup below to learn how to prepare your inventory and configure ShakeCast.
Linux Installation
There are multiple ways to install pyCast on Linux, but we recommend you use the PyPI package. Installation requires python 3.6 or higher and root access.
sudo yum install epel-release python3 python3-pip
sudo pip3 install usgs-shakecast
sudo python3 -m shakecast.app.startup
sudo python3 -m shakecast start &
Contributor Installation (GitHub)
Contributors may want to install pyCast directly from GitHub to have the most updated code.
Download from GitHub:
git clone https://github.com/usgs/shakecast.git
Install the required Python libraries and start ShakeCast. Installating within a virtual environemnt is preferred.
cd shakecast
pip3 install -r requirements.txt
sudo python3 -m shakecast.app.startup
sudo python3 -m shakecast start &
Docker Installation
Docker is our preferred method of installation ShakeCast for our internal instances. We find it to be very stable and easy to update and are leaning on containerization more and more. It’s our hope more customers will adopt this method of running ShakeCast.
git clone https://github.com/usgs/shakecast.git
cd shakecast
git fetch origin --tags
git checkout $(git describe --tags)
docker-compose up
After Installation…
In order to determine if ShakeCast has installed correctly, use your web browser to navigate to your localhost. If you did not install ShakeCast on your local machine, you’ll navigate to the address of the server you used instead of your localhost. You can login using the default administrator account by entering “scadmin” for both the username and password.
Inventory Setup
Download an Inventory Workbook here and create your initial inventory. Your ShakeCast inventory is made up of facilities, notification groups, and users. You can store all of this invormation in the ShakeCast Inventory Workbook to ensure your data is compatable with ShakeCast (including future versions). Once your information is input, you can export the data as XML files, which are easily read by ShakeCast.
Learn more about the ShakeCast Inventory Workbook here
Upload to ShakeCast
Drag and drop the XML files exported by the inventory workbook onto any page in the admin application. Once the file is over the web interface, the upload screen will appear.
Setup a SMTP Server
ShakeCast must be able to access an SMTP server in order to send email notifications. This can be done using your own SMTP server, GMail, Outlook, and many others. To configure your SMTP server, navigate to Settings after entering the admin application.
System Test
You can run a system test from the Settings tab in the admin app. This will check that ShakeCast is able to access its database, the web, and your configured SMTP server. If your instance is configured correctly, the test will take a minute or two to run.
Scenario Run
Running a scenario is a good way to test that your ShakeCast instance and inventory are configured properly. Navigate to the Scenario tab in the admin app. From here, you can click “Download More from the Web” to download a scenario. This will show a panel on the lefthand side of the screen that you can use to search for a scenario. You can choose between a real event (earthquake data recorded by actual shaking) or a scenario (earthquake data generated by scientists for testing purposes).
Enter the rest of your search criteria and hit search. This will produce a list of scenarios that match your criteria. You can select any of these scenarios by clicking on them; then to download the data, click “Download Selected”.
Notification Customization
Navigate to the “Notifications” tab in the admin app and you should see what looks like a ShakeCast notification as well as some customization options. These options allow you to change the look and feel of the notification and the best way to learn how to use this part of the application is to play with the options; your changes will be reflected in the notification, but will not be stored until you click Save.
Clicking “New Event” or “Facilities” will switch between the type of notification you’re configuring. Every template has configurations for New Event emails as well as Facility emails that are sent when there is a potential impact to one of your structures.
If you wish to have your own companie’s logo in the notification instead of the ShakeCast logo, drag and drop the image you wish to use onto the Settings page, and the upload screen will appear.
Using the Dashboard
Now that your ShakeCast instance is configured, you’re ready to sit back and wait for the earthquake data to roll in. The Dashboard (and the landing page for pyCast) provides the interface to this data. You can use it to search for older events or let it run on the extra monitor at your work station; the earthquake feed will update automatically.
Stopping and Removing pyCast
Windows
Navigate to the Shakecast folder in your user directory and run the uninstaller.
If you just wish to stop shakecast, you can treat it like any other Windows service. Open a cmd window as an administrator and you can run:
net stop sc_server
net stop sc_web_server
and then to start it again:
net start sc_server
net start sc_web_server
You will find an uninstaller for pyCast in it’s installation directory (C:\Users\Username\shakecast). Run this as an administrator to fully remove pyCast.
Linux
To stop ShakeCast:
sudo python3 -m shakecast stop
Then to uninstall it:
pip3 uninstall usgs-shakecast
Admin Changes in V4
Although V4 has an entirely new codebase, the administration process remains the same. One detail, which you can take advantage of, or simply ignore, is a user’s ability to change their own password and email once logged into the user interface. This is an effort to protect our users’ passwords from being stored in plain text in the ShakeCast Inventory Workbook; instead, a default password can be used during configuration, then changed later through the web.
HAZUS AEBM
Using the newly developed HAZUS Advanced Engineering Building Module, ShakeCast V4 can determine potential impact by analyzing multiple spectral accelerations. This provides a much clearer picture of earthquake shaking and allows us to make more precise impact estimates than ever before. Checkout our AEBM Implementation for a more detailed explanation of this new strategy.
MySQL Database Connection
MySQL connection is a built-in feature in ShakeCast V4 and organizations with many facilities (40,000 or more) will find that this upgrade is actually necessary. There are many ways to run a MySQL database, but the simplest is to install the database on the same server on which ShakeCast is running. The following is an example shows how to do this with the open source replica of MySQL, Mariadb, on CentOS.
sudo yum install mariadb-server
sudo pip3 install install pymysql
You can adjust this methodology for any flavor of Linux you might have installed ShakeCast on. Once these packages are installed, you can create a new MySQL user ():
mysql -u root -p
GRANT ALL PRIVILEGES ON *.* TO 'sc'@'localhost' IDENTIFIED BY 'P@s$w0rd123!';
\q
The username of your new user is “sc” and the password is “P@s$w0rd123!” if you simply copied and pasted the command above. However, you should customize your username and password. Next, log back into MySQL with the user you just created and create a new database:
mysql -u sc -p
CREATE DATABASE pycast;
\q
The last step is to tell ShakeCast to use the new database we just created. You can do this easily using environment variables:
export SHAKECAST_DB_CONNECTION_TYPE=mysql
export SHAKECAST_DB_CONNECTION_STRING=mysql+pymysql://sc:P@s$w0rd123!@localhost:3306/pycast
and then running ShakeCast you may need to forward the environment to sudo using the -E flag
sudo -E python3 -m shakecast start
Your database is not ready to go! Head to your ShakeCast web interface and go to the Settings page. Select “MySQL” from the dropdown database options and enter the username and password you input into MySQL. Save those configurations and restart ShakeCast. Confirm your new configurations work by heading back to the Settings page and clicking “Run System Test.”
Implementing HTTPS for ShakeCast
ShakeCast V4 utilizes an extremely lightweight web server that doesn’t natively support SSL access. If you are running ShakeCast outside of your organizations network, it is probably important for you to use SSL to access ShakeCast. This is still acheivable by installing a full-featured web server in front of ShakeCast and port forwarding to ShakeCast’s web port. Start by actually changing ShakeCast’s web port from the web interface’s Settings page. Now you can install a web server and allow it to listen on ports 80 and 443. The following is an example NGINX configuration file that redirects web access to SSL and forward those SSL requests to ShakeCast’s web port:
server {
# Listen on port 80, but rewrite the url using https
listen 80 default_server;
server_name _;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
# You will have to get and install your own SSL certificates
ssl_certificate /etc/nginx/certs/cert.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;
location / {
proxy_pass http://localhost:SHAKECAST_WEB_PORT/;
proxy_redirect off;
}
}
where SHAKECAST_WEB_PORT is the port you have re-assigned ShakeCast through the Settings page.