teracyhq · hoatle · Dec 7, 2016 · Dec 6, 2016 · Dec 6, 2016 · Dec 6, 2016
diff --git a/README.rst b/README.rst
@@ -1,15 +1,18 @@
-teracy-dev - get development fun!
-=================================
+teracy-dev
+==========
 
-This ``teracy-dev`` repository was created for developing softwares at Teracy with ease and fun.
-We use ``virtualbox`` for running as a VM box, ``chef`` and ``vagrant`` for
-installing and configuring any necessary packages.
+The only truly universal software development platform for all!
 
-By using this approach, we can work in a consistent development environment. We do not have to
-install tons of development stuff on the host machine **manually** to get started.
 
-Before getting started, please see the "Frequently asked question" to know some of the common
-problems you could meet with proposed solutions.
+``teracy-dev`` is created to set up a universal development platform which has the same development
+workflow on Mac, Linux and Windows with good developer experience and productivity in mind. 
+
+We leverage Docker workflow for our software development and we use ``vagrant``, ``virtualbox``, and
+``chef`` to install and configure any necessary packages.
+
+By using this approach, we can work in a consistent development environment and workflow.
+We do not have to install tons of development stuff on the host machine **manually** to get started.
+
 
 Usage
 -----
@@ -27,233 +30,7 @@ Installation
 Follow the guide at: http://dev.teracy.org/docs/develop/getting_started.html
 
 
-Configuration
--------------
-
-All configuration is in the ``Vagrantfile`` and ``vagrant_config.json`` files.
-
-To override the default configuration, you need to copy the key you want to override from ``vagrant_config.json``
-to your newly created ``vagrant_config_override.json`` file and adjust it by your needs.
-
-For example, override the ``git`` keys as follows.
-::
-
-  {
-    "chef_json":{
-      "teracy-dev":{
-        "git":{
-          "user":{
-            "name":"hoavt",
-            "email":"[email protected]"
-          }
-        }
-      }
-    }
-  }
-
-We do this for smooth teracy-dev upgrading.
-
-``workspace`` directory
------------------------
-
-The ``workspace`` directory is created under ``teracy-dev``. This ``workspace`` directory is the
-location where you will store all your work, after ``$ vagrant up``, the following sub-directories
-will be created if they do not exist yet.
-
-``workspace/personal``: the location to store all your stuffs which you have full control
-(your own projects).
-
-``workspace/readonly``: the location to store all the stuffs that you just can read only (open source
-projects).
-
-
-The ``teracy-dev/workspace`` directory from host machine is mapped to the ``~/workspace`` directory
-on the virtual machine. So you can access this ``workspace`` directory from the virtual machine by the
-``$ cd ~/workspace`` or alias ``$ ws`` command.
-
-From now on, we will ``$ vagrant ssh`` and run command lines on the virtual machine if not
-explicitly mentioning about running command lines on the host machine.
-
-
-Training
---------
-
-We offered free training for recruiting newcomers.
-
-- For Django development, please head to: http://dev.teracy.org/docs/develop/django_training.html
-
-
-Learn more
-----------
-
-- Teracy's projects
-
-    + https://github.com/teracyhq
-
-- Vagrant
-
-    + http://www.vagrantup.com/
-
-- Sublime Text
-
-    + http://www.sublimetext.com/
-
-- Django
-
-    + https://docs.djangoproject.com/en/1.5/
-
-    + http://www.djangobook.com/en/2.0/index.html
-
-    + http://www.deploydjango.com/
-
-    + ``pip``: http://www.pip-installer.org/en/latest/
-
-    + ``virtualenv``: http://www.virtualenv.org/en/latest/
-
-    + ``virtualenvwrapper``: http://virtualenvwrapper.readthedocs.org/en/latest/
-
-- Python
-
-    + http://python.org/doc/
-
-    + http://www.diveintopython.net/
-
-    + http://learnpythonthehardway.org/book/
-
-- Git
-
-    + http://git-scm.com/book
-
-- NodeJs
-
-    + http://nodejs.org/api/
-
-- Vim
-
-    + http://www.openvim.com/tutorial.html
-
-    + https://www.shortcutfoo.com/app/tutorial/vim
-
-- Node.js
-
-    + http://nodejs.org/api/
-
-- Linux
-
-    + http://www.quora.com/Linux/What-are-the-good-online-resources-for-a-linux-newbie
-
-    + http://www.quora.com/Linux/What-are-some-time-saving-tips-that-every-Linux-user-should-know
-
-    + http://kernelnewbies.org/
-
-
-
-Frequently asked questions
---------------------------
-
-**1. My internet speed is slow, ``$ vagrant up`` took a lot of time and reset to 0% after reaching
-more than 50%?**
-
-For slow internet connection (~200KB/s or lower), you could use a download accelerator to
-download ``.box`` file (400-500MB) first with the link:
-https://opscode-vm-bento.s3.amazonaws.com/vagrant/opscode_ubuntu-12.04-i386_chef-11.4.4.box
-
-And before ``$ vagrant up``, you must execute the command below:
-::
-
-    $ vagrant box add opscode-ubuntu-1204 path_to_the_downloaded_file.box
-
-If you're on Windows and downloaded the ``.box`` file to your ``Desktop``, then:
-::
-
-    $ vagrant box add opscode-ubuntu-1204 ~/Desktop/opscode_ubuntu-12.04-i386_chef-11.4.4.box
-
-The output could be something similar like this:
-::
-
-    Downloading or copying the box...
-    Extracting box...te: 66.3M/s, Estimated time remaining: 0:00:01)
-    Successfully added box 'opscode-ubuntu-1204' with provider 'virtualbox'!
-
-**2. What OS should I use for best development environment?**
-
-You could use any OS to start development (Windows XP, Windows 7, Windows 8, Mac,
-Ubuntu, etc.)
-
-However, Windows is NOT recommended for best development experience. It is better to work on any
-\*nix compatible OS (Mac OSX, Ubuntu, Fedora, Redhat, and more.)
-
-Ubuntu 12.04 is a **strongly** recommended OS for development, get it now at:
-http://www.ubuntu.com/download/desktop
-
-**3. After ``$ vagrant up``, there is an error saying that ``virtualbox`` has error, cannot run and
-quit immediately?**
-
-Make sure you install the exact version **4.3.12** of ``virtualbox``.
-
-**4. How could I update ``teracy-dev``?**
-
-We're trying to make the update as painless as possible so that we don't have to ``destroy`` and
-``up`` again as it is time consuming. We try to make the update with ``provision``, acceptable
-``reload``. If we have to ``destroy`` and ``up`` again, it will be the next major release version.
-
-Follow the command below and you're done:
-::
-
-    $ git pull
-
-
-**5. How to use ssh keys on the virtual machine**?
-
-
-``"vm_forward_agent":true`` is enabled by default. It means that we do not have to specify username
-and password each time when working with Git like ``pull, push, rebase, etc.``.
-
-However, if you want to use new created ssh keys for the Vagrant box, then you need to set
-``"vm_forward_agent":false`` on ``vagrant_config_override.json``.
-
-- Get ``teracy-dev/home/.ssh`` on the host machine and ``~/.ssh`` on the virtual machine in sync by
-adding this line on ``vagrant_config_override.json``:
-::
-
-    "vm_synced_folders":[
-      {
-        "host":"./workspace",
-        "guest":"/home/vagrant/workspace",
-        "mount_options":[
-          "dmode=775",
-          "fmode=664"
-        ]
-      },
-      //disable .virtualenvs mapping due to this: https://issues.teracy.org/browse/DEV-116
-      //to enable this, configure vm_sync_folders on vagrant_config_override.json
-      //WARNING: enable this will cause bad performance impact of the Python apps
-      // {
-      //   "host":"./home/.virtualenvs",
-      //   "guest":"/home/vagrant/.virtualenvs",
-      //   "supports": ["linux", "mac"],
-      //   "mount_options":[
-      //     "dmode=755",
-      //     "fmode=755"
-      //   ]
-      // },
-      //disable .ssh mapping due to this: https://issues.teracy.org/browse/DEV-162
-      {
-        "host":"./home/.ssh",
-        "guest":"/home/vagrant/.ssh",
-        "mount_options":[
-          "dmode=775",
-          "fmode=600"
-        ]
-      }
-    ],
-
-
-then ``$ vagrant reload``.
-
-After that you could copy your existing ssh keys into one location and it will be synced in both
-.ssh directories.
-
+License
+-------
 
