docs: extend install docs

docs/install.rst

@@ -3,31 +3,36 @@ Installation of a development machine
 
 
 .. highlight:: bash
 .. highlight:: bash
 
 
+This tutorial describes the installation of a development environment. To
+have a fully working environment, you have to set up the other components
+as well. The full procedure is included in the :doc:`Puppet recipes
+<puppet>` available for CIRCLE Cloud.
+
 Preparation
 Preparation
 -----------
 -----------
 
 
-To get the project running on a development machine, create a new Ubuntu 12.04
-instance, and log in to it over SSH.
+To get the project running on a development machine, launch a new Ubuntu
+12.04 or 14.04 machine, and log in to it over SSH.
 
 
 
 
 To use *git* over *SSH*, we advise enabling SSH *agent forwarding*.
 To use *git* over *SSH*, we advise enabling SSH *agent forwarding*.
-On your personal computer check if *ssh-agent* is running (the command should
-print a process id)::
+On your terminal computer check if *ssh-agent* is running (the command
+should print a process id)::
   
   
   $ echo $SSH_AGENT_PID
   $ echo $SSH_AGENT_PID
   1234
   1234
 
 
-If it is not running, you should set up your login manager or some other
-solution to automatically launch it.
+If it is not running, you can configure your dektop environment to
+automatically launch it.
 
 
 Add your private key to the agent (if it is not added by your desktop
 Add your private key to the agent (if it is not added by your desktop
 environment)::
 environment)::
 
 
-  $ ssh-add [~/.ssh/path_to_id_rsa]
+  ssh-add [~/.ssh/path_to_id_rsa]
 
 
 Log in to the new vm. The :kbd:`-A` switch enables agent forwarding::
 Log in to the new vm. The :kbd:`-A` switch enables agent forwarding::
 
 
-  $ ssh -A cloud@host
+  ssh -A cloud@host
 
 
 You can check agent forwarding on the vm::
 You can check agent forwarding on the vm::
 
 
@@ -38,55 +43,55 @@ You can check agent forwarding on the vm::
   If the first character of the hostname of the vm is a digit, you have to
   If the first character of the hostname of the vm is a digit, you have to
   change it, because RabbitMQ won't work with it. ::
   change it, because RabbitMQ won't work with it. ::
  
  
-    $ old=$(hostname)
-    $ new=c-${old}
-    $ sudo tee /etc/hostname <<<$new
-    $ sudo hostname $new
-    $ sudo sed -i /etc/hosts -e "s/$old/$new/g"
+    old=$(hostname)
+    new=c-${old}
+    sudo tee /etc/hostname <<<$new
+    sudo hostname $new
+    sudo sed -i /etc/hosts -e "s/$old/$new/g"
 
 
 Setting up required software
 Setting up required software
 ----------------------------
 ----------------------------
 
 
 Update the package lists, and install the required system software::
 Update the package lists, and install the required system software::
 
 
-  $ sudo apt-get update
-  $ sudo apt-get install --yes virtualenvwrapper postgresql git \
-      python-pip rabbitmq-server libpq-dev python-dev ntp memcached \
-      libmemcached-dev
+  sudo apt-get update
+  sudo apt-get install --yes virtualenvwrapper postgresql git \
+    python-pip rabbitmq-server libpq-dev python-dev ntp memcached \
+    libmemcached-dev
 
 
 Set up *PostgreSQL* to listen on localhost and restart it::
 Set up *PostgreSQL* to listen on localhost and restart it::
 
 
-  $ sudo sed -i /etc/postgresql/9.1/main/postgresql.conf -e '/#listen_addresses/ s/^#//'
-  $ sudo /etc/init.d/postgresql restart
+  sudo sed -i /etc/postgresql/9.1/main/postgresql.conf -e '/#listen_addresses/ s/^#//'
+  sudo /etc/init.d/postgresql restart
 
 
 Also, create a new database and user::
 Also, create a new database and user::
 
 
