1. happs intro
2. the missing happs documentation
3. getting started with happs
4. prerequisites
5. cabal install me
6. main
7. url handling
8. templates
9. stringtemplate basics
10. debugging
11. form data: get and post
12. form data: file uploads
13. cookies
14. introduction to macid
15. using macid safely
16. macid dummy data
17. macid updates and queries
18. changing the data model
19. macid stress test
20. limitations of macid
21. foreign characters
22. cron jobs
23. thanks
24. appendix (floundering in ghci)

Run This Tutorial Locally

Before going further, you may want to inform yourself about the basic prerequisites, both knowledge and equipment, you need to make the best use of this tutorial

This tutorial is cabalized. You can install it, and chase down all the HAppS dependencies it needs, simply by doing

cabal install happs-tutorial

The cabal installation may take up to an hour, mainly because the HAppS-Server installation is slow, but it should succeed in one shot. This is a symptom of the HAppS slow linking bug.

If you've never used cabal install or need more detailed info....

• Haskell: You need at least ghc 6.8.2 to install HAppS. I installed this with with apt-get install haskell (works for ubuntu hardy heron), and then upgraded to ghc 6.8.3 as this is supposed to have fixed some bugs.
• Dependency chasing haskell package installers: you should have the latest versions of cabal and cabal install from hackage. These are already included in the latest version of ghc, or they will be soon. Another reason to upgrade to ghc 6.8.3.
• If you want to check out the latest version of this tutorial, install Darcs and check out the repo with darcs get http://code.haskell.org/happs-tutorial

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

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:

find ~/.cabal | grep -i happs-tutorial

should show you a tar file. Or you can just download the tar file from hackage. 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.

To run the app, either do ./hackInGhci.sh and then execute runInGhci inside Main.hs, or recompile the executable using ./runServerWithCompileNLink.sh. Really you only need to be inside ghci if you are experiencing the slow link time issue. This isn't a problem at time of writing but seems to crop up from time to time.

Shutdown with ctrl-c.

You should now be able to browse this tutorial offline by running the executable, and opening http://localhost:5001 in your browser.

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

*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)

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

You may also want to start HAppS on boot.

Next up is the HAppS server main function.