Tethys Platform
Table Of Contents
Table Of Contents

Developer Installation

Last Updated: October 2019

These instructions are intended for those that want to contribute to the Tethys Platform source code. Use these instructions to install the Tethys source code in a development environment (for Unix based systems only).

Tip

To install and use Tethys Platform, you will need to be familiar with using the command line/terminal. For a quick introduction to the command line, see the Terminal Quick Guide article.

1. Download and Run the Installation Script

Run the following commands from a terminal to download and run the Tethys Platform install script.

For systems with wget (most Linux distributions):

wget https://raw.githubusercontent.com/tethysplatform/tethys/release/scripts/install_tethys.sh
bash install_tethys.sh -b release

For Systems with curl (e.g. Mac OSX and CentOS):

curl https://raw.githubusercontent.com/tethysplatform/tethys/release/scripts/install_tethys.sh -o ./install_tethys.sh
bash install_tethys.sh -b release

Install Script Options

You can customize your tethys installation by passing command line options to the installation script. The available options can be listed by running:

bash install_tethys.sh --help
Each option is also descriped here:
  • -n, --conda-env-name <NAME>:

    Name for tethys conda environment. Default is 'tethys-dev'.

  • -t, --tethys-home <PATH>:

    Path for tethys home directory. Default is ~/.tethys/${CONDA_ENV_NAME}/.

    Note

    If ${CONDA_ENV_NAME} is "tethys" then the default for TETHYS_HOME is just ~/.tethys/

  • -s, --tethys-src <PATH>:

    Path to the tethys source directory. Default is ${TETHYS_HOME}/tethys/.

  • -a, --allowed-hosts <HOST>:

    Hostname or IP address on which to serve Tethys. Default is 127.0.0.1.

  • -p, --port <PORT>:

    Port on which to serve Tethys. Default is 8000.

  • -b, --branch <BRANCH_NAME>:

    Branch to checkout from version control. Default is 'master'.

  • -c, --conda-home <PATH>:

    Path to conda home directory where Miniconda will be installed, or to an existing installation of Miniconda. Default is ~/miniconda/.

    Tip

    The conda home path cannot contain spaces. If the your home path contains spaces then the --conda-home option must be specified and point to a path without spaces.

  • --db-username <USERNAME>:

    Username for the normal tethys database user. Default is 'tethys_default'.

    Note

    The developer install script configures the database user to be the db-super-username rather than the db-username so that tests can be run.

  • --db-password <PASSWORD>:

    Password that the tethys database server will use. Default is 'pass'.

  • --db-super-username <USERNAME>:

    Username for super user on the tethys database server. Default is 'tethys_super'.

  • --db-super-password <PASSWORD>:

    Password for super user on the tethys database server. Default is 'pass'.

  • --db-port <PORT>:

    Port that the tethys database server will use. Default is 5436.

  • --db-dir <PATH>:

    Path where the local PostgreSQL database will be created. Default is ${TETHYS_HOME}/psql/.

  • -S, --superuser <USERNAME>:

    Tethys super user name. Default is 'admin'.

  • -E, --superuser-email <EMAIL>:

    Tethys super user email. Default is ''.

  • -P, --superuser-pass <PASSWORD>:

    Tethys super user password. Default is 'pass'.

  • --skip-tethys-install:

    Flag to skip the Tethys installation so that the Docker installation or production installation can be added to an existing Tethys installation.

    Tip

    If conda home is not in the default location then the --conda-home options must also be specified with this option.

  • --partial-tethys-install <FLAGS>:

    List of flags to indicate which steps of the installation to do.

    Flags:

    • m - Install Miniconda

    • r - Clone Tethys repository (the --tethys-src option is required if you omit this flag).

    • c - Checkout the branch specified by the option --branch (specifying the flag r will also trigger this flag)

    • e - Create Conda environment

    • s - Create portal_config.yml file and configure settings

    • d - Create a local database server

    • i - Initialize database server with the Tethys database (specifying the flag d will also trigger this flag)

    • u - Add a Tethys Portal Super User to the user database (specifying the flag d will also trigger this flag)

    • a - Create activation/deactivation scripts for the Tethys Conda environment

    • t - Create the t alias to activate the Tethys Conda environment

    For example, if you already have Miniconda installed and you have the repository cloned and have generated a portal_config.yml file, but you want to use the install script to:

    • create a conda environment,

    • setup a local database server,

    • create the conda activation/deactivation scripts, and

    • create the t shortcut

    then you can run the following command:

    bash install_tethys.sh --partial-tethys-install edat

    Warning

    If --skip-tethys-install is used then this option will be ignored.

  • --install-docker:

    Flag to include Docker installation as part of the install script (Linux only). See 2. Install Docker (OPTIONAL) for more details.

  • --docker-options <OPTIONS>:

    Command line options to pass to the tethys docker init call if --install-docker is used. Default is "'-d'".

    Tip

    The value for the --docker-options option must have nested quotes. For example "'-d -c geoserver'" or '"-d -c geoserver"'.

  • --production

    Flag to install Tethys in a production configuration.

  • --configure-selinux

    Flag to perform configuration of SELinux for production installation. (Linux only).

  • -x:

    Flag to turn on shell command echoing.

  • -h, --help:

    Print this help information.