-  $ sudo -u postgres createuser -S -D -R circle
-  $ sudo -u postgres psql <<<"ALTER USER circle WITH PASSWORD 'circle';"
-  $ sudo -u postgres createdb circle -O circle
+  sudo -u postgres createuser -S -D -R circle
+  sudo -u postgres psql <<<"ALTER USER circle WITH PASSWORD 'circle';"
+  sudo -u postgres createdb circle -O circle
 
 
 Configure RabbitMQ: remove the guest user, add virtual host and user with
 Configure RabbitMQ: remove the guest user, add virtual host and user with
 proper permissions::
 proper permissions::
 
 
-  $ sudo rabbitmqctl delete_user guest
-  $ sudo rabbitmqctl add_vhost circle
-  $ sudo rabbitmqctl add_user cloud password
-  $ sudo rabbitmqctl set_permissions -p circle cloud '.*' '.*' '.*'
+  sudo rabbitmqctl delete_user guest
+  sudo rabbitmqctl add_vhost circle
+  sudo rabbitmqctl add_user cloud password
+  sudo rabbitmqctl set_permissions -p circle cloud '.*' '.*' '.*'
 
 
 Enable SSH server to accept your name and address from your environment::
 Enable SSH server to accept your name and address from your environment::
 
 
-  $ sudo sed -i /etc/ssh/sshd_config -e '$ a AcceptEnv GIT_*'
-  $ sudo /etc/init.d/ssh reload
+  sudo sed -i /etc/ssh/sshd_config -e '$ a AcceptEnv GIT_*'
+  sudo /etc/init.d/ssh reload
 
 
 You should set these vars in your **local** profile::
 You should set these vars in your **local** profile::
 
 
-  $ cat >>~/.profile <<'END'
+  cat >>~/.profile <<'END'
   export GIT_AUTHOR_NAME="Your Name"
   export GIT_AUTHOR_NAME="Your Name"
   export GIT_AUTHOR_EMAIL="your.address@example.org"
   export GIT_AUTHOR_EMAIL="your.address@example.org"
   export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
   export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
   export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
   export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
   END
   END
-  $ source ~/.profile
+  source ~/.profile
 
 
 Allow sending it in your **local** ssh configuration::
 Allow sending it in your **local** ssh configuration::
 
 
@@ -100,17 +105,17 @@ Setting up Circle itself
 
 
 Clone the git repository::
 Clone the git repository::
 
 
-  $ git clone git@git.cloud.ik.bme.hu:circle/cloud.git circle
+  git clone git@git.cloud.ik.bme.hu:circle/cloud.git circle
 
 
 Set up *virtualenvwrapper* and the *virtual Python environment* for the
 Set up *virtualenvwrapper* and the *virtual Python environment* for the
 project::
 project::
 
 
-  $ source /etc/bash_completion.d/virtualenvwrapper
-  $ mkvirtualenv circle
+  source /etc/bash_completion.d/virtualenvwrapper
+  mkvirtualenv circle
 
 
 Set up default Circle configuration and activate the virtual environment::
 Set up default Circle configuration and activate the virtual environment::
 
 
-  $ cat >>/home/cloud/.virtualenvs/circle/bin/postactivate <<END
+  cat >>/home/cloud/.virtualenvs/circle/bin/postactivate <<END
   export DJANGO_SETTINGS_MODULE=circle.settings.local
   export DJANGO_SETTINGS_MODULE=circle.settings.local
   export DJANGO_DB_HOST=localhost
   export DJANGO_DB_HOST=localhost
   export DJANGO_DB_PASSWORD=circle
   export DJANGO_DB_PASSWORD=circle
@@ -120,32 +125,32 @@ Set up default Circle configuration and activate the virtual environment::
   export AMQP_URI='amqp://cloud:password@localhost:5672/circle'
   export AMQP_URI='amqp://cloud:password@localhost:5672/circle'
   export CACHE_URI='pylibmc://127.0.0.1:11211/'
   export CACHE_URI='pylibmc://127.0.0.1:11211/'
   END
   END
