Official Docker Image¶
Last Updated: July 2020
Versions and Tags¶
The official Tethys Docker images are located in the tethysplatform/tethys-core Docker Hub repository. Images released are tagged using the following format:
Tag |
Description |
---|---|
latest |
latest tagged released |
master |
latest development build (what's in the master branch) |
version |
Specify the version of Tethys image, for example: v3.0.5 |
Pull a Pre-Built Image¶
The following commands will download Tethys image to your machine:
docker pull tethysplatform/tethys-core:latest # the latest Tethys release
docker pull tethysplatform/tethys-core:v3.0.5 # Tethys version 3.0.5
docker pull tethysplatform/tethys-core:master # the latest development build
Build From Source¶
Make sure that there isn't already a docker container or docker images with the desired name:
docker rm tethys-core
docker rmi tethys-core
To build a new docker image with the desired name and tag, run the following in the directory containing the Dockerfile:
docker build -t tethys-core:latest
Run Image¶
When running the docker you can use the -e
flag to set environment variables. A list of available environment variables is given in a table below.
-e TETHYS_CONDA_ENV='tethys'
Note
Variables in the Build Arguments table can be used here as well.
Example of Run Command:
docker run -p 127.0.0.1:80:80 --name tethys-core \
-e TETHYS_DB_SUPERUSER='tethys_super' -e TETHYS_DB_PASSWORD='3x@m9139@$$' \
-e TETHYS_DB_PORT='5432' TETHYS_SUPERUSER='admin' \
-e TETHYS_SUPERUSER_PASS='admin' tethysplatform/tethys-core
Docker Compose¶
A more convenient way is to use a docker-compose.yml file to build and run the image.
version: "3.2"
services:
tethys:
container_name: tethyscore
image: tethysplatform/tethys-core
build:
cache_from:
- tethysplatform/tethys-core
context: ../
ports:
- "80:80"
environment:
TETHYS_DB_SUPERUSER: "tethys_super"
TETHYS_DB_SUPERUSER_PASS: "pass"
CLIENT_MAX_BODY_SIZE: "75M"
links:
- db
depends_on:
- db
db:
image: postgres
restart: always
environment:
POSTGRES_PASSWORD: pass
You can build and run your docker image now with:
docker-compose up
Note
If you remove or comment out the build
section, it will pull the image from Docker Hub instead of building it locally.
Environment Variables¶
Tethys uses environment variables to build and initialize the app. These are the environment variables in Tethys:
Build Arguments
Environment Variable |
Description |
---|---|
TETHYS_HOME |
Path to tethys home directory. Defaults to "/usr/lib/tethys". |
TETHYS_PERSIST |
Path to tethys persist directory. Mount a drive from the host machine to this location to persist runtime data. Defaults to "/var/lib/tethys_persist" |
TETHYS_APPS_ROOT |
Path to tethys apps root directory. Defaults to "${TETHYS_HOME}/apps". |
TETHYS_PORT |
Tethys' port. Defaults to "8000". Note: this port is only used inside the container. |
POSTGRES_PASSWORD |
Password of the postgres database. Defaults to "pass". |
TETHYS_DB_NAME |
Name for Tethys Database. Defaults to "tethys_platform". |
TETHYS_DB_USERNAME |
Owner's Username for Tethys Database. Defaults to "tethys_default" |
TETHYS_DB_PASSWORD |
Owner's Password for Tethys Database. Defaults to "pass" |
TETHYS_DB_HOST |
Host of Tethys Database. Defaults to "db" |
TETHYS_DB_PORT |
Port of Tethys Database. Defaults to "5432" |
TETHYS_DB_SUPERUSER |
Super User for Tethys Database. Defaults to "tethys_super" |
TETHYS_DB_SUPERUSER_PASS |
Super User's password for Tethys Database. Defaults to "pass" |
PORTAL_SUPERUSER_NAME |
Name for the Tethys portal super user. Empty by default. |
PORTAL_SUPERUSER_EMAIL |
Email for the Tethys portal super user. Empty by default. |
PORTAL_SUPERUSER_PASSWORD |
Password for the Tethys portal super user. Empty by default. |
TETHYS_MANAGE |
Path to manage.py file. Defaults to "${TETHYS_HOME}/tethys/tethys_portal/manage.py" |
Misc Arguments
Environment Variable |
Description |
---|---|
BASH_PROFILE |
The location of bash profile file. Defaults to ".bashrc" |
CONDA_HOME |
Path of conda home. Defaults to "/opt/conda" |
CONDA_ENV_NAME |
Name of conda environment. Defaults to tethys. |
ASGI_PROCESSES |
The maximum number of asgi worker processes. Defaults to 1. |
CLIENT_MAX_BODY_SIZE |
client_max_body_size parameter for nginx config. Defaults to 75M. |
Tethys Settings Arguments
Environment Variable |
Description |
---|---|
DEBUG |
the Django DEBUG setting. Defaults to False. See Tethys Portal Configuration |
ALLOWED_HOSTS |
The Django ALLOWED_HOSTS setting. Defaults to ""[localhost, 127.0.0.1]"". See Tethys Portal Configuration |
BYPASS_TETHYS_HOME_PAGE |
The home page of Tethys Portal redirects to the Apps Library when True. Defaults to False. See Tethys Portal Configuration |
ADD_DJANGO_APPS |
List of the DJANGO APPS in this format ""[App1, App2]"". Defaults to ""[]"" (Empty) |
SESSION_WARN |
Number of seconds in idle until the warning message of session expiration displayed. Defaults to "1500" (1500 seconds). |
SESSION_EXPIRE |
Number of seconds in idle until the session expired. Defaults to "1800" (1800 seconds). |
STATIC_ROOT |
Path to the tethys static root folder. Defaults to "${TETHYS_PERSIST}/static" |
WORKSPACE_ROOT |
Path to the tethys workspaces root folder. Defaults to "${TETHYS_PERSIST}/workspaces" |
QUOTA_HANDLERS |
A list of Tethys ResourceQuotaHandler classes to load in this format ""[RQ1, RQ22]"". Defaults to ""[]"" (Empty). See RESOURCE_QUOTA_HANDLERS in Tethys Portal Configuration |
DJANGO_ANALYTICAL |
the Django Analytical configuration settings for enabling analytics services on the Tethys Portal in this format ""{CLICKY_SITE_ID:123}"". Defaults to ""{}}"" (Empty). Tethys Portal. See ANALYTICS_CONFIGS in Tethys Portal Configuration |
ADD_BACKENDS |
the Django AUTHENTICATION_BACKENDS setting in this format ""[Setting1, Setting2]"" Defaults to ""[]"" (Empty). See AUTHENTICATION_BACKENDS in Tethys Portal Configuration |
OAUTH_OPTIONS |
the OAuth options for Tethys Portal in this format ""{SOCIAL_AUTH_FACEBOOK_KEY:123}"" Defaults to ""{}}"" (Empty). Tethys Portal. See OATH_CONFIGS in Tethys Portal Configuration |
CHANNEL_LAYERS_BACKEND |
the Django Channel Layers backend. Default to "channels.layers.InMemoryChannelLayer" |
CHANNEL_LAYERS_CONFIG |
the Django Channel Layers configuration if a layer other than the default is being used. |
RECAPTCHA_PRIVATE_KEY |
Private key for Google ReCaptcha. Required to enable ReCaptcha on the login screen. See RECAPTCHA_PRIVATE_KEY in Tethys Portal Configuration |
RECAPTCHA_PUBLIC_KEY |
Public key for Google ReCaptcha. Required to enable ReCaptcha on the login screen. See RECAPTCHA_PUBLIC_KEY in Tethys Portal Configuration |
Tethys Site Arguments
Environment Variable |
Description |
---|---|
TAB_TITLE |
title to display in the web browser tab. |
FAVICON |
icon to display in the web browser tab. |
TITLE |
title of the Tethys Portal. |
LOGO |
the logo/brand image of the Tethys Portal. |
LOGO_HEIGHT |
height of logo/brand image. |
LOGO_WIDTH |
width of logo/brand image. |
LOGO_PADDING |
padding around logo/brand image. |
LIBRARY_TITLE |
title of the Apps Library page. |
PRIMARY_COLOR |
primary color of the Tethys Portal. |
SECONDARY_COLOR |
secondary color of the Tethys Portal. |
BACKGROUND_COLOR |
background color of the Tethys Portal. |
TEXT_COLOR |
primary text color of the Tethys Portal. |
TEXT_HOVER_COLOR |
primary text color when hovered over. |
SECONDARY_TEXT_COLOR |
secondary text color of the Tethys Portal. |
SECONDARY_TEXT_HOVER_COLOR |
secondary text color when hovered over. |
COPYRIGHT |
the copyright text to display in the footer of the Tethys Portal. |
HERO_TEXT |
the hero text on the home page. |
BLURB_TEXT |
the blurb text on the home page. |
FEATURE1_HEADING |
the home page feature 1 heading. |
FEATURE1_BODY |
the home page feature 1 body text. |
FEATURE1_IMAGE |
the home page feature 1 image. |
FEATURE2_HEADING |
the home page feature 2 heading. |
FEATURE2_BODY |
the home page feature 2 body text. |
FEATURE2_IMAGE |
the home page feature 2 image. |
FEATURE3_HEADING |
the home page feature 3 heading. |
FEATURE3_BODY |
the home page feature 3 body text. |
FEATURE3_IMAGE |
the home page feature 3 image. |
ACTION_TEXT |
the action text on the home page. |
ACTION_BUTTON |
the action button text on the home page. |
These environment variables can be overwritten in your app docker file.
Build Your App with Tethys Docker Image¶
You can build your app by extending from the tethys docker image. Include this at the top of your Dockerfile:
FROM tethysplatform/tethys-core:master
You can overwrite the environment variable of the tethys base image in your app docker file. For example:
ENV ASGI_PROCESSES 4
This line in your docker file will change the environment variable ASGI_PROCESSES from the default value of 1 to 4.
Here is an example of a dockerfile from a tethys app:
# Use our Tethyscore base docker image as a parent image
FROM tethysplatform/tethys-core:master
###############################
# DEFAULT ENVIRONMENT VARIABLES
###############################
ENV TETHYS_CLUSTER_IP 172.17.0.1
ENV TETHYS_CLUSTER_USERNAME condor
ENV TETHYS_CLUSTER_PKEY_FILE ${TETHYS_PERSIST}/keys/condorkey
ENV TETHYS_CLUSTER_PKEY_PASSWORD please_dont_use_default_passwords
ENV TETHYS_GS_PROTOCOL http
ENV TETHYS_GS_HOST 172.17.0.1
ENV TETHYS_GS_PORT 8181
ENV TETHYS_GS_PROTOCOL_PUB https
ENV TETHYS_GS_HOST_PUB 172.17.0.1
ENV TETHYS_GS_PORT_PUB 443
ENV TETHYS_GS_USERNAME admin
ENV TETHYS_GS_PASSWORD geoserver
ENV APP_DB_HOST ${TETHYS_DB_HOST}
ENV APP_DB_PORT ${TETHYS_DB_PORT}
ENV APP_DB_USERNAME ${TETHYS_DB_USERNAME}
ENV APP_DB_PASSWORD ${TETHYS_DB_PASSWORD}
ENV CONDORPY_HOME ${TETHYS_HOME}/tethys
##################################
# PRODUCTION ENVIRONMENT VARIABLES
##################################
ENV ASGI_PROCESSES 1
ENV CHANNEL_LAYERS_BACKEND "channels_redis.core.RedisChannelLayer"
ENV CHANNEL_LAYERS_CONFIG "\"{\"hosts\": [[127.0.0.1, 6379]]}\""
#########
# SETUP #
#########
# Speed up APT installs
RUN echo "force-unsafe-io" > /etc/dpkg/dpkg.cfg.d/02apt-speedup \
&& echo "Acquire::http {No-Cache=True;};" > /etc/apt/apt.conf.d/no-cache \
&& echo "Acquire::Check-Valid-Until false;" > /etc/apt/apt.conf.d/no-check-valid
# Install APT Package
RUN apt-get update -qq && apt-get -yqq install gcc libgdal-dev g++ libhdf5-dev > /dev/null
# Quiet pip installs
RUN mkdir -p $HOME/.config/pip && echo "[global]\nquiet = True" > $HOME/.config/pip/pip.conf
###########
# INSTALL #
###########
ADD --chown=www:www tethysapp ${TETHYSAPP_DIR}/tethysapp-my_first_app/tethysapp
ADD --chown=www:www *.py ${TETHYSAPP_DIR}/tethysapp-my_first_app/
ADD *.ini ${TETHYSAPP_DIR}/tethysapp-my_first_app/
ADD *.sh ${TETHYSAPP_DIR}/tethysapp-my_first_app/
ADD install.yml ${TETHYSAPP_DIR}/tethysapp-my_first_app/
RUN /bin/bash -c ". ${CONDA_HOME}/bin/activate tethys \
; cd ${TETHYSAPP_DIR}/tethysapp-my_first_app \
; tethys install -N"
#########
# CHOWN #
#########
RUN export NGINX_USER=$(grep 'user .*;' /etc/nginx/nginx.conf | awk '{print $2}' | awk -F';' '{print $1}') \
; find ${TETHYSAPP_DIR} ! -user ${NGINX_USER} -print0 | xargs -0 -I{} chown ${NGINX_USER}: {} \
; find ${WORKSPACE_ROOT} ! -user ${NGINX_USER} -print0 | xargs -0 -I{} chown ${NGINX_USER}: {} \
; find ${STATIC_ROOT} ! -user ${NGINX_USER} -print0 | xargs -0 -I{} chown ${NGINX_USER}: {} \
; find ${TETHYS_PERSIST}/keys ! -user ${NGINX_USER} -print0 | xargs -0 -I{} chown ${NGINX_USER}: {} \
; find ${TETHYS_HOME}/tethys ! -user ${NGINX_USER} -print0 | xargs -0 -I{} chown ${NGINX_USER}: {}
#########################
# CONFIGURE ENVIRONMENT #
#########################
EXPOSE 80
################
# COPY IN SALT #
################
ADD docker/salt/ /srv/salt/
#######
# RUN #
#######
CMD bash run.sh
Run.sh¶
The bash script run.sh
is executed during run time to startup and initialize the container. Here is what it's trying to accomplish:
Create Salt Config.
Set extra ENVs to NGINX.
Check if Database is ready.
Run Salt Scripts to establish the necessary set up for the docker image.
Fix permissions.
Start supervisor.
Showing the logs for supervisor, nginx and tethys.
Run.sh also has these following optional arguments:
Argument |
Description |
---|---|
--background |
run supervisord in background. |
--skip-perm |
skip fixing permissions step. |
--db-max-count |
number of attempt to connect to the database. Default is at 24. |
--test |
only run salt scripts. |
For example, to only run the salt script you can run.
sudo docker run -it tethysplatform/tethys-core /bin/bash -c '. run.sh --test'
Salt Script¶
Tethys uses Salt Script to setup the app when the docker container runs. The file, named top.sls
, contains a list of state files to run. These files are pre_tethys.sls
, tethyscore.sls
and post_app.sls
. You can override this file with your own top.sls
file to insert a salt state file for your app. Here is an example of a top.sls
file in a tethys app:
base:
'*':
- pre_tethys
- tethyscore
- tethys_app
- post_app
In this example, you can put logic needed to initialize your app in the tethys_app.sls
file. The rest of the scripts are coming from tethys-core to help initialize the app setup up. Don't forget to add a line to the Dockerfile to add the new tethys_app.sls
script to the /srv/salt
directory:
ADD tethys_app.sls /srv/salt/
Salt Script Description¶
Create static workspace and root for tethys.
Generate tethys settings.
Generate NGINX service.
Generate ASGI service.
Prepare database for tethys.
Persist portal_config.yaml.
Persist workspace and static data of the app.
Persist and link NGINX and ASGI for the app.