Detailed Installation

Last Updated: April 2025

This section describes how to get Tethys Platform up and running as a fresh installation for app development. The steps within this section are what is executed behind the scenes when using tethys quickstart (see Quick Start).

Note

For upgrading an existing installation, see Upgrade to 4.3.

For deploying a production instance of Tethys Portal, see Production Installation Guide.

To contribute to the Tethys Platform source code itself, see Developer Installation.

Prerequisites

Be sure that the system you are using meets the minimum System Requirements.

1. Install the tethys-platform package

First create a Virtual Environment with the tool of your choice and then run the following commands:


conda install -c conda-forge tethys-platform django=<DJANGO_VESION>

Tip

Installation Speedup

If conda is taking too long to solve the Tethys environment, try using the libmamba solver: Using the libmamba Solver.


Install Micro-Tethys

The micro-tethys-platform conda package is a minimal version of tethys-platform. It has the exact same code base, but doesn't include any of the optional dependencies. As a result the environment is much smaller, but none of the optional features will be enabled. Any of the optional features can be enabled simply by installing the dependencies required by those features (see Optional Features).

conda install -c tethysplatform -c conda-forge micro-tethys-platform

Install Development Build

To install the latest development build of tethys-platform add the tethysplatform/label/dev channel to the list of conda channels:

conda install -c tethysplatform/label/dev -c conda-forge tethys-platform

Important

Django Version

As of Tethys 4.3 and above, the version of Django is no longer pinned in the tethys-platform package. You will need to specify the version of Django that you want to use when creating the environment. This is especially important for production installations, as only the LTS versions of Django recieve bug and security fixes. For development installations, we recommend using the same version of Django that you plan to use in production. For production installations, we recommend using the current LTS version of Django (see: How to get Django - Supported Versions. Failing to provide the Django version will result in installing the latest version of Django which may not be the LTS version.

Alternatively, to install from source refer to the Developer Installation docs.

2. Create a portal_config.yml File

To add custom configurations such as the database and other local settings you will need to generate a portal_config.yml file. To generate a new template portal_config.yml run:

tethys gen portal_config

You can customize your settings in the portal_config.yml file after you generate it by manually editing the file or by using the settings command command. Refer to the Tethys Portal Configuration documentation for more information.

3. Configure the Tethys Database

There are several options for setting up a DB server: local, docker, or remote. Tethys Platform uses a local SQLite database by default. For development environments you can use Tethys to create a local server:

tethys db configure

Note

The tethys db command (db command) will create a local database file in the location specified by the NAME setting in the DATABASES section of the portal_config.yml file (by default tethys_platform.sqlite). If the value of NAME is a relative path then the database file will be created relative to directory specified by the TETHYS_HOME environment variable. By default TETHYS_HOME is at ~/.tethys.

For additional options for configuring a database see Database Configuration

4. Start the Development Server

Once you have a database successfully configured you can run the Tethys development server:

tethys manage start

This will start up a locally running web server. You can access the Tethys Portal by going to http://localhost:8000 in your browser.

Tip

You can customize the port that the server is running on by adding the -p option.

tethys manage start -p 8001

See manage command for more details.

5. Next Steps

There are several directions that you may want to go from here.

  • Install an app you have already developed using the Application Installation guide.

  • Complete one or more Tutorials to learn how to develop apps using Tethys Platform.

  • Install one or both of the Showcase Apps to see live demos and code examples of Gizmos and Layouts.

  • Checkout the Web Admin Setup docs to customize your Tethys Portal.

  • For help getting started with docker see Using Docker