Skip to content
Browse files

fix bug 634263: updates to installation docs

* installation.rst markup fixes.

* Create development.rst with common tips.

* Also move tips that apply to vagrant VM from installation.rst to
  development.rst.

* Move README-vagrant.md to docs/ and convert to rst.
  Per https://bugzilla.mozilla.org/show_bug.cgi?id=634263#c5

* Improve installation-vagrant.rst docs.

    * Note that core kuma devs use this method.
    * Don't insist on using gem, while pointing to vagrantup.com, since they
      recommend using DMGs
    * Advice again using the same working directory as for the local
      installation, since that wipes out settings_local.py and breaks
      because of symlinks (e.g. media/uploads) that are host-dependent.
    * Fix the puppet manifest filename to match reality (dev-vagrant.pp)
    * Mention dekiwiki availability, link to development.rst

* Update vagrant motd to mention the proper way to run tests.
  • Loading branch information...
1 parent d087b8e commit 20a72efddebf9702cea587356ce9d4ea1cb55ef1 @nickolay nickolay committed with lmorchard
Showing with 230 additions and 134 deletions.
  1. +0 −97 README-vagrant.md
  2. +97 −0 docs/development.rst
  3. +118 −0 docs/installation-vagrant.rst
  4. +11 −37 docs/installation.rst
  5. +4 −0 puppet/files/etc/motd
