Orientation to Azure VM¶
Last Updated: November 2021
This tutorial provides an orientation to the Tethys Azure virtual machine (VM). It includes instructions for connecting to the VM, user accounts to use, descriptions of what is installed, and important directories and files.
Connect with SSH¶
To connect to the Azure virtual machine via SSH, do the following:
Navigate to the overview page for the virtual machine resource.
If the virtual machine is not running, press the Start button.
Click on Connect from the tools at the top of the page and select SSH.
Follow the instructions to connect to the virtual machine via SSH.
Tethys User Account¶
The Tethys Portal image for Azure includes a
tethys user account for maintenance of the Tethys installation. You should always be logged in to this account to run any
tethys commands or install apps.
Change Tethys User Password¶
Before switching to the
tethys user account, you should change the password using the following command:
sudo passwd tethys
Switch to Tethys User¶
To switch to the Tethys user from another account, use the
su command (switch user):
su - tethys
Enter the password for the
tethys user when prompted.
Don't forget the dash (
To exit the
tethys user and return to your login user, run the
Activate Conda Environment¶
Before running any
tethys command in this or other tutorials, you'll need to activate the
tethys Conda environment. After logging in as the
tethys user, you'll notice that the
base environment for Conda is automatically activated. Activate the
tethys environment as normal:
conda activate tethys
Now you can run
Tethys Home is the directory where the
portal_config.yaml is located. Use the
TETHYS_HOME environment variable to locate the Tethys Home directory:
You can also use
TETHYS_HOME to change into the directory:
List the contents of the TETHYS_HOME directory:
ls -l $TETHYS_HOME
Here's a brief explanation of the important items in the Tethys Home directory:
apps: Directory for storing app source code.
config: Directory with configuration files used by the production installation.
data: Directory for storing data for GeoServer, THREDDS, etc.
miniconda3: Conda installation containing the
portal_config.yml: The primary configuration file for the Tethys Portal.
static: Location where static files are collected and served by NGINX.
workspaces: Location where workspaces for apps will be collected.
Tethys Portal is configured to use a system-installed PostgreSQL database with the PostGIS extension installed.
To connect to the database using
psql, run the
su command, but this time specifying the
postgres user and a command to run with the
sudo su - postgres -c psql
psql, run the following query to get the version of the PostgreSQL database:
Run the following query in
psql to get the version of PostGIS installed:
SELECT * FROM pg_available_extensions WHERE pg_available_extensions.name LIKE 'postgis';
Run the following in
psql to get a list of the database users:
The passwords of the database users should be changed from their default values. See Configure Azure VM tutorial for how to do this.
Run the following in
psql to get a list of the databases:
Docker is installed on the image but not running by default. This is to make it easy for you to install the services your apps need such as a THREDDS or GeoServer. The Configure Azure VM tutorial describes the additional configuration that should be performed before using Docker.
In a production installation, you will need to examine logs to see errors when they occur. All logs for running processes on the server are located in the /var/log directory. Here's a list of the logs that are most helpful to use when debugging Tethys problems:
The Daphne logs capture all of the logged information from Tethys Platform:
The NGINX logs are helpful to review when you get 502 errors or when you are debugging connection issues:
The PostgreSQL logs can be helpful when you encounter database errors, though these are rare for most Tethys applications:
Start, Stop, Restart¶
The Daphne, NGINX, and PostgreSQL services are all managed using the
systemctl command. You'll need to restart any of these services any time you make changes to the configuration. Use the following commands to start/stop/restart these services.
sudo systemctl status tethys.service
sudo systemctl start tethys.service
sudo systemctl stop tethys.service
sudo systemctl restart tethys.service
sudo systemctl status nginx.service
sudo systemctl start nginx.service
sudo systemctl stop nginx.service
sudo systemctl restart nginx.service
sudo systemctl status firstname.lastname@example.org
sudo systemctl start email@example.com
sudo systemctl stop firstname.lastname@example.org
sudo systemctl restart email@example.com
Now that you know how to connect to the VM and have a basic understanding of what is installed, you are ready to configure and customize the Tethys Portal. Don't skip out on this important next step!