-- Or create new ssh keys on the virtual machine, and these keys will be synced
-  into ``teracy-dev/home/.ssh``.
+BSD License
diff --git a/docs/advanced_usage.rst b/docs/advanced_usage.rst
@@ -0,0 +1,59 @@
+Advanced Usage
+==============
+
+This is for advanced usage, make sure to master the :doc:`basic_usage` guide first.
+
+Configuration
+-------------
+
+Sometimes, we need some customed configuration other than default configuration.
+
+So for easier upgrade and customed configuration, we use a json file named `vagrant_config_override.json`
+to override the default configuration on `vagrant_config.json` file.
+
+By using this, we can easily upgrade teracy-dev with ease, no conflicts introduced.
+
+
+For example, to use more memory for the VM, looking at the `vagrant_config.json` we could find:
+
+..  code-block:: javascript
+
+    "vb":{ //virtualbox settings from https://www.virtualbox.org/manual/ch08.html#vboxmanage-modifyvm
+      //"gui":true,
+      //"name":"teracy-dev",
+      "memory":2048,
+      //"cpus":1,
+      "description":"teracy-dev #{Time.now.getutc.to_i}"
+    }
+
+Now create `vagrant_config_override.json` file with the following content:
+
+..  code-block:: json
+
+    {
+      "vb":{
+        "memory":3072
+      }
+    }
+
+After that, ``$ vagrant reload``, then this override configuration will update the VM with *3072* MB
+of memory instead of default *2048* MB of memory.
+
+This applied the same for other configuration that you want to override. Under the hood, we merge
+the `vagrant_config_override.json` with `vagrant_config.json` to create the configuration settings.
+The configuration settings are then applied to the `Vagrantfile`.
+
+
+Upgrading
+---------
+
+To upgrade teracy-dev, just pull the latest changes from the git repo and you're set:
+
+.. code-block:: bash
+
+   $ cd ~/teracy-dev
+   $ git pull
+
+``$ vagrant reload --provision`` is used for improvements and bug fixes change upgrade.
+
+``$ vagrant destroy && vagrant up`` is used for next major version change upgrade.