Skip to content

Commit

Permalink
@ #167 | add getting started guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@hoatle
hoatle committed Dec 6, 2016
1 parent d61c9fd commit a676bc1
Show file tree
Hide file tree
Showing 4 changed files with 217 additions and 89 deletions.
4 changes: 4 additions & 0 deletions docs/advanced_usage.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Advanced Usage
==============

//TODO(hoatle): complete this
4 changes: 4 additions & 0 deletions docs/basic_usage.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Basic Usage
===========

// TODO(hoatle): complete this
296 changes: 207 additions & 89 deletions docs/getting_started.rst
View file
Original file line number Diff line number Diff line change
@@ -1,130 +1,228 @@
Getting Started
===============

To get started, you must follow the instruction steps below to set up the development environment.
``teracy-dev`` is created to set up an universal development platform which has the same development
workflow on Mac, Linux and Windows with good developer experience and productivity in mind.


Prerequisites
-------------
Please follow the installation instruction below, after that, the instruction step for teracy-dev
`git clone` and `vagrant up` is the same on all the platforms.

At Teracy, you need to install the tools below:

- ``virtualbox``
- ``vagrant``
- ``git``
- ``rsync``
.. note::

- The 64-bit architecture is used and run every day by us, however, the 32-bit archirecture is
expected to work, too.

- We recommend the following tested and supported platforms:

+ macOS Sierra
+ Ubuntu 16.04
+ Windows 10, Windows 8, Windows 7

Other platforms are expected to work, but we haven't fully tested them yet.


Automatic Installation on macOS
-------------------------------

// TODO(hoatle): https://github.com/teracyhq/dev/issues/162


Manual Installation on macOS
----------------------------

Check out the video and follow step by step instructions below:

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/htGqh_UyY_I" frameborder="0" allowfullscreen></iframe>

Open terminal window to:

1. Install ``Homebrew`` and ``Homebrew Cask``

- http://brew.sh/
- https://caskroom.github.io/

2. Install ``virtualbox`` and ``vagrant``

- Install ``virtualbox`` (>=5.1):

.. code-block:: bash
$ brew cask install virtualbox
- Install ``vagrant`` (>=1.8, <1.9):

.. code-block:: bash
$ brew cask install vagrant
.. note::

- If the above command installs ``vagrant`` >=1.9, make sure to install the right version by
downloading the installation file manually from https://releases.hashicorp.com/vagrant/

- // FIXME(hoatle): https://github.com/teracyhq/dev/issues/175


Automatic Installation on Linux (Ubuntu)
----------------------------------------

// TODO(hoatle): https://github.com/teracyhq/dev/issues/162


Manual Installation on Linux (Ubuntu)
-------------------------------------

Check out the video and follow step by step instructions below:

.. raw:: html

<iframe width="560" height="315" src="https://www.youtube.com/embed/MteK5c1r6B8" frameborder="0" allowfullscreen></iframe>

Open terminal window to:

1. Install ``git``

.. code-block:: bash
$ sudo apt-get update
$ sudo apt-get install -y git
2. Install ``virtualbox`` (>=5.1):

Find the right installation version file at https://www.virtualbox.org/wiki/Linux_Downloads or
https://www.virtualbox.org/wiki/Download_Old_Builds

on Mac
------
//TODO(hoatle)
.. code-block:: bash
on Linux
--------
//TODO(hoatle)
$ cd /tmp/
$ wget <download_link>
$ sudo dpkg -i <downloaded_file>
$ sudo apt-get install -r -y
on Windows
----------
//TODO(hoatle)
3. Install ``vagrant`` (>=1.8, <1.9):

- You MUST install ``cygwin`` to use ``git``, ``rsync``, from now on, it is called ``terminal window``.
Find the right installation version file at https://releases.hashicorp.com/vagrant/ or
https://www.vagrantup.com/downloads.html

.. code-block:: bash
Automatic Installation
----------------------
$ cd /tmp/
$ wget <download_link>
$ sudo dpkg -i <downloaded_file>
To install required packages automatically, you need run **Ubuntu** 12.04 and newer. If not, you
need to move to the next alternative instruction by installing required packages manually.
Installing ``git``, ``virtualbox``, ``vagrant`` with the provided bash script below:
Automatic Installation on Windows
---------------------------------

