Setting up Wizard
=================

:Author: Edward Z. Yang <ezyang@mit.edu>

.. highlight:: sh

Probably the easiest way to do development is entirely on :term:`AFS`, so that if you
SSH into a scripts server to perform testing, you will be able
to invoke your tools and read your development repository.  In order
to be able to run the test scripts in the tests directory, this
is preferably in :file:`web_scripts`.  First, you should ensure that you
are signed up web scripts service and sql.mit.edu::

    athrun scripts # Select "Enable the web scripts service" and "Sign up for a sql.mit.edu account"

.. note::

    If you are running on a operating system that does not have support
    for AFS and other standard Debathena tools, it is highly recommended
    that you SSH into a server that does, such as `Linerva <http://linerva.mit.edu/>`_
    to perform development.  We will now assume all commands are
    being done on a server similar to Linerva.

In that case, setup is as simple as::

    git clone /mit/scripts/git/wizard.git /mit/$USER/web_scripts/wizard

Other users will not be able to access your source code, which may be
detrimental if you want to let other people test your code.  If you change the
access control to allow ``system:anyuser`` to read your source code (in case
you want to let other people test your code), do *not* give access to the
:file:`tests` directory, which may contain sensitive data once you start
running tests.  A set of commands that will let you do this would be::

    athrun consult fsr sa /mit/$USER/web_scripts/wizard system:anyuser read
    athrun consult fsr sa /mit/$USER/web_scripts/wizard/tests system:anyuser none

Finally, you need to generate some metadata for Python.  You can do this
by running::

    ./refresh.sh

in the root of your Wizard installation.

To test if your setup is now working, run one of the test scripts on a Scripts
server::

    ssh scripts.mit.edu
    /mit/$USER/web_scripts/wizard/tests/mediawiki-install-test.sh

You should also add the :file:`bin` to your path::

    PATH=/mit/$USER/web_scripts/wizard/bin:$PATH

You will need to run this command whenever you do Wizard development; if
you forget you may accidentally use the system-wide Wizard binary
installed on Scripts servers.

Application development
-----------------------

By default, Wizard will go and look for Git repositories for our various
applications in the :file:`/mit/scripts/git/autoinstalls` directory.
However, if you're developing your own application, you'll probably have
your own directory (probably living in :file:`/mit/$USER/web_scripts/wizard/srv`)
and you want Wizard to use those files.  In that case, you can override
the directory Wizard is looking at with::

    export WIZARD_SRV_PATH=/mit/$USER/web_scripts/wizard/srv

You may call this command a lot, so placing it in a small shell file (e.g. :file:`dev`) that
you include with::

    . dev

at your prompt may be useful.  This also means that Wizard will think you
have *no* applications initially; you'll have to clone (or symlink)
the appropriate repositories manually::

    git clone /mit/scripts/git/autoinstalls/$APP.git /mit/$USER/web_scripts/wizard/srv/$APP

Advanced setup
--------------

These instructions are for if you'd like to be able to develop offline and are
on ``scripts-root``.  Wizard will mostly work on your local machine, but you
won't be able to do all development offline; some steps in the development
process must be performed on scripts servers.  Thus, the difficult part is
marshalling commits from one repository to another. Git doesn't exactly make
this easy, but you can follow this recipe::

    git clone ssh://scripts@scripts.mit.edu/mit/scripts/git/wizard.git ~/wizard
    cd /mit/$USER
    mkdir wizard.git
    cd wizard.git
    git init --bare
    cd ~/wizard
    git remote add afs /mit/$USER/wizard.git
    git push -f afs master
    git clone /mit/$USER/wizard.git /mit/$USER/wizard

We create a bare repository :file:`/mit/$USER/wizard.git` that you can push and
pull from, and then setup an alternate remote ``afs`` on your offline copy.

And then you can perform updates from your local copy with::

    git push afs master
    cd /mit/$USER/wizard
    git pull

If :file:`/mit/$USER/wizard.git` has write permissions for
``system:scripts-security-upd``, this is especially useful if you were hacking
on a copy living on ``not-backward.mit.edu``, and now need to transfer the
changes back to the canonical repository (please don't give ``not-backward.mit.edu``
your root tickets!)  You can also setup a wizard directory similar to the
first set of directions for on-server testing.

Setting up the tests scripts to work is also slightly involved; more
instructions can be found on the :doc:`testing documentation <testing>`.

.. warning::

    These instructions are not well tested.  Let me know if you run into
    any difficulties.