-  $ workon circle
-  $ cd ~/circle
+  workon circle
+  cd ~/circle
 
 
 Install the required Python libraries to the virtual environment::
 Install the required Python libraries to the virtual environment::
 
 
-  $ pip install -r requirements/local.txt
+  pip install -r requirements/local.txt
 
 
 Sync the database and create a superuser::
 Sync the database and create a superuser::
 
 
-  $ circle/manage.py syncdb --all --noinput
-  $ circle/manage.py migrate --fake
-  $ circle/manage.py createsuperuser --username=test --email=test@example.org 
+  circle/manage.py syncdb --all --noinput
+  circle/manage.py migrate --fake
+  circle/manage.py createsuperuser --username=test --email=test@example.org 
 
 
 You can now start the development server::
 You can now start the development server::
 
 
-  $ circle/manage.py runserver '[::]:8080'
+  circle/manage.py runserver '[::]:8080'
 
 
 You will also need to run a local Celery worker::
 You will also need to run a local Celery worker::
 
 
-  $ circle/manage.py celery worker -A manager.mancelery
+  circle/manage.py celery worker -A manager.mancelery
 
 
 .. note::
 .. note::
   You might run the Celery worker (and also the development server) in GNU
   You might run the Celery worker (and also the development server) in GNU
   Screen, or use Upstart::
   Screen, or use Upstart::
-    $ sudo cp miscellaneous/mancelery.conf /etc/init/
-    $ sudo start mancelery
+    sudo cp miscellaneous/mancelery.conf /etc/init/
+    sudo start mancelery
 
 
 Building documentation
 Building documentation
 ----------------------
 ----------------------
@@ -153,14 +158,14 @@ Building documentation
 To build the *docs*, install *make*, go to the docs folder, and run the building
 To build the *docs*, install *make*, go to the docs folder, and run the building
 process. ::
 process. ::
 
 
-  $ sudo apt-get install make
-  $ cd ~/circle/docs/
-  $ make html
+  sudo apt-get install make
+  cd ~/circle/docs/
+  make html
 
 
 You might also want to serve the generated docs with Python's development
 You might also want to serve the generated docs with Python's development
 server::
 server::
 
 
-  $ (cd _build/html && python -m SimpleHTTPServer 8080)
+  (cd _build/html && python -m SimpleHTTPServer 8080)
 
 
 Configuring vim
 Configuring vim
 ---------------
 ---------------
@@ -168,16 +173,16 @@ Configuring vim
 To follow the coding style of the project more easily, you might want to
 To follow the coding style of the project more easily, you might want to
 configure vim like we do::
 configure vim like we do::
   
   
-  $ mkdir -p ~/.vim/autoload ~/.vim/bundle
-  $ curl -Sso ~/.vim/autoload/pathogen.vim \
-          https://raw.githubusercontent.com/tpope/vim-pathogen/master/autoload/pathogen.vim
-  $ cd ~/.vim; mkdir -p bundle; cd bundle && git clone \
-        git://github.com/klen/python-mode.git
-  $ cat >>~/.vimrc <<END
+  mkdir -p ~/.vim/autoload ~/.vim/bundle
+  curl -Sso ~/.vim/autoload/pathogen.vim \
+      https://raw.github.com/tpope/vim-pathogen/master/autoload/pathogen.vim
+  cd ~/.vim; mkdir -p bundle; cd bundle && git clone \
+      git://github.com/klen/python-mode.git
+  cat >>~/.vimrc <<END
       filetype off
       filetype off
       call pathogen#infect()
       call pathogen#infect()
       call pathogen#helptags()
       call pathogen#helptags()
       filetype plugin indent on
       filetype plugin indent on
       syntax on
       syntax on
   END
   END
-  $ sudo pip install pyflakes rope pep8 mccabe
+  sudo pip install pyflakes rope pep8 mccabe