::
// TODO(hoatle): add this

$ cd /tmp && wget -qO- https://raw.github.com/teracyhq/dev/develop/scripts/setup_working_env_chef.sh | bash

On Windows (Windows 7, Windows 8 & Windows 10), follow these steps:
Manual Installation on Windows
------------------------------

1. Open: https://raw.github.com/teracyhq/dev/develop/scripts/setup_vagrant_and_virtualbox.bat on Chrome or Firefox.
This should be the same on Windows 10, Windows 8 and Windows 7.

2. Press ``Ctrl + S``.
Check out the video and follow step by step instructions below:

3. Select the option ``Save as type: Text document``, with the name "setup_vagrant_and_virtualbox.bat" (notice the double quote).
.. raw:: html

4. Open it by double-clicking on ``setup_vagrant_and_virtualbox.bat``.
<iframe width="560" height="315" src="https://www.youtube.com/embed/SBOoUIVI3Jw" frameborder="0" allowfullscreen></iframe>

Now you should have ``vagrant`` and ``virtualbox`` installed on your system.

1. Install ``chocolatey``

Manual Installation
-------------------
Run ``Command Prompt`` as administrator and paste the Cmd.exe command from
https://chocolatey.org/install

1. Install the latest ``cygwin`` version at https://www.cygwin.com/ and choose to install the
following packages:
2. Install ``cyg-get``

Type the command below on the opened ``Command Prompt``:

- bash
- bash-completion
- git
- openssh
- rsync
.. code-block:: bash
2. Install ``virtualbox`` with the exact version of **5.1.8** (or newer) at
https://www.virtualbox.org/wiki/Downloads.
> choco install cyg-get -y
3. Install ``bash-completion``, ``git``, ``virtualbox`` and ``vagrant``

Run ``Cygwin Terminal`` as administrator with the following commands:

- Install ``bash-completion``:

.. code-block:: bash
$ cyg-get.bat bash-completion
- Install ``git``:

.. code-block:: bash
$ cyg-get.bat git
- Install ``virtualbox``:

.. code-block:: bash
$ choco install virtualbox -y
- Install ``vagrant``:

.. code-block:: bash
$ choco install vagrant -y
3. Install ``vagrant`` with the exact version of **1.8.7** (or newer) at
https://releases.hashicorp.com/vagrant/1.8.7/.
.. note::

- The 64-bit architecture is used and run every day by us, however, the 32-bit archirecture is
expected to work, too.
- If you encounter the following error:

- The virtualbox has an installation issue which is reported `here
<https://www.virtualbox.org/ticket/4140>`_. If you `$ vagrant up` but can not start the
virtual box, please find "VBoxUSBMon.inf" & "VBoxDrv.inf" in your installation directory and
re-install it to fix the issue.
.. code-block:: bash
Git Setup
---------
C:\ProgramData\chocolatey\lib\cyg-get\tools\cyg-get.ps1 : Please ensure you have Cygwin installed.
To install please call 'choco install cygwin' (optionally add -y to autoconfirm).
ERROR: This command cannot be run due to the error: The system cannot find the file specified.
At line:1 char:1
then fix it with: https://github.com/chocolatey/chocolatey-coreteampackages/issues/176#issuecomment-212939458

Complete the following guides to get it work:
- If you ``$ vagrant up`` but can not start the VirtualBox, please find "VBoxUSBMon.inf" and
"VBoxDrv.inf" in your installation directory then re-install it to fix the issue. The
VirtualBox has an installation issue which was reported `here <https://www.virtualbox.org/ticket/4140>`_

- https://help.github.com/categories/ssh/


Environment Up
--------------
teracy-dev Git Clone and Vagrant Up
-----------------------------------

1. Open your terminal window and type:
::

.. code-block:: bash
$ cd ~/
$ git clone https://github.com/teracyhq/dev.git teracy-dev
$ cd teracy-dev
$ git checkout develop
$ vagrant up
.. note::

- The home directory on ``Git Bash`` normally should point to your user's directory on windows.
For example: ``C:\Documents and Settings\<user_name>``, this is the place you will find
``teracy-dev`` directory to import projects into your text editor later for coding.

