Clank is a deployment tool for Atmosphere, written in Ansible.

At this time, Clank only supports deploying Atmosphere to Ubuntu 14.04. The deployment host which runs Clank can run any operating system which supports Ansible.

Clone the repository.

git clone https://github.com/cyverse/clank.git

Obtain Ansible of the version specified in requirements.txt. One way is to use a Python virtual environment, like this:

# Install Python dependencies if needed
apt-get update
apt-get install -y python python-pip python-dev libffi-dev libssl-dev python-virtualenv
# Create virtual environment, activate it, and install Ansible
virtualenv clank_env
. clank_env/bin/activate
pip install -r clank/requirements.txt

Clank is configured using a set of YAML variables which override default settings. See dist_files/variables.yml.dist, which you can copy and customize for your deployment.

By default, Clank is configured to deploy against localhost. To deploy to a remote target, modify the hosts file, replacing localhost with the desired target.

ansible-playbook playbooks/deploy_stack.yml -e @/path/to/my/clank-variables.yml

To ensure you pick up the appropriate Ansible configuration, either run Clank from the root of this repository, or set the environment variable ANSIBLE_CONFIG=/path/to/your/clank-repo/ansible.cfg.

Skip some steps for a faster rebuild (after Clank has already run at least once):

--skip-tags "clone-repo,data-load,npm,pip-install-requirements,apt-install"

Verbose Ansible output for troubleshooting:

-vvvvv -e "CLANK_VERBOSE=true" --tags print-vars

All features of ansible-playbook are at your disposal, which can be viewed by running ansible-playbook --help.

Clank provides optional functionality that is used in some, but not all deployments. Enable these optional configurations by setting the corresponding variable to true (e.g. in your variables.yml).

[WIP] -- All of clank should be re-evaluated to ensure that the 3 'supported tags' listed below cover enough ground. For now, ignore this section. -- [WIP]

Clank's install process is separated into three parts: installation of dependencies, atmosphere, and troposphere. To run specific parts of the deployment process, pass a comma separated list to the --tags option.

Supported tags: dependencies, atmosphere, troposphere, kernel

Note: kernel tag is only attached to the app-alter-kernel-for-imaging role in the setup_atmosphere.yml playbook so that it can be skipped in Docker build environments.

ansible-playbook playbooks/deploy_stack.yml -e @/path/to/my/clank-variables.yml --tags dependencies,troposphere

You can actually specify any tag you may find in the roles and playbooks. Clank is just Ansible.

Clank comes with several useful utilities located in playbooks/utils/.

You can run a particular utility just like any other playbook:

ansible-playbook -e @/path/to/my/clank-variables.yml playbooks/utils/upgrade_postgres.yml

• A organizational cert
• A bundle cert
• And a organization ssl key

• A private id_rsa file
• A public id_rsa file

• atmosphere.sql
• troposphere.sql

The location of these files must be stated in your completed variables.yml. # FIXME: bad linked-lines.

You can change the images and colors used in troposphere to reflect your own institution's branding.

To change images like the logo or favicon, add the absolute path to your theme images folder to the variable THEME_IMAGES_PATH in variables.yml.

THEME_MAGES_PATH: "/absoulte/path/to/your-images"

We recomened copying the defaultThemeImages folder found in Troposphere <projectRoot>/troposphere/static/theme/themeImagesDefault

Replace any image in the folder with your new image keeping the same name and file type. It is important that the new image has the same dimensions and uses a transparent background or it may not display correctly. Your image may not be the same ratio as the image you are replacing but the file should be. For example, your logo might be shorter in length given the same height. Without distorting the logo ratio, align it to the left of the file and export the file at the same dimensions of the original file.

File Dimentions
+++++++++++++++++++++++++++
+--------------------     +
+| Logo Dimentions  |     +
+--------------------     +
+++++++++++++++++++++++++++

To change the theme colors edit the color variable. Colors are used by cyverse-ui and Material-ui for components like buttons, toggles, radios, etc... See Our Style Guide for more information on how colors are used by components.

A developer of atmosphere/troposphere are going to be serving the app in unique ways. Often it's desired to serve assets that are generated whenever the source changes, so that developers can see changes as they're made. Sometimes it's useful to put interactive debuggers in the services. However the production nginx setup serves JS assets from a static folder, and daemonized python services via uwsgi.

Clank supports predefined nginx templates for common development workflows, which is configured via nginx_locations.

By default, the production value is:

nginx_locations: ["atmo-uwsgi", "tropo-uwsgi", "flower", "tropo-assets-path", "robots"]

This serves troposphere and the atmosphere api over uwsgi, includes an endpoint for flower, serves troposphere assets from an asset directory on disk, and includes an endpoint for robots.txt.

In order to serve troposphere assets from a webpack-dev-server instead of a directory on disk, nginx_locations would include "tropo-assets-server" instead of "tropo-assets-path".

nginx_locations: ["tropo-assets-server", ...]
TROPO_ASSETS_SERVER_URL: "http://local.atmo.cloud:8080"

Note, that TROPO_ASSETS_SERVER_URL must be defined, and you will be responsible for running the server at that location.

In order to serve the atmosphere api from a ./manage.py runserver instance, nginx_locations would include "atmo-dev-server" instead of "atmo-uwsgi".

LOCATIONS: ["atmo-dev-server", ...]
ATMO_DEV_SERVER_URL: "http://local.atmo.cloud:8000"

Note, that ATMO_DEV_SERVER_URL must be defined, and you will be responsible

In order to serve jenkins, nginx_locations would include "jenkins".

LOCATIONS: ["jenkins", ...]
JENKINS_SERVER_URL: "http://127.0.0.1:8080"

Note, that JENKINS_SERVER_URL must be defined, and you will be responsible for running the server at that location.

For further examples read the documentation of configure-nginx located here.

See HACKING.md

See LICENSE file.