Getting Started¶
Last Updated: June 2022
This section describes how to get Tethys Platform up and running as a fresh installation for app development. If you are upgrading an existing installation then refer to the Upgrade to 3.4 docs. If you are deploying a production instance of Tethys Portal refer to the Production Installation Guide docs. If you want to contribute to the Tethys Platform source code itself then refer to the Developer Installation docs.
Prerequisites¶
Tethys Platform requires the conda packaging system. If you do not already have an installation of Miniconda (or Anaconda) then refer to their documentation for installation instructions.
Also, be sure that the system you are using meets the minimum System Requirements.
1. Install the tethys-platform Conda Package¶
To install the
tethys-platforminto a new conda environment then run the following commands:
conda create -n tethys -c tethysplatform -c conda-forge tethys-platform
Tip
If conda is taking too long to solve the Tethys environment, try using the [experimental libmamba solver](https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community):
conda update -n base conda
conda install -n base conda-libmamba-solver
conda create --experimental-solver libmamba -n tethys -c tethysplatform -c conda-forge tethys-platform
Note
To install the latest development build of tethys-platform add the tethys/label/dev channel to the list of conda channels:
conda create -n tethys -c tethysplatform/label/dev -c tethysplatform -c conda-forge tethys-platform
Alternatively, to install from source refer to the Developer Installation docs.
2. Activate the Tethys Conda Environment¶
Anytime you want to work with Tethys Platform, you'll need to activate the tethys Conda environment. You will know the tethys environment is active when (tethys) is displayed to the left of the terminal prompt. Activate the tethys environment now as follows:
conda activate tethys
3. 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.
4. Configure the Tethys Database¶
Tethys Platform requires a PostgreSQL database server. There are several options for setting up a DB server: local, docker, or dedicated. 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 server in the directory specified by the DIR setting in the DATABASES section of the portal_config.yml file. If the value of DIR is a relative path then the database server will be created relative to directory specified by the TETHYS_HOME environment variable. By default TETHYS_HOME is at ~/.tethys.
As an alternative to creating a local database server you can also configure a Docker DB server (see Using Docker). A local database server is only recommended for development environments. For production environments please refer to Production Installation Guide.
5. 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.
6. Next Steps¶
There are several directions that you may want to go from here.
Checkout the Web Admin Setup docs to set up your Tethys Portal.
For help getting started with docker see Using Docker
To install your app refer to the Application Installation
You also may want to jump over to the Tutorials to begin developing your first app.