Repository navigation
Setup
There are four ways in which the provisioning system might be used:
- Deploying to a vagrant-based VM
- Best for development and testing, unless you need a non-x86 architecture
- Deploying to a cubietruck
- x2go default for deployments to locations with no existing hardware, or power/space limitations
- Deploying to a commodity PC
- Tunapanda default for deployments to locations that already have hardware
- Refreshing/reloading the config after deployment
- Applies to all of the above methods
- bootstrap.sh is run from /etc/rc.local at every boot (but skips most tasks if not net connection is detected)
- Install vagrant and virtualbox
git clone https://github.com/tunapanda/provisioncd provision- See the Customization section below for ways you can fine-tune your install beyond the default setup.
vagrant up- To access the system, either:
-
vagrant ssh(CLI only, no password required) - A new VirtualBox window should appear during deployment. You can log in there with username
teacherand passwordTunapanda2. If you installed the GUI (see 'customization' below), you will have full desktop access here.
- See the Post-deplyment steps, below.
An important note about vagrant deployments: Normally, the deployment process clones the provision git repo into /usr/local/tunapanda/provision. In this case, you've already cloned the repo on your host system, so we can just use that. The Vagrantfile that controls the VM's behavior mounts the directory where you cloned the repo on your host as /usr/local/tunapanda/provision on the VM. This is why VM-based deployments can be very convenient for development. Just modify stuff in the repo and run vagrant provision to apply your changes.
edX requires several modifications to work on ARM. Thanks mainly to the work of Arturo Samanez and Ahmad Draidi, we have a prebuilt image of Ubuntu 14 for ARM (based on Igor Pecovnik's Cubietruck Ubuntu), with edX pre-installed. You will need to begin by using it to create an SD card from which to boot the cubie.
- (Optional) Normally, after the initial installation, several rsync processes will be spawned to start downloading site content in the background. You can also pre-download this content if it's easier for you to just do a few downloads overnight before you even deploy your cubietruck. Just download these archives and put them on a USB drive or something else you can use to extract them onto the cubietruck later:
- wikipedia (4.6G)
- KA-Lite (11G)
- All other modules (3.3M)
- Download the x2go initial setup image
-
wget http://geekdome.net/x2go/cubietruck_trusty_edx/x2go_edx.img.bz2- This file is hosted on a server in the US. Outside of the US, you may get better performance downloading it from Google here.
- Write the image to your SD card
-
bzcat x2go_edx.img.bz2 | sudo dd bs=4096 of=/dev/sdX- Replace
Xwith your device's letter. Rundmesgafter inserting the card for hints if you're not sure. - This step can take 2+ hours to complete!
- Replace
- Plug your cubietruck's wired ethernet adapter into the network so it can access the Internet for installations later.
- Boot your cubietruck from the SD card.
- The initial boot may take a while. It should configure its self to use either VGA or HDMI, whichever is plugged in during the initial boot, but you don't even need video because...
- When the cubie finishes booting, you should see a wireless access point called
x2go. - Connect to the
x2gowifi network and ssh toroot@10.0.0.1with the passwordx2go - Change the root password!
passwd
- (Optional) Use your cubietruck's SATA drive, if it has one. You have two options:
- Store just the site data (course content, etc) on the SATA drive. This lets you re-OS and reprovision from scratch if you need to without having to re-download content that probably won't change between provisionings.
- Be sure you are OK losing all data currently on the drive!
- sudo mkfs.ext4 -L TUNAPANDA_DATA /dev/sda1
- The provisioning script will cause any device with the label
TUNAPANDA_DATAto be auto-mounted under/usr/local/tunapanda/data/.
- Store everything possible on the SATA drive. This includes the OS and site data, but not the boot files, so the cubie will still need an SD card to boot from. We're still testing, but this may improve performance.
~/nand-sata-install- Follow the instructions to install to
/dev/sda1 - Note: Leave the SD card in the cubietruck. The cubie will still need it to boot, even if most data has been moved to the SATA drive.
- Reboot, and log in again.
- (Optional) Expand the previously-downloaded content (if you downloaded it in the first step).
mkdir -p /usr/local/tunapanda/data/portal_modulescd /usr/local/tunapanda/data/portal_modules- Expand the archives into this directory
- Update the provisioning scripts
cd /usr/local/tunapanda/provision-
git pullImportant! Don't skip this! - Customize your deployment
cd /usr/local/tunapanda/provisioncp localconfig.yml-sample localconfig.yml- Edit
localconfig.ymland at least set theprovision__siteandprovision__instancevars. * If you have limited storage space (e.g. no SATA drive), you may also wish to includewikipedia__enabled: falseand/orkalite__enabled: false, since kalite and wikipedia require more space than other services. - Start the main provisioning
- scripts/bootstrap.sh
- Go to post-deployment steps.
Note: These instructions assume a machine already running Ubuntu 14 (other Debian-like distros will probably also work, but have not been tested).
Really important note: Following these instructions will completely reconfigure the system. Don't do this on a personal machine you don't plan to use as a dedicated server. If you're just curious, use the instructions for deploying on a virtual machine instead!
- cd /tmp
- wget https://github.com/tunapanda/provision/blob/master/scripts/bootstrap.sh
- sudo bash bootstrap.sh # add -x if troubleshooting
At this point some basic configuration been done, but mostly we've just set up the /usr/local/tunapanda/provisioning directory and created some users. To customize your deployment further, see Customizing below.
- If provisioning failed, run
scripts/diag.sh, and email the resulting archive to brad@tunapanda.org. - If things don't seem to be working after the provisioning process completes, try rebooting the cubietruck.
- The provisioning process starts a set of background rsync processes to download files for most of the content modules linked from the main page, but if you reboot they can die and will need to be re-started. You can do this by running
/usr/local/tunapanda/data/cron_datasync/syncscripts.d/*as root
- The provisioning process starts a set of background rsync processes to download files for most of the content modules linked from the main page, but if you reboot they can die and will need to be re-started. You can do this by running
- In order for the content modules to be searchable, the database for the web crawler
sphidermust be populated. You can do this by running the following as root on the cubie.wget http://geekdome.net/x2go/cubietruck_trusty_edx/sphider_plus.sql.bz2bzcat sphider_plus.sql.bz2 | mysql sphider_plus
- PLEASE REPORT BUGS!. Email Brad Smith with questions and comments.
First, a very brief overview of Ansible, the system we use to configure systems during deployment. You will need to understand at least three concepts: roles, playbooks, and variables.
- A role describes how to deploy a specific service or machine type. Most of the roles we use can be found in
playbooks/roles/. - A playbook describes which roles to load, among other things. The file matched by
playbooks/*.ymlare all playbooks. By default, when you runscripts/bootstrap.sh, it usesplaybooks/main.ymlfor deployment instructions. - A variable is a setting that can control the behavior of roles and playbooks.
If all you need to do is customize which services are installed, how many users are created, the system's hostname, etc, the easiest way to do this is with a localconfig.yml.
cd /usr/local/tunapanda/provisioncp localconfig.yml-sample localconfig.yml- Open
localconfig.ymlin a text editor and make whatever customizations you need. The comments in the file should explain everything, but basically there are two things you can define here:
- The
groups:section lets you select one or more "groups" for your deployment. A group is a convenient collection of variables, and sometimes custom playbooks, for a particular deployment scenario.- Each group has variables are set
playbooks/group_vars/$GROUPNAME.- ...so, to get a list of available groups, run
ls playbooks/group_vars/.
- ...so, to get a list of available groups, run
- Groups may also have a custom playbook at
playbooks/$GROUPNAME.yml. Otherwise, it just loads all roles enabled in the vars file. - Note that if you are deploying on a cubietruck (or really anything with an ARM architecture), the provisioning system will automatically use the
cubietruckgroup by default.
- Each group has variables are set
- The
vars:section lets you override any setting, including the ones set by your selected groups.- The most common vars to overide are
provision__siteandprovision__instance, as described in the comments. - You can also enable or disable any role by setting
$ROLENAME__enabled(note the two '_' characters) totrueorfalse. - To see all of the variables for a role, look in
playbooks/roles/$ROLENAME/defaults/main.yml
- The most common vars to overide are
You can also create a localconfig.yml with all available variables set to their default values like this:
(echo "---" ; echo "groups: [ default ]"; echo "vars:" ; for r in $(ls playbooks/roles/) ; do echo "" ; echo " ## $r role" ; cat playbooks/roles/$r/defaults/main.yml | grep -v '^---' | grep -v '^[[:space:]]*$' | sed 's,^, ,'; done) > localconfig.yml
To apply your changes, run sudo scripts/bootstrap.sh
If the file playbooks/custom.yml exists, bootstrap.sh will use it instead of the default. If you know what you're doing with Ansible, you can use this to create your own custom playbook.
Normally, the best profile is automatically chosen based on hardware architecture, etc, but if you want to (and you know what you're doing!), you can fine-tune things with a special profile called custom, and the localconfig.yml file. Note that this file does not exist by default, but you can create one using localconfig.yml.sample as a template, or using the following command, which will create a config file with all available settings set to their default values:
To apply your changes, run sudo scripts/bootstrap.sh
Note: this feature hasn't been tested much recently. If you encounter problems, please file an issue with information on how you used it and what went wrong
You can generate a bootable DVD of the provisioned system, which can then be used to demo or install a duplicate of the system elsewhere, by adding build_iso__enabled: true to your localconfig.yml.