docs: extend install docs

e924562a · Őry Máté · c12a5e67 · e924562a
Commit e924562a authored May 08, 2014 by Őry Máté
Show whitespace changes
Inline Side-by-side

Showing with 57 additions and 52 deletions

docs/install.rst
+57 -52

No files found.
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -3,31 +3,36 @@ Installation of a development machine
 .. 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
 -----------
-To get the project running on a development machine, create a new Ubuntu 12.04
+To get the project running on a development machine, launch a new Ubuntu
-instance, and log in to it over SSH.
+12.04 or 14.04 machine, and log in to it over SSH.
 To use *git* over *SSH*, we advise enabling SSH *agent forwarding*.
-On your personal computer check if *ssh-agent* is running (the command should
+On your terminal computer check if *ssh-agent* is running (the command
-print a process id)::
+should print a process id)::
  $ echo $SSH_AGENT_PID
  1234
-If it is not running, you should set up your login manager or some other
+If it is not running, you can configure your dektop environment to
-solution to automatically launch it.
+automatically launch it.
 Add your private key to the agent (if it is not added by your desktop
 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::
-  $ ssh -A cloud@host
+  ssh -A cloud@host
 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
  change it, because RabbitMQ won't work with it. ::
-    $ old=$(hostname)
+    old=$(hostname)
-    $ new=c-${old}
+    new=c-${old}
-    $ sudo tee /etc/hostname <<<$new
+    sudo tee /etc/hostname <<<$new
-    $ sudo hostname $new
+    sudo hostname $new
-    $ sudo sed -i /etc/hosts -e "s/$old/$new/g"
+    sudo sed -i /etc/hosts -e "s/$old/$new/g"
 Setting up required software
 ----------------------------
 Update the package lists, and install the required system software::
-  $ sudo apt-get update
+  sudo apt-get update
-  $ sudo apt-get install --yes virtualenvwrapper postgresql git \
+  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::
-  $ sudo sed -i /etc/postgresql/9.1/main/postgresql.conf -e '/#listen_addresses/ s/^#//'
+  sudo sed -i /etc/postgresql/9.1/main/postgresql.conf -e '/#listen_addresses/ s/^#//'
-  $ sudo /etc/init.d/postgresql restart
+  sudo /etc/init.d/postgresql restart
 Also, create a new database and user::
-  $ sudo -u postgres createuser -S -D -R circle
+  sudo -u postgres createuser -S -D -R circle
-  $ sudo -u postgres psql <<<"ALTER USER circle WITH PASSWORD 'circle';"
+  sudo -u postgres psql <<<"ALTER USER circle WITH PASSWORD 'circle';"
-  $ sudo -u postgres createdb circle -O circle
+  sudo -u postgres createdb circle -O circle
 Configure RabbitMQ: remove the guest user, add virtual host and user with
 proper permissions::
-  $ sudo rabbitmqctl delete_user guest
+  sudo rabbitmqctl delete_user guest
-  $ sudo rabbitmqctl add_vhost circle
+  sudo rabbitmqctl add_vhost circle
-  $ sudo rabbitmqctl add_user cloud password
+  sudo rabbitmqctl add_user cloud password
-  $ sudo rabbitmqctl set_permissions -p circle cloud '.*' '.*' '.*'
+  sudo rabbitmqctl set_permissions -p circle cloud '.*' '.*' '.*'
 Enable SSH server to accept your name and address from your environment::
-  $ sudo sed -i /etc/ssh/sshd_config -e '$ a AcceptEnv GIT_*'
+  sudo sed -i /etc/ssh/sshd_config -e '$ a AcceptEnv GIT_*'
-  $ sudo /etc/init.d/ssh reload
+  sudo /etc/init.d/ssh reload
 You should set these vars in your **local** profile::
-  $ cat >>~/.profile <<'END'
+  cat >>~/.profile <<'END'
  export GIT_AUTHOR_NAME="Your Name"
  export GIT_AUTHOR_EMAIL="your.address@example.org"
  export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
  export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
  END
-  $ source ~/.profile
+  source ~/.profile
 Allow sending it in your **local** ssh configuration::
@@ -100,17 +105,17 @@ Setting up Circle itself
 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
 project::
-  $ source /etc/bash_completion.d/virtualenvwrapper
+  source /etc/bash_completion.d/virtualenvwrapper
-  $ mkvirtualenv circle
+  mkvirtualenv circle
 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_DB_HOST=localhost
  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 CACHE_URI='pylibmc://127.0.0.1:11211/'
  END
-  $ workon circle
+  workon circle
-  $ cd ~/circle
+  cd ~/circle
 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::
-  $ circle/manage.py syncdb --all --noinput
+  circle/manage.py syncdb --all --noinput
-  $ circle/manage.py migrate --fake
+  circle/manage.py migrate --fake
-  $ circle/manage.py createsuperuser --username=test --email=test@example.org 
+  circle/manage.py createsuperuser --username=test --email=test@example.org 
 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::
-  $ circle/manage.py celery worker -A manager.mancelery
+  circle/manage.py celery worker -A manager.mancelery
 .. note::
  You might run the Celery worker (and also the development server) in GNU
  Screen, or use Upstart::
-    $ sudo cp miscellaneous/mancelery.conf /etc/init/
+    sudo cp miscellaneous/mancelery.conf /etc/init/
-    $ sudo start mancelery
+    sudo start mancelery
 Building documentation
 ----------------------
@@ -153,14 +158,14 @@ Building documentation
 To build the *docs*, install *make*, go to the docs folder, and run the building
 process. ::
-  $ sudo apt-get install make
+  sudo apt-get install make
-  $ cd ~/circle/docs/
+  cd ~/circle/docs/
-  $ make html
+  make html
 You might also want to serve the generated docs with Python's development
 server::
-  $ (cd _build/html && python -m SimpleHTTPServer 8080)
+  (cd _build/html && python -m SimpleHTTPServer 8080)
 Configuring vim
 ---------------
@@ -168,16 +173,16 @@ Configuring vim
 To follow the coding style of the project more easily, you might want to
 configure vim like we do::
-  $ mkdir -p ~/.vim/autoload ~/.vim/bundle
+  mkdir -p ~/.vim/autoload ~/.vim/bundle
-  $ curl -Sso ~/.vim/autoload/pathogen.vim \
+  curl -Sso ~/.vim/autoload/pathogen.vim \
-          https://raw.githubusercontent.com/tpope/vim-pathogen/master/autoload/pathogen.vim
+      https://raw.github.com/tpope/vim-pathogen/master/autoload/pathogen.vim
-  $ cd ~/.vim; mkdir -p bundle; cd bundle && git clone \
+  cd ~/.vim; mkdir -p bundle; cd bundle && git clone \
      git://github.com/klen/python-mode.git
-  $ cat >>~/.vimrc <<END
+  cat >>~/.vimrc <<END
      filetype off
      call pathogen#infect()
      call pathogen#helptags()
      filetype plugin indent on
      syntax on
  END
-  $ sudo pip install pyflakes rope pep8 mccabe
+  sudo pip install pyflakes rope pep8 mccabe