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 --recursive https://github.com/tunapanda/provision
-
Note: The
--recursiveis essential!
cd provisionvagrant 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.
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) Move the installation to your cubietruck's SATA drive. 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.
- (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, you may also wish to includewikipedia__enabled: falseand/orkalite__enabled: false, since kalite and wikipedia require more space than any other component. - Start the main provisioning
- scripts/bootstrap.sh
- Go to post-deployment steps.
Log in as root (or log in as another user and run sudo -i). Just using sudo isn't enough, because the ssh keys Ansible needs are stored in root's homedir. This should be fixed, but it's what we have for now.
sudo -i
cd /tmp
https://github.com/tunapanda/provision/blob/master/scripts/bootstrap.sh
bash bootstrap.sh # add -x if troubleshooting
- 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 profiles (roles and playbooks are ansible terms, profiles are specific to this provisioning system).
- A role describes how to deploy a specific service or machine type. Most of the roles we use can be found in
playbooks/roles/. Well-written roles use variables instead of hard-coded values so their behavior can be customized without re-writing the role. Variables can be overridden in... - A playbook describes a set of roles to load and (optionally) custom values for variables that control what they do.
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:
(echo "---" ; echo "groups: [ custom ]"; 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
Almost every role has a variable called role_name__enabled (note the double-underscore), which is usually set to false. For many customizations you will only need to change these settings, and can ignore the others.
When you've made your changes, simply run vagrant provision if you are using vagrant, or run /usr/local/tunapanda/provision/scripts/bootstrap.sh on other systems.
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.