doc/setup.rst

   1 Setting up Wizard
   2 =================
   3
   4 :Author: Edward Z. Yang <ezyang@mit.edu>
   5
   6 .. highlight:: sh
   7
   8 Probably the easiest way to do development is entirely on :term:`AFS`, so that if you
   9 SSH into a scripts server to perform testing, you will be able
  10 to invoke your tools and read your development repository.  In order
  11 to be able to run the test scripts in the tests directory, this
  12 is preferably in :file:`web_scripts`.  First, you should ensure that you
  13 are signed up web scripts service and sql.mit.edu::
  14
  15     athrun scripts # Select "Enable the web scripts service" and "Sign up for a sql.mit.edu account"
  16
  17 .. note::
  18
  19     If you are running on a operating system that does not have support
  20     for AFS and other standard Debathena tools, it is highly recommended
  21     that you SSH into a server that does, such as `Linerva <http://linerva.mit.edu/>`_
  22     to perform development.  We will now assume all commands are
  23     being done on a server similar to Linerva.
  24
  25 In that case, setup is as simple as::
  26
  27     git clone /mit/scripts/git/wizard.git /mit/$USER/web_scripts/wizard
  28
  29 Other users will not be able to access your source code, which may be
  30 detrimental if you want to let other people test your code.  If you change the
  31 access control to allow ``system:anyuser`` to read your source code (in case
  32 you want to let other people test your code), do *not* give access to the
  33 :file:`tests` directory, which may contain sensitive data once you start
  34 running tests.  A set of commands that will let you do this would be::
  35
  36     athrun consult fsr sa /mit/$USER/web_scripts/wizard system:anyuser read
  37     athrun consult fsr sa /mit/$USER/web_scripts/wizard/tests system:anyuser none
  38
  39 Finally, you need to generate some metadata for Python.  You can do this
  40 by running::
  41
  42     ./refresh.sh
  43
  44 in the root of your Wizard installation.
  45
  46 To test if your setup is now working, run one of the test scripts on a Scripts
  47 server::
  48
  49     ssh scripts.mit.edu
  50     /mit/$USER/web_scripts/wizard/tests/mediawiki-install-test.sh
  51
  52 You should also add the :file:`bin` to your path::
  53
  54     PATH=/mit/$USER/web_scripts/wizard/bin:$PATH
  55
  56 You will need to run this command whenever you do Wizard development; if
  57 you forget you may accidentally use the system-wide Wizard binary
  58 installed on Scripts servers.
  59
  60 Application development
  61 -----------------------
  62
  63 By default, Wizard will go and look for Git repositories for our various
  64 applications in the :file:`/mit/scripts/git/autoinstalls` directory.
  65 However, if you're developing your own application, you'll probably have
  66 your own directory (probably living in :file:`/mit/$USER/web_scripts/wizard/srv`)
  67 and you want Wizard to use those files.  In that case, you can override
  68 the directory Wizard is looking at with::
  69
  70     export WIZARD_SRV_PATH=/mit/$USER/web_scripts/wizard/srv
  71
  72 You may call this command a lot, so placing it in a small shell file (e.g. :file:`dev`) that
  73 you include with::
  74
  75     . dev
  76
  77 at your prompt may be useful.  This also means that Wizard will think you
  78 have *no* applications initially; you'll have to clone (or symlink)
  79 the appropriate repositories manually::
  80
  81     git clone /mit/scripts/git/autoinstalls/$APP.git /mit/$USER/web_scripts/wizard/srv/$APP
  82
  83 Advanced setup
  84 --------------
  85
  86 These instructions are for if you'd like to be able to develop offline and are
  87 on ``scripts-root``.  Wizard will mostly work on your local machine, but you
  88 won't be able to do all development offline; some steps in the development
  89 process must be performed on scripts servers.  Thus, the difficult part is
  90 marshalling commits from one repository to another. Git doesn't exactly make
  91 this easy, but you can follow this recipe::
  92
  93     git clone ssh://scripts@scripts.mit.edu/mit/scripts/git/wizard.git ~/wizard
  94     cd /mit/$USER
  95     mkdir wizard.git
  96     cd wizard.git
  97     git init --bare
  98     cd ~/wizard
  99     git remote add afs /mit/$USER/wizard.git
 100     git push -f afs master
 101     git clone /mit/$USER/wizard.git /mit/$USER/wizard
 102
 103 We create a bare repository :file:`/mit/$USER/wizard.git` that you can push and
 104 pull from, and then setup an alternate remote ``afs`` on your offline copy.
 105
 106 And then you can perform updates from your local copy with::
 107
 108     git push afs master
 109     cd /mit/$USER/wizard
 110     git pull
 111
 112 If :file:`/mit/$USER/wizard.git` has write permissions for
 113 ``system:scripts-security-upd``, this is especially useful if you were hacking
 114 on a copy living on ``not-backward.mit.edu``, and now need to transfer the
 115 changes back to the canonical repository (please don't give ``not-backward.mit.edu``
 116 your root tickets!)  You can also setup a wizard directory similar to the
 117 first set of directions for on-server testing.
 118
 119 Setting up the tests scripts to work is also slightly involved; more
 120 instructions can be found on the :doc:`testing documentation <testing>`.
 121
 122 .. warning::
 123
 124     These instructions are not well tested.  Let me know if you run into
 125     any difficulties.
 126