Updated micromasters documentation

Author: gsidebo

.rsync-ignore

@@ -5,3 +5,4 @@ node_modules
 Makefile
 README.rst
 .DS_Store
+.idea/

Makefile

@@ -1,58 +1,41 @@
 # Micromasters
 Portal for learners and course teams to access MITx Micromasters programs
 
-## Getting Started
+## Major Dependencies
+- Docker
+  - OSX recommended install method: [Download from Docker website](https://docs.docker.com/mac/)
+- docker-compose
+  - Recommended install: pip `pip install docker-compose`
+- Virtualbox (https://www.virtualbox.org/wiki/Downloads)
 
-Although you can run Micromasters locally with a default sqlite database after
-installing the ``requirements.txt`` file, the recommended way is to 
-use [Docker](https://www.docker.io). Install Docker, then install 
-``docker-compose`` and run the app: 
+## (OSX only) Getting your machine Docker-ready
 
-    pip install docker-compose 
-    docker-compose up
+#### Create your docker container:
 
-### (OSX only) Create your docker machine:
-
-    docker-machine create default
-    docker-machine start default
-    docker-machine env default
-    eval "$(docker-machine env default)"
-
-These commands create a Docker container named ``default``, start the
+The following commands create a Docker machine named ``mm``, start the
 container, and configure environment variables to facilitate communication
-with the ``edX`` instance.
-
-
-This will set up a near production-ready containerized development 
-environment that runs migrations, with the Django development server 
-running on port ``8079``.
-
-To run one-off commands, like shell, you can run:
+with the edX instance.
 
-    docker-compose run web python manage.py shell
+    docker-machine create --driver virtualbox mm
+    docker-machine start mm
+    # 'docker-machine env (machine)' prints export commands for important environment variables
+    eval "$(docker-machine env mm)"
 
-or to create root user:
+#### Enable file syncing between the host machine and Docker:
 
-    docker-compose run web python manage.py createsuperuser
+Due to file notification issues using Docker in OSX, development is more
+efficient if you install [docker-osx-dev](https://github.com/brikis98/docker-osx-dev).
+This synchronizes host file-system changes with the Docker container.
 
+First, set up ``docker-osx-dev`` via shell script.
 
-## For OS X Development
+    . ./osx_docker_dev_setup.sh
 
-Due to issues using Docker in OSX, development is more efficient if you
-install [docker-osx-dev](https://github.com/brikis98/docker-osx-dev).
-docker-osx-dev synchronizes host file-system changes with the Docker
-container. If you have [``homebrew``](http://brew.sh/) installed, you can 
-install ``docker-osx-dev`` by typing ``make`` in the root of the Micromasters
-project directory. The make file will install or update Docker using Homebrew
-and go on to install ``docker-osx-dev``.
-
-Subsequently, before you run the application with ``docker-compose up``, 
-you would run:
+Subsequently, before you run the application with ``docker-compose up``,
+you would run this command in a separate terminal tab (assumes machine
+name ``mm``):
 
-    docker-osx-dev -m default -s ./ --ignore-file '.rsync-ignore'
-
-(Assuming your Docker VM is called ``default``, and your current working
-directory is the root of the ``micromasters`` source directory).
+    docker-osx-dev -m mm -s ./ --ignore-file '.rsync-ignore'
 
 This starts a process that monitors the file system for changes. On startup
 you may receive this error:
@@ -68,96 +51,120 @@ you may receive this error:
 
 Answer ``yes``.
 
-## Configuration and Start-up
+## Running edX devstack locally _(optional, but recommended)_
+
+Micromasters can work with a live instance of edX, but it's recommended that
+you get it running locally. It's obviously more configurable that way, and you'll
+likely need to run it locally for other projects in the future.
+
+#### 1) Install edX
+Run through the
+[instructions provided by edX](https://edx-installing-configuring-and-running.readthedocs.io/en/latest/installation/devstack/install_devstack.html)
+up to and including the **LMS Workflow** section. Note that this section mentions
+some helpful dummy accounts that edX devstack comes preloaded with (eg: [email protected]).
 
-Create a user who has permission to view the course:
+#### 2) Run the machine and SSH into it
 
-    docker-compose run web python manage.py createsuperuser
+    # Start the VM
+    vagrant up
+    # Once that's done, ssh into the running VM
+    vagrant ssh
+    # Switch to the edxapp account within SSH session
+    sudo su edxapp
 
-Start the machine:
+Switching to the edxapp account sources the edxapp environment and sets the
+current working directory to the edx-platform repository. If you get the error
+_"Unknown task: devstack, the working directory has not been updated properly"_,
+simply run ``cd /edx/app/edxapp/edx-platform`` and re-run the command.
 
-    docker-compose up
+#### 3) Set up a user with superuser permissions
 
-(OSX only) visit: http://192.168.99.100:8079/
+Once in the VM, creating a superuser/setting superuser permissions can be done
+in Django admin or in a shell. It's preferable to do it in Django admin as you'll
+need to use Django admin for the next step anyway.
 
-Note: Your IP address may vary depending on what address Docker 
-assigns to your container.  If the IP address above doesn't work, enter 
-this command:
+- **In Django admin**
 
-    docker-machine ls
+    Run the server (``paver devstack --fast lms``) and navigate to Django admin
+    (eg: http://192.168.33.10:8000/admin). In the **Authentication and Authorization**
+    section, select a **User**, or add one then select it. In the **Permissions**
+    section, check the **Superuser status** box and save.
 
-The command lists the containers and their URLs.  Your container's URL
-will be something like ``tcp://192.168.99.100:2376``.  Micromasters will 
-run at that URL, but on port ``8079``.  So, for this example, Micromasters 
-will run at ``192.168.99.100:8079``.
+- **In a Python shell**
 
-## Configuring edX devstack
+        # Kick off an interactive shell
+        python manage.py lms --settings=devstack shell
 
-These instruction presume that you're running Micromasters in a development 
-environment that includes a local edX devstack.  If you don't have a edX
-devstack installed navigate to these
-[instructions](https://openedx.atlassian.net/wiki/display/OpenOPS/Running+Devstack)
-that walk you through the installation.  We'll wait.
+        ### RUN THESE WITHIN THE SHELL ###
+        from django.contrib.auth.models import User
+        # We'll update the dummy user 'staff' to have superuser permissions
+        user = User.objects.get(username='staff')
+        user.is_superuser=True
+        user.save()
 
-### Create a superuser 
-   
-You need a user with superuser privileges to create the edX client for 
-Micromasters.  Start up the edX devstack and ssh into the ``edxapp`` user.
+#### 4) Add an OAuth client
 
-    vagrant up
-    vagrant ssh
-    sudo su edxapp
+Run Django admin (see "In Django admin" section from step 2), navigate to the
+OAuth2 clients section (eg: http://192.168.33.10:8000/admin/oauth2/client/), and add a
+new client. Fill in the values as follows:
+
+- **User**: Use the lookup (magnifying glass) to find your superuser
+- **Name**: Anything you want. Something like 'micromasters-local'
+- **Url**: The URL where Micromasters will be running. If you're running it via
+Docker, run ``docker-machine ip`` from the host machine to get the container IP.
+Micromasters runs on port ``8079`` by default, so this value should be something
+like ``http://192.168.99.100:8079``
+- **Redirect uri**: Your **Url** value with "/complete/edxorg/" at the end
+
+#### 5) Copy relevant values to use in the Micromasters .env file
+
+The Micromasters codebase contains a ``.env.sample`` file which will be used as
+a template to create your ``.env`` file. For Micromasters to work, it needs 3 values:
 
-    edxapp@precise64:~/edx-platform$ pip install ipython
+- ``EDXORG_BASE_URL``
 
-Open an iPython shell and execute these commands:
+    This value _should_ be ``http://192.168.33.10:8000``. The Vagrant VM IP is hard-coded
+    in the Vagrantfile, and it's unlikely that edX will change that. The LMS server runs
+    on port ``8000`` by default.
+- ``EDXORG_CLIENT_ID`` and ``EDXORG_CLIENT_SECRET``
 
-      edxapp@precise64:~/edx-platform$ python manage.py lms --settings=devstack shell
-      Python 2.7.10 (default, Jun 29 2015, 22:38:23)
-      Type "copyright", "credits" or "license" for more information.
+    These values can be found in Django admin OAuth client section discussed above.
+    **Client id:** and **Client secret:** values should be auto-generated for
+    your new client. Use those values for the corresponding ``EDXORG_``
+    variables in the ``.env`` file
 
-      IPython 4.1.2 -- An enhanced Interactive Python.
-      ?         -> Introduction and overview of IPython's features.
-      %quickref -> Quick reference.
-      help      -> Python's own help system.
-      object?   -> Details about 'object', use 'object??' for extra details.
+## Docker Container Configuration and Start-up
 
-      In [1]: from django.contrib.auth.models import User
+First, create a ``.env`` file from the sample in the codebases:
 
-      In [2]: User.objects.get(username='staff')
-      Out[2]: <User: staff>
+    cp .env.sample .env
 
-      In [3]: staff=_
+Set the ``EDXORG_BASE_URL``, ``EDXORG_CLIENT_ID``, and ``EDXORG_CLIENT_SECRET``
+variables in the ``.env`` file appropriately.
 
-      In [4]: staff.is_superuser=True
+For first-time container start-up, start it with a full build:
 
-      In [5]: staff.save()
+    docker-compose up --build
 
-      In [6]:
-      Do you really want to exit ([y]/n)? y
+In another terminal tab, navigate the the Micromasters directory
+and add a superuser in the now-running Docker container:
 
-Start the LMS:
+    docker-compose run web python3 manage.py createsuperuser
 
-    paver devstack lms
+Starting the container after this can be done without the ``--build``
+param: ``docker-compose up``
 
-Navigate to ``localhost:8000/admin`` and login with the superuser account.
-Scroll down to the "Oauth2" section and open "Clients".
-Create a new client
-    name - your choice of name, mine is ``micromasters-local``.
-    Url - the URL of your local Micromasters instance, a URL on port ``8087``.
-    Redirect url: the same URL, but with ``/complete/edxorg/`` at the end. 
-    Client type: Chose "Confidential (Web applications)"
+You should now be able to do the following:
 
-Make a note of the Client id and the Client secret; you need them to
-configure Micromasters.  Don't forget to save your new client.
+1. Visit Micromasters in your browser on port `8079`. _(OSX Only)_ Docker auto-assigns
+ the container IP. Run ``docker-machine ip`` to see it. Your Micromasters URL will
+ be something like this: ``192.168.99.100:8079``.
+1. Click "Sign in with edX.org" and sign in by authorizing an edX client. If you're
+ running edX locally, this will be the client you created in the steps above.
 
-Return to Micromasters and, the project root directory, copy the 
-``.env.sample`` file to ``.env`` and edit these values:
-    
-    STATUS_TOKEN: Can be anything. STATUS_TOKEN is not used in local development.
-    EDXORG_BASE_URL: The URL of your local edX instance. Something like: ``http://192.168.33.10:8000``
-    EDXORG_CLIENT_ID: The ``Client id`` from the edX Oauth2 client.
-    EDXORG_CLIENT_SECRET: The ``Client secret`` from the edX Oauth2 client.
+As shown above, manage commands can be executed on the Docker-contained
+Micromasters app. For example, you can run a shell with the following command:
 
+    docker-compose run web python3 manage.py shell
 
 

README.md

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+curl -o /usr/local/bin/docker-osx-dev https://raw.githubusercontent.com/brikis98/docker-osx-dev/master/src/docker-osx-dev
+chmod +x /usr/local/bin/docker-osx-dev
+docker-osx-dev install