Instance Setup Code

Exosphere uses Ansible to configure and provision new instances. (Among other things, it installs and configures Docker and Apache Guacamole server for the one-click terminal and remote desktop environment.) The setup code is stored in the ansible/ directory of the Exosphere repository.

By default, new instances pull this code from the master branch of the upstream exosphere/exosphere repository. This is true even for instances which are launched using a different branch or fork of Exosphere.

You may wish to configure Exosphere to deploy instances using your own (modified) instance setup code, for development/testing purposes or as customized for your own organization. To do that, you must push the code to a git repository somewhere that new instances can download from, and then set two options in config.js:

  • instanceConfigMgtRepoUrl to the git repository URL that new instances can download your setup code from
  • instanceConfigMgtRepoCheckout to the repository branch/tag/commit that should be checked out (defaults to master if left null)

Note that Exosphere downloads the specified repo and runs the playbook stored at ansible/playbook.yml, so implement your changes by modifying that playbook.

To test the instance setup code locally on a cloud instance, do this:

python3 -m venv /opt/ansible-venv
. /opt/ansible-venv/bin/activate
pip install ansible-core
ansible-pull --url --directory /opt/instance-config-mgt -i /opt/instance-config-mgt/ansible/hosts /opt/instance-config-mgt/ansible/playbook.yml

Optionally, pass the --checkout argument to specify a git branch/tag or commit hash.

For now, we are using only built-in Ansible modules, because Exosphere uses the lightweight ansible-core package.

Ansible variables currently used

Exosphere sets these variables when running the instance setup code on a new instance.

variable type required description
guac_enabled boolean no deploys Apache Guacamole to serve terminal (and optionally desktop)
gui_enabled boolean no deploys VNC server, configures Guacamole to serve graphical desktop
workflow_source_repository string no source git repository to use for deploying a Binder container
workflow_repo_version string no git reference (branch, tag, commit) for the above binder repository

Additional Scripts

Exosphere deploys additional scripts in assets/scripts/ for easy use on instances. The only script currently deployed this way is and all examples below will reference that script.

As users are instructed to run these scripts using curl https://[exosphere_domain]/assets/scripts/ | sudo python3 -, these commands will not work correctly when developing on localhost. The suggested way to test modifications to these scripts is:

  1. Download or copy the current script code to an instance
  2. Run locally with sudo python3 instead of curl ... | sudo python3 -
  3. Make changes as needed. Either: * Edit assets/scripts/ copying to your instance as needed to test changes * Edit the script locally on the instance, updating assets/scripts/ when finished