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:

  1. Navigate to the overview page for the virtual machine resource.

  2. If the virtual machine is not running, press the Start button.

  3. Click on Connect from the tools at the top of the page and select SSH.

  4. Follow the instructions to connect to the virtual machine via SSH.

Example connect SSH instructions
Figure 1. Example connect SSH instructions.

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:

default
sudo passwd tethys

Tip

Consider using a password generator to help you create strong passwords. For example, the xkpasswd generator is a tool based on an xkcd cartoon for creating secure passwords that are memorable.

Switch to Tethys User

To switch to the Tethys user from another account, use the su command (switch user):

default
su - tethys

Enter the password for the tethys user when prompted.

Important

Don't forget the dash (-)!

To exit the tethys user and return to your login user, run the exit command:

default
exit

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:

default
conda activate tethys

Now you can run tethys commands:

default
tethys version

Tethys Home

Tethys Home is the directory where the portal_config.yaml is located. Use the TETHYS_HOME environment variable to locate the Tethys Home directory:

default
echo $TETHYS_HOME

You can also use TETHYS_HOME to change into the directory:

default
cd $TETHYS_HOME

Contents

List the contents of the TETHYS_HOME directory:

default
ls -l $TETHYS_HOME
Contents of Tethys Home directory as given by ls command
Figure 2. Contents of Tethys Home directory as given by ls command.

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 tethys Conda environment.

  • 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.

Database

Tethys Portal is configured to use a system-installed PostgreSQL database with the PostGIS extension installed.

psql

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 -c option:

default
sudo su - postgres -c psql

Version

Using psql, run the following query to get the version of the PostgreSQL database:

default
SELECT version();

Run the following query in psql to get the version of PostGIS installed:

default
SELECT * FROM pg_available_extensions WHERE pg_available_extensions.name LIKE 'postgis';

Database Users

Run the following in psql to get a list of the database users:

default
\du

Important

The passwords of the database users should be changed from their default values. See Configure Azure VM tutorial for how to do this.

Databases

Run the following in psql to get a list of the databases:

default
\l

Quit psql

To quit psql run:

default
\q

Docker

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.

Logs

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:

Daphne/Tethys Portal

The Daphne logs capture all of the logged information from Tethys Platform:

  • /var/log/tethys/access.log

  • /var/log/tethys/error.log

  • /var/log/tethys/out.log

NGINX

The NGINX logs are helpful to review when you get 502 errors or when you are debugging connection issues:

  • /var/log/nginx/access.log

  • /var/log/nginx/error.log

PostgreSQL

The PostgreSQL logs can be helpful when you encounter database errors, though these are rare for most Tethys applications:

  • /var/log/postgresql/postgresql-12-main.log

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.

Daphne/Tethys

default
sudo systemctl status tethys.service
default
sudo systemctl start tethys.service
default
sudo systemctl stop tethys.service
default
sudo systemctl restart tethys.service

NGINX

default
sudo systemctl status nginx.service
default
sudo systemctl start nginx.service
default
sudo systemctl stop nginx.service
default
sudo systemctl restart nginx.service

PostgreSQL

default
sudo systemctl status postgresql@12-main.service
default
sudo systemctl start postgresql@12-main.service
default
sudo systemctl stop postgresql@12-main.service
default
sudo systemctl restart postgresql@12-main.service

Additional Resources

What's Next?

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!