View
97 README-vagrant.md
@@ -1,97 +0,0 @@
-# Kuma in VirtualBox via Vagrant
-
-This is an attempt to describe the bootstrap process to get Kuma running in a
-Vagrant-managed virtual machine.
-
-This is known to work on Mac OS X. It could possibly be made to work under
-Linux and Windows, but few have tried. Bug reports and suggestions are
-welcome. The main barrier to Windows is that this Vagrantfile
-[uses NFS to share the current working directory][nfs] for performance
-reasons, and also Vagrant support for Windows is not-so-great yet.
-
-[nfs]: http://vagrantup.com/docs/nfs.html
-
-## Getting up and running
-
-* Install VirtualBox 4 from http://www.virtualbox.org/
-
-* Install vagrant from a Terminal window, see vagrantup.com:
-
- gem update
- gem install vagrant
-
-* Clone Kuma, update submodules:
-
- git clone git://github.com/mozilla/kuma.git
- cd kuma
- git submodule update --init --recursive
-
-* Create a `vagrantconfig_local.yaml` file to configure your VM:
-
- cp vagrantconfig_local.yaml-dist vagrantconfig_local.yaml
-
- This may have some interesting settings for you to tweak, but the
- defaults should work fine.
-
-* Fire up the VM and install everything, go take a bike ride (approx.
- 30 min on a fast net connection):
-
- vagrant up
-
-* If the process fails with an error, try running the Puppet setup again:
-
- vagrant provision
-
- This often recovers from transient network issues or installation
- ordering problems.
-
-* Add developer-dev.mozilla.org to /etc/hosts:
-
- echo '192.168.10.55 developer-dev.mozilla.org' >> /etc/hosts
-
-* Everything should be working now, frmo the host side.
-
- curl 'http://developer-dev.mozilla.org'
-
-* You should be able to log into a shell in the VM as the user `vagrant`:
-
- vagrant ssh
-
-## What's next?
-
-* Django and node.js web services must be started within the VM by hand,
- which makes them easier to restart during development. Details on this
- should be displayed via `/etc/motd` when you log in with `vagrant ssh`
-
-* Edit files as usual on your host machine; the current directory is
- mounted via NFS at /vagrant within the VM. Update should be reflected
- without any action on your part.
-
-* Useful vagrant sub-commands:
-
- vagrant ssh # Connect to the VM via ssh
- vagrant suspend # Sleep the VM, saving state
- vagrant halt # Shutdown the VM
- vagrant up # Boot up the VM
- vagrant destroy # Destroy the VM
-
-* You should occasionally re-run the Puppet setup, especially after
- updating code with major changes. This will ensure that the VM
- environment stays up to date with configuration changes and
- installation of additional services.
-
- * On the Host:
-
- vagrant provision
-
- * Inside the VM:
-
- sudo puppet apply /vagrant/puppet/manifests/dev-vagrant-mdn.pp
-
-* **Experimental and Optional**: Download and import data extracted and
- sanitized from the production site. This can take a long while, since
- there's over 500MB of data to download.
-
- vagrant ssh
- sudo puppet apply /vagrant/puppet/manifests/dev-vagrant-mdn-import.pp
- sudo puppet apply /vagrant/puppet/manifests/dev-vagrant.pp
View
97 docs/development.rst
@@ -0,0 +1,97 @@
+============
+Development
+============
+
+After you have completed the `manual installation steps <installation.rst>`_
+or set up the `Vagrant-managed VM <installation-vagrant.rst>`_), and are able
+to run Kuma using ``./manage.py runserver``, you can start contributing.
+
+Running Kuma
+============
+
+In addition to running the django app using ``./manage.py runserver``, you can run
+the kumascript service to enable wiki templates processing::
+
+ node kumascript/run.js
+
+...and `celery <celery.rst>`_ to enable background task processing (such as sending
+the e-mail notifications).
+
+Log in
+------
+
+You can log into the wiki using BrowserID or via the django admin interface.
+If you use the admin interface, you can log in as the user you created during installation
+or on the vagrant VM use login ``admin`` with password ``admin``.
+
+Set up permissions
+------------------
+
+Some features are only available to privileged users. To manage permissions use the
+Auth -> Users section of the django admin interface.
+
+Hacking on bleeding edge features
+=================================
+To hack on the features not yet ready for production you have to enable them first.
+
+Enable kumawiki in waffle
+-------------------------
+
+The Kuma wiki is disabled by default using `django-waffle`_. To test out the wiki,
+open the django admin interface (``http://.../admin/``) and add a ``kumawiki`` flag
+in the Waffle section.
+
+Note that features disabled by a flag will show up as a 404 error.
+
+.. _django-waffle: https://github.com/jsocol/django-waffle
+
+Enable Kumascript
+-----------------
+
+Kuma uses a separate nodejs-based service to process templates in wiki pages. Its
+use is disabled by default, to enable: open the django admin interface and in the
+Constance section change the value of ``KUMASCRIPT_TIMEOUT`` parameter to a positive
+value (such as ``2.0`` seconds).
+
+Running the Tests
+=================
+
+A great way to check that everything really is working is to run the test
+suite.
+
+Django tests
+------------
+If you're not using the vagrant VM, you'll need to add an extra grant in MySQL for
+your database user::
+
+ GRANT ALL ON test_NAME.* TO USER@localhost;
+
+Where ``NAME`` and ``USER`` are the same as the values in your database
+configuration.
+
+The test suite will create and use this database, to keep any data in your
+development database safe from tests.
+
+Running the test suite is easy::
+
+ ./manage.py test -s --noinput --logging-clear-handlers
+
+Note that this will try (and fail) to run tests that depend on apps disabled
+via ``INSTALLED_APPS``. You should run a subset of tests specified in
+`scripts/build.sh <../scripts/build.sh>`_, at the bottom of the script.
+
+When using the vagrant VM you must `run the tests from the root folder`_, not from
+``/vagrant``::
+
+ (cd / && /vagrant/manage.py test ...)
+
+For more information, see the `test documentation <tests.rst>`_.
+
+.. _run the tests from the root folder: https://bugzilla.mozilla.org/show_bug.cgi?id=756536#c2
+
+Kumascript tests
+----------------
+
+If you're changing Kumascript, be sure to run its tests too.
+See https://github.com/mozilla/kumascript
+
View
118 docs/installation-vagrant.rst
@@ -0,0 +1,118 @@
+Kuma in VirtualBox via Vagrant
+==============================
+
+The core developers run Kuma in a `Vagrant`_-managed virtual machine to
+simplify `installation <installation.rst>`_.
+If you're on Mac OS X and looking for a quick way to get started, you
+should try these instructions.
+
+This could possibly be made to work under Linux and Windows, but few have
+tried. Bug reports and suggestions are welcome.
+The main barrier to Windows is that this Vagrantfile `uses NFS to share
+the current working directory`_ for performance reasons, and also Vagrant
+support for Windows is not-so-great yet.
+
+.. _vagrant: http://vagrantup.com/
+.. _uses NFS to share the current working directory: http://vagrantup.com/docs/nfs.html
+
+
+Getting up and running
+----------------------
+
+- Install VirtualBox 4 from http://www.virtualbox.org/
+- Install vagrant using ``gem`` from a Terminal window, or by downloading
+ a package from `vagrantup.com`_. ::
+
+ gem update
+ gem install vagrant
+
+.. _vagrantup.com: http://vagrantup.com/
+
+- Clone Kuma, update submodules (**don't** try to use the same working
+ directory as for the local installation)::
+
+ git clone git://github.com/mozilla/kuma.git
+ cd kuma
+ git submodule update --init --recursive
+
+- Create a ``vagrantconfig_local.yaml`` file to configure your VM::
+
+ cp vagrantconfig_local.yaml-dist vagrantconfig_local.yaml
+
+ This may have some interesting settings for you to tweak, but the
+ defaults should work fine.
+
+- Fire up the VM and install everything, go take a bike ride (approx.
+ 30 min on a fast net connection)::
+
+ vagrant up
+
+- If the process fails with an error, try running the Puppet setup
+ again::
+
+ vagrant provision
+
+ This often recovers from transient network issues or installation
+ ordering problems.
+
+- Add developer-dev.mozilla.org to /etc/hosts::
+
+ echo '192.168.10.55 developer-dev.mozilla.org' >> /etc/hosts
+
+- Everything should be working now, from the host side::
+
+ curl 'http://developer-dev.mozilla.org'
+
+- You should be able to log into a shell in the VM as the user
+ ``vagrant``::
+
+ vagrant ssh
+
+What’s next?
+------------
+
+- See `development <development.rst>`_ for tips not specific to vagrant.
+
+- Django and node.js web services must be started within the VM by
+ hand, which makes them easier to restart during development. Details
+ on this should be displayed via ``/etc/motd`` when you log in with
+ ``vagrant ssh``
+
+- Edit files as usual on your host machine; the current directory is
+ mounted via NFS at /vagrant within the VM. Update should be reflected
+ without any action on your part.
+
+- Useful vagrant sub-commands::
+
+ vagrant ssh # Connect to the VM via ssh
+ vagrant suspend # Sleep the VM, saving state
+ vagrant halt # Shutdown the VM
+ vagrant up # Boot up the VM
+ vagrant destroy # Destroy the VM
+
+- You should occasionally re-run the Puppet setup, especially after
+ updating code with major changes. This will ensure that the VM
+ environment stays up to date with configuration changes and
+ installation of additional services.
+
+ - On the Host::
+
+ vagrant provision
+
+ - Inside the VM::
+
+ sudo puppet apply /vagrant/puppet/manifests/dev-vagrant.pp
+
+- The VM comes with MindTouch wiki (the one that powers the production
+ developer.mozilla.org site) installed. Visit http://developer-dev.mozilla.org/en/Test
+ after you log in to create a page in it.
+
+- **Experimental and Optional**: Download and import data extracted and
+ sanitized from the production site. This can take a long while, since
+ there’s over 500MB of data to download. ::
+
+ vagrant ssh
+ sudo puppet apply /vagrant/puppet/manifests/dev-vagrant-mdn-import.pp
+ sudo puppet apply /vagrant/puppet/manifests/dev-vagrant.pp
+
+
View
48 docs/installation.rst
@@ -2,6 +2,10 @@
Installation
============
+This page describes the manual installation procedure. If you can, you
+should set up the `vagrant-managed virtual machine <installation-vagrant.rst>`_
+instead.
+
Requirements
============
@@ -154,7 +158,7 @@ set your ``settings_local.py`` with the following::
SERVE_MEDIA = True
Configure BrowserID
------
+-------------------
Add the following to ``settings_local.py`` so that BrowserID works with the
development instance::
@@ -166,19 +170,9 @@ development instance::
SESSION_COOKIE_SECURE = False # needed if the server is running on http://
SESSION_EXPIRE_AT_BROWSER_CLOSE = False
-The `SESSION_EXPIRE_AT_BROWSER_CLOSE` setting is not strictly necessary, but
+The ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` setting is not strictly necessary, but
it's convenient for development.
-Enable kumawiki in waffle
------
-
-We're using `django-waffle <https://github.com/jsocol/django-waffle>`_ to disable
-features not yet ready for production. To test out the wiki, you'll have to enable
-it first. To do so, open the `django admin interface <http://localhost:8000/admin/>`_
-and add a ``kumawiki`` flag.
-
-Note that features disabled by a flag will show up as a 404 error.
-
Testing it Out
==============
@@ -186,35 +180,15 @@ To start the dev server, run ``./manage.py runserver``, then open up
``http://localhost:8000``. If everything's working, you should see
the MDN home page!
-You might need to set ``LC_CTYPE`` if you're on Mac OS X until `bug 754728 <https://bugzilla.mozilla.org/show_bug.cgi?id=754728>`_ is fixed::
+You might need to first set ``LC_CTYPE`` if you're on Mac OS X until
+`bug 754728 <https://bugzilla.mozilla.org/show_bug.cgi?id=754728>`_ is fixed::
export LC_CTYPE=en_US
+What’s next?
+============
-Running the Tests
------------------
-
-A great way to check that everything really is working is to run the test
-suite. You'll need to add an extra grant in MySQL for your database user::
-
- GRANT ALL ON test_NAME.* TO USER@localhost;
-
-Where ``NAME`` and ``USER`` are the same as the values in your database
-configuration.
-
-The test suite will create and use this database, to keep any data in your
-development database safe from tests.
-
-Running the test suite is easy::
-
- ./manage.py test -s --noinput --logging-clear-handlers
-
-Note that this will try (and fail) to run tests that depend on apps disabled
-via ``INSTALLED_APPS``. You should run a subset of tests specified in
-`scripts/build.sh <../scripts/build.sh>`_, at the bottom of the script.
-
-For more information, see the `test documentation <tests.rst>`_.
-
+See `development <development.rst>`_ for further instructions.
Last Steps
==========
View
4 puppet/files/etc/motd
@@ -8,3 +8,7 @@ To start the Django app:
To start the kumascript service:
node kumascript/run.js
+
+To run tests:
+ (cd / && /vagrant/manage.py test actioncounters contentflagging dekicompat demos devmo landing users wiki)
+ (cd /vagrant/kumascript && ./node_modules/.bin/nodeunit tests)

0 comments on commit 20a72ef

Please sign in to comment.
Something went wrong with that request. Please try again.