happs-tutorial-0.7: templates/runtutoriallocally.st

<h3>Run This Tutorial Locally</h3>

<p> Before going further, you may want to inform yourself about the <a href=/tutorial/prerequisites>basic prerequisites</a>, both knowledge and equipment, you need to make the best use of this tutorial </p>

<p>This tutorial is cabalized. You can install it, and chase down all the Happstack dependencies it needs, simply by doing 
<p>cabal install happs-tutorial

<p><font color=orange>Unfortunately, the above statement is false on ghc 6.10.1 at the moment, because 
   <br>the crypto package won't cabal install out of the box. You can build crypto first by doing 
   <br>darcs get http://code.haskell.org/crypto
   <br>cd crypto
   <br>cabal install
   <br>When ghc 6.10.2 is released the hackage version of Crypto should build right out of the box</font>

<p>If you've never used cabal install or need more detailed info....</p>

<ul>
    <li>Haskell: I use ghc 6.10.1, and suggest you do too. 
    I installed this with with apt-get install haskell (works for ubuntu hardy heron), and then <a href="http://www.haskell.org/ghc/download.html">upgraded to ghc 6.10.1</a>.</li> 
    <li>Dependency chasing haskell package installers: you should have the latest versions of cabal and cabal install from <a href="http://hackage.haskell.org/packages/archive/pkg-list.html">hackage</a>. These are already included in the latest version of ghc, or they will be soon. I have 
   <br>cabal --version
   <br>cabal-install version 0.6.0
   <br>using version 1.6.0.1 of the Cabal library 
   <br>The latest version of cabal is a bit tricky to install. What I did was start with ghc 6.10.1 and then
   download the tar file of the latest version of cabal from hackage, unzip that and run bootstrap.sh.

</li>
    <li>If you want to check out the latest version of this tutorial, install <a href="http://www.darcs.net">Darcs</a> and check out the repo with darcs get http://patch-tag.com/publicrepos/happstack-tutorial</li>
</ul>

<p>The reason I cabalized happs-tutorial was for the dependency chasing you get with cabal install,
not for actually running it.


<p>Cabal installs an executable somewhere that you can run, but the tutorial pages won't display because
the executable needs template files to display pages correctly. To actually run the tutorial locally, copy the 
happs-tutorial.tar.gz distribution file that cabal downloaded -- probably somewhere under  ~/.cabal if you're on linux: 

<p><i>find ~/.cabal | grep -i happs-tutorial</i>

<p>should show you a tar file. Or you can just download the tar file from
<a href="http://hackage.haskell.org/cgi-bin/hackage-scripts/package/happs-tutorial">hackage</a>.
Once you have the tar file, untar this somewhere, cd into that, build and run here as described below.
Or, you could darcs get happs-tutorial and run there. 

<p>To run the app, either do ./hackInGhci.sh and then execute runInGhci inside Main.hs or run the happs-tutorial
      executable created by cabal install, with the caveat that you do need to be in the base directory of happs-tutorial.
   You shouldn't need to run inside of ghci, but the option is available.
<p>
Shutdown with ctrl-c.
<p>
You should now be able to browse this tutorial offline by running the executable, and opening http://localhost:5001 in your browser.

<p>Every so often, when starting via runInGhci, you may get an error message like:

<p>*Main> runInGhci
happs tutorial running in ghci.
exit :q ghci completely and reenter ghci, before restarting.
*** Exception: _local/happs-tutorial_state/events-0000000006: openFile: resource busy (file is locked)

<p>Don't worry about it. Every time I get this error I simply run runInGhci again, and the second time it always works.

<p>As far as I know, this issue does not occur when you run the tutorial from a compiled executable, which is of course
  how you should be running for a production application.

<p>
You may also want to <a href="start-happstack-on-boot">start Happstack on boot</a>.

<p>Next up is the <a href="/tutorial/main-function">Happstack server main function</a>.</p>