Here is an example of calling the installation script with customized options:

bash install_tethys.sh -t ~/Workspace/tethys -a localhost -p 8005 -c ~/miniconda3 --db-username tethys_db_user --db-password db_user_pass --db-port 5437 -S tethys -E email@example.com -P tpass

The installation script may take several minutes to run. Once it is completed you will need to activate the new conda environment so you can start the Tethys development server. This is most easily done using an alias created by the install script. To enable the alias you need to open a new terminal or re-run the .bashrc (Linux) or .bash_profile (Mac) file.

For Linux:

. ~/.bashrc

For Mac:

   . ~/.bash_profile

You can then activate the Tethys conda environment and start the Tethys development server by running::

   t
   tethys manage start

or simply just:

t
tms

Tip

The installation script adds several environmental variables and aliases to help make using Tethys easier. Most of them are active only while the tethys conda environment is activated, however one alias to activate the tethys conda environment was added to your .bashrc or bash_profile file in your home directory and should be available from any terminal session:

  • t: Alias to activate the tethys conda environment. It is a shortcut for the command source <CONDA_HOME>/bin/activate tethys where <CONDA_HOME> is the value of the --conda-home option that was passed to the install script.

The following environmental variables are available once the tethys conda environment is activated:

  • TETHYS_HOME:

    The directory where the Tethys source code and other Tethys resources are. It is set from the value of the --tethys-home option that was passed to the install script.

  • TETHYS_PORT:

    The port that the Tethys development server will be served on. Set from the --port option.

  • TETHYS_DB_PORT:

    The port that the Tethys local database server is running on. Set from the --db-port option.

Also, the following aliases are available:

  • tms:

    An alias to start the Tethys development server. It calls the command tethys manage start -p <HOST>:${TETHYS_PORT} where <HOST> is the value of the --allowed-host option that was passed to the install script and ${TETHYS_PORT} is the value of the environmental variable which is set from the --port option of the install script.

  • tstart:

    Combines the tethys_start_db and the tms commands.

When installing Tethys in production mode the following additional environmental variables and aliases are added:

  • NGINX_USER:

    The name of the Nginx user.

  • NGINX_HOME:

    The home directory of the Nginx user.

  • tethys_user_own:

    Changes ownership of relevant files to the current user by running the command sudo chown -R ${USER} ${TETHYS_HOME}/src ${NGINX_HOME}/tethys.

  • tuo:

    Another alias for tethys_user_own

  • tethys_server_own:

    Reverses the effects of tethys_user_own by changing ownership back to the Nginx user.

  • tso:

    Another alias for tethys_server_own

When you start up a new terminal there are three steps to get the Tethys development server running again:

  1. Activate the Tethys conda environment

  2. Start the Tethys database server

  3. start the Tethys development server

Using the supplied aliases, starting the Tethys development server from a fresh terminal can be done with the following two commands:

t
tstart

Congratulations! You now have Tethys Platform running a in a development server on your machine. Tethys Platform provides a web interface that is called the Tethys Portal. You can access your Tethys Portal by opening http://localhost:8000/ (or if you provided custom host and port options to the install script then it will be <HOST>:<PORT>) in a new tab in your web browser.

../_images/tethys_portal_landing.png
To log in, use the credentials that you specified with the -S or --superuser and the -P or --superuser-pass options. If you did not specify these options then the default credentials are:

  • username: admin

  • password: pass

2. Install Docker (OPTIONAL)

To facilitate leveraging the full capabilities of Tethys Platform Docker containers are provided to allow the Software Suite to be easily installed. To use these containers you must first install Docker. The Tethys installation script install_tethys.sh will support installing the community edition of Docker on several Linux distributions. To install Docker when installing Tethys then add the --install-docker option. You can also add the --docker-options options to pass options to the tethys docker init command (see the docker command documentation).

To install Docker on other systems or to install the enterprise edition of Docker please refer to the Docker installation documentation

Use the following Tethys command to start the Docker containers.

tethys docker start

You are now ready to link your Tethys Portal with the Docker containers using the web admin interface. Follow the Web Admin Setup tutorial to finish setting up your Tethys Platform.

If you would like to test the Docker containers, see Test Docker Containers.

3. Customize Settings (OPTIONAL)

The Tethys installation script created a portal configuration file called portal_config.yml in the directory $TETHYS_HOME/. The installation script has defined the most essential settings that will allow the Tethys development server to function based on the options that were passed to the script or based on the default values of those options. If you would like to further customize the settings then open the portal_config.yml file and make any desired changes. Refer to the Tethys Portal Configuration documentation for a description of each of the settings.

Table Of Contents

arrow_back
Previous
Tethys Platform Docker Image Reference
 arrow_forward
Next
Tethys Portal Configuration