Deploy Tools Reference
Content Controller is a fairly complex application, so we’ve created a set of Ansible playbooks and Bash scripts to help you deploy it.
Ansible playbooks are a collection of tasks that describe how application componets are deployed. These playbooks are further broken down in to Roles. There is usually one role per application component. You’ll want to pay special attention to the section labeled Group Vars below, as that is how you will configure your installation.
To make it easier to understand, let’s dive in to the Content Controller playbooks. You can find those here on GitHub.
Note that you don’t have to understand every detail of these playbooks, but if you are hosting the application yourself, it certainly helps when things go sideways to have an idea of what is running on your servers and how it gets there.
There are a few bash scripts that are useful for getting started.
Run this on your Ansible control server. It will install all of the necessary dependencies for running the playbooks.
Only run this once! It sets up the initial group vars for you, sets sane defaults, and generates passwords and secrets. After adding your
keypair.yml file, run this script.
roles folder, you’ll find several folders. Each folder is a role which contains default variables, tasks, files, and templates and is responsibile for installing and configuring an application component.
tasksdescribe exactly what the role will do and when.
defaultsare variables that can be configured by you if needed. If you want to change one of these variables, place those changes somewhere in your
host_vars- don’t modify the actual files in
varsare variables that are used by the role. They typically shouldn’t be changed (overwriting them in the
handlersare executed by the
taskswhen things are changed. We typically use them to restart services after the role has finished executing.
Installs the Apache web server, which acts as a reverse proxy to Content Controller and SCORM Engine.
Provisions S3 buckets, IAM users, and creates an S3 group var when initial provisioning Content Controller inside of Amazon Web Services. This role is covered in more detail in the AWS setup. It will only be used one time.
Installs Rustici Engine, which carries the bulk of the load when serving courses to learners.
Copies cookie signing keys for AWS CloudFront to the proper locations on the server.
Performs some important tasks such as installing operating system dependencies and setting the server timezone to UTC.
Installs the Content Controller application and writes configuration templates.
Installs and updates the Oracle Java JDK to the latest supported version.
Sets up folders and permissions for temp files or mounted folders when using a storage solution other than AWS S3.
Installs local dependencies for connecting to MySQL, creates application DB users with appropriate permissions, sets up tables, and performs some hardening.
Installs a local copy of MySQL for QA and staging environments.
Installs SSL certs when terminating SSL at Apache. Also generates self-signed SSL certs for QA and staging environments.
Installs and configures Apache Tomcat for use by Rustici Engine.
Contains settings for the
build_ami.yml playbook. If you are not using AWS or you don’t want to deploy releases using the AMI builder, then you can ignore this file.
Enables AWS CloudFront and provides settings for allowing Content Controller to sign CloudFront cookies. You can ignore this if you aren’t using CloudFront and S3.
Contains important settings for the Content Controller application such as database credentials, auth token secret key, initial application user credentials, and email credentials.
Contains settings for Rustici Engine. You can probably ignore most of these.
This one is where the majority of the configuration happens, and you should review it carefully. Some important things to check on in this file include:
ServerName- the domain name used by Content Controller
S3FileStorageEnabled- you’ll want to set this to true if you’re using AWS S3
- SSL settings - we recommend terminating SSL at the load balancer if you’re using AWS. If not, you’ll want to follow the instructions for adding SSL certificates and set
- Heap size - if your application servers have more than 4 GB RAM, you’ll want to adjust these values.
This file contains credentials for downloading the latest release of Content Controller. It will be provided by Rustici during the project kickoff.
Contains settings for AWS S3. If you run the
aws-s3.yml playbook to setup S3, then this file will be created for you.
If you have a staging and production installation of CC and want specific settings to vary between them, using
host_vars will be how you accomplish that. You will need to add a separate
host_vars file for each environment that contains the different settings. These files will overwrite settings from the shared
group_vars config files. An example setup might look like:
All of your
group_vars files will stay the same, and the values that the settings should have for production will be specified in your
host_vars entry. There may be other settings you want to differ between environments, but we expect the following to be set:
ServerName: the domain name used by Content Controller
cc_db_host: used to ensure that your deployment doesn’t affect the test environment’s database
mysql_root_password: the root password of the target database
We also recommend changing the following between environments for the sake of security, but it isn’t necessary. The exact values don’t matter, as long as they are unique and secure passwords:
When you want to reference a
host_vars file during deployment, just add the argument
--extra-vars="@host_vars/name.of.file.yml" somewhere before the
env.yml. Ansible will read the file you’ve provided, and the settings specified in that file will overwrite the values you’ve configured in the
Again, these files are for environment-specific settings. Anything that applies to both staging and production environments (like SMTP settings, file paths, etc) will go in the
group_vars directory, and anything environment-specific goes in the
host_vars directory for that environment. If you have any questions about the best way to setup a separate staging and production environment, give us a call.
We provide several playbooks to assist you with deploying Content Controller.
This playbook sets up the majority of the necessary bits in AWS for using S3 with Content Controller.
If you’re using AWS, this is the best way to deploy Content Controller. It creates a new EC2 instance, deploys Content Controller to it, creates an AMI (Amazon Machine Image), and then destroys the EC2 instance. You can then add the AMI to an autoscaling group or use the image to spin up a few servers and add them to your load balancer target. Refer to the deploying on AWS section for more information.
Deploys Content Controller. It will automatically load the group vars.
Also deploys Content Controller, but skips loading group vars. You must include the group vars from the command line or provide a fully-loaded host vars file. You probably won’t need this one.