io.livecode.ch

io.livecode.ch is a prototype for turning code repositories into interactive tutorials and books, with code snippets that can be edited and run on the web.

Test your .io.livecode.ch/_site locally

• git clone https://github.com/namin/io.livecode.ch
• cd io.livecode.ch
• git submodule init; git submodule update
• cd pub/templates/local
• git clone https://github.com/<user>/<repo>.git
• cd ../.. (back to pub directory)
• python local.py (powered by flask and requests)
• visit http://localhost:5000/learn/<user>/<repo>
• if you make code changes, refresh the server installation by visiting http://io.livecode.ch/learn/<user>/<repo>?refresh=1

Development server-side installation steps

These steps have been tested on an Ubuntu derivative and Mac OS X.

• Install dependencies

  • Install docker for for Ubuntu or for Mac OS X.
  • Install dependencies (example from a clean slate Ubuntu)
    • sudo apt-get install redis-server python-pip git
    • sudo pip install flask redis docker-py

• Set up local io.livecode.ch repository in a directory of your choice

  • git clone --recursive https://github.com/namin/io.livecode.ch
  • export LIVECODE_DIR=``pwd``/io.livecode.ch

• Install the io.livecode.ch docker image

  • Get the official image
    • docker pull namin/io.livecode.ch
    • export LIVECODE_CONFIG="dev"
  • Or build your own from the source repo
    • cd $LIVECODE_DIR; docker build -t=namin/io.livecode.ch-dev .
    • export LIVECODE_CONFIG="dev_docker"

• export GITHUB_BOT_TOKEN="your_access_token"

• Run local development server

  • export APP_SETTINGS=$LIVECODE_DIR/cfg/$LIVECODE_CONFIG.cfg
  • cd $LIVECODE_DIR/pub
  • python __init__.py

Production server-side installation steps

These steps have been tested on a DigitalOcean (referral link) docker application droplet, and work regardless of the actual (sub)domain name of your server (i.e. no need to change occurrences of io.livecode.ch in config files).

• Create a new droplet in the DigitalOcean UI:

  • for the image, select the default Ubuntu image
  • for the other options, select as you please. My options:
    • for the size, I use the second smallest droplet, though any other including the smallest should work too.
    • for the last settings, I keep the default VirtIO enabled (I have not tested it disabled).

• Initial setup of the server

  • Instructions to install Docker
  • $ME refers to your preferred username (e.g. namin for me)
  • $DKR refers to a docker-enabled user (e.g. dkr, which I use for scheduling docker cleanups)
  • as root:
    • be sure to set $ME and $DKR as you like. I do:
      • export ME=namin
      • export DKR=dkr
    • apt-get update
    • apt-get upgrade
    • Install docker.
    • adduser $ME
    • usermod -a -G www-data,docker,sudo $ME
    • usermod -a -G docker www-data
    • adduser $DKR
    • usermod -a -G docker $DKR
  • as $ME:
    • set up your favorite editor (and other tools) as you please. I do:
      • set up emacs

        • sudo apt-get install emacs

        • git clone -b server https://github.com/namin/.emacs.d.git

          (in $HOME directory)

        • run emacs to ensure customization works

      • configure git
        • git config --global user.name "Nada Amin"
        • git config --global user.email "[email protected]"
        • git config --global core.editor emacs
    • pull official io.livecode.ch docker image
      • docker pull namin/io.livecode.ch
    • set up NGINX

      • sudo apt-get install nginx

      • sudo rm /etc/nginx/sites-enabled/default

        (rationale: the default kicks in too easily)

      • (when adding another domain (e.g. dev.livecode.ch), I had to comment out this line in /etc/nginx/nginx.conf: server_names_hash_bucket_size 64;)

    • set up dependencies
      • sudo apt-get install uwsgi uwsgi-plugin-python
      • sudo apt-get install redis-server
      • sudo apt-get install python-pip python-dev
      • sudo pip install flask redis docker-py
    • set up website
      • cd /var
      • sudo mkdir -p www
      • sudo chown www-data:www-data www
      • sudo chmod g+w www
      • cd www
      • git clone https://github.com/namin/io.livecode.ch.git
      • cd io.livecode.ch
      • git submodule init; git submodule update
      • cp app.wsgi.sample app.wsgi
      • edit the app.wsgi to include the environment variable GITHUB_BOT_TOKEN
      • cd cfg
      • sudo cp nginx-site.sample /etc/nginx/sites-available/io.livecode.ch
      • sudo ln -s /etc/nginx/sites-available/io.livecode.ch /etc/nginx/sites-enabled/io.livecode.ch
      • sudo cp uwsgi-app.ini.sample /etc/uwsgi/apps-available/io.livecode.ch.ini
      • sudo ln -s /etc/uwsgi/apps-available/io.livecode.ch.ini /etc/uwsgi/apps-enabled/io.livecode.ch.ini
  • as $DKR:
    • mkdir log
    • touch log/clean.log
    • contrab -e
    • add line
      • */10 * * * * (/var/www/io.livecode.ch/bin/clean) >>log/clean.log

Docker cheat sheet

• docker run -i -t -u runner -e HOME=/home/runner namin/io.livecode.ch /bin/bash --login

  (shell access)