- You may see the error:
.. note::

.. code-block:: bash
We checkout the `develop` branch here to use the latest development version of teracy-dev.
When it is released, we will use the `master` branch - the latest stable version instead.

Vagrant uses the `VBoxManage` binary that ships with VirtualBox, and requires this to be
available on the PATH. If VirtualBox is installed, please find the `VBoxManage` binary and
add it to the PATH environmental variable.
You could see the error message saying that `vagrant-gatling-rsync` and `vagrant-rsync-back`
plugins are required, so install them:

To fix this error, add the path of the **VirtualBox** folder to your environment variable.
.. code-block:: bash
For example: In Windows, add this ``C:\Program Files\Oracle\VirtualBox``.
$ vagrant plugin install vagrant-gatling-rsync
$ vagrant plugin install vagrant-rsync-back
If the error still occurs, you have to unistall and re-install VirtualBox, then Vagrant to fix
this error.
You should see the following similar messages after ``$ vagrant up`` finishes running:
::
You should see the following similar messages after ``$ vagrant up`` finishes running:
::

==> default: [2016-11-25T06:02:16+00:00] INFO: Report handlers complete
==> default: Chef Client finished, 9/15 resources updated in 03 minutes 36 seconds
Expand All @@ -134,27 +232,47 @@ Environment Up
==> default: ip address: 192.168.0.105
==> default: vagrant-gatling-rsync is starting the sync engine because you have at least one rsync folder. To disable this behavior, set `config.gatling.rsync_on_startup = false` in your Vagrantfile.
==> default: Doing an initial rsync...
==> default: Rsyncing folder: /Users/hoatle/teracy-dev-docker/workspace/teracy-dev/workspace/ => /home/vagrant/workspace
==> default: Rsyncing folder: /Users/hoatle/teracy-dev/workspace/ => /home/vagrant/workspace
==> default: - Exclude: [".vagrant/", ".git", ".idea/", "node_modules/", "bower_components/", ".npm/"]


.. note::

- You may see the error:
::

vagrant uses the VBoxManage binary that ships with VirtualBox, and requires this to be
available on the PATH. If VirtualBox is installed, please find the VBoxManage binary and
add it to the PATH environmental variable.

To fix this error, add the path of the **VirtualBox** folder to your environment variable.

For example: In Windows, add this ``C:\Program Files\Oracle\VirtualBox``.

If the error still occurs, you have to unistall and re-install ``virtualbox``, then
``vagrant`` to fix this error.

2. Use the ``$ vagrant ssh`` command to access the virtual machine you have just
installed which runs Ubuntu 12.04 with ssh. You should see the following similar messages:
::
provisioned. You should see the following similar messages:

.. code-block:: bash
Welcome to Ubuntu 14.04.5 LTS (GNU/Linux 3.13.0-101-generic x86_64)
Welcome to Ubuntu 16.04.1 LTS (GNU/Linux 4.4.0-51-generic x86_64)
* Documentation: https://help.ubuntu.com/
* Documentation: https://help.ubuntu.com
* Management: https://landscape.canonical.com
* Support: https://ubuntu.com/advantage
System information as of Fri Nov 25 06:02:18 UTC 2016
1 package can be updated.
1 update is a security update.
System load: 0.79 Users logged in: 0
Usage of /: 5.6% of 39.34GB IP address for eth0: 10.0.2.15
Memory usage: 10% IP address for eth1: 192.168.0.105
Swap usage: 0% IP address for docker0: 172.17.0.1
Processes: 89
Graph this data and manage this system at:
https://landscape.canonical.com/
Last login: Tue Dec 6 14:19:56 2016 from 10.0.2.2
Git Setup
---------

To work with ``git``, complete the following guides to set up ssh keys:
https://help.github.com/categories/ssh/

Get cloud support with Ubuntu Advantage Cloud Guest:
http://www.ubuntu.com/business/services/cloud
*Congratulations, you’ve all set now!*
2 changes: 2 additions & 0 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ Contents:

intro
getting_started
basic_usage
advanced_usage
tool_chain
built_in_ide
style_standards
Expand Down

0 comments on commit a676bc1

Please sign in to comment.