Add tutorial on running locally

CONTRIBUTING.md

@@ -1,6 +1,7 @@
-# Contributing guide
+# Contributing guide / Documentation
 
 * [Criteria for language inclusion](doc/what-languages.md)
+* [Running Riju locally](doc/local.md)
 * [How to add your own language to Riju](doc/tutorial.md)
 * [Deep dive on Riju build system](doc/build.md)
 * [Riju infrastructure layout](doc/infra.md)

README.md

@@ -47,7 +47,7 @@ being nice include:
 * *Mining cryptocurrency.* Since hosting Riju comes out of my
   paycheck, this is exactly equivalent to stealing, which isn't nice.
 
-## Can I help?
+## Can I help? / Documentation
 
 Absolutely, please see [Contributing guide](CONTRIBUTING.md).
 

doc/local.md

@@ -0,0 +1,110 @@
+# Running Riju locally
+
+This document has the steps necessary to build and run Riju locally,
+without modifications. See the other documentation pages for
+information about customizing and rebuilding Riju, or extending it by
+adding or modifying the supported languages.
+
+If you run into any trouble following the guide, please do not
+hesitate to open an issue!
+
+## Project setup
+
+Fork this repository to your account on GitHub, and clone it locally:
+
+```
+$ git clone https://github.com/yourname/riju.git
+$ cd riju
+```
+
+Install [Docker](https://www.docker.com/). Then you can build and
+start the admin shell:
+
+```
+$ make image shell I=admin
+```
+
+All future operations can be done inside the admin shell, where Riju's
+dependencies are already installed.
+
+## Start tmux
+
+Start a tmux session:
+
+```
+$ make tmux
+```
+
+If you don't know how to use tmux, see [a
+cheatsheet](https://danielmiessler.com/study/tmux/). The useful
+keybindings are:
+
+* `control-b c`: open new tab
+* `control-b p/n`: previous/next tab
+* `control-b "`: split tab into top and bottom panes
+* `control-b %`: split tab into left and right panes
+* `control-b <arrows>`: move between panes
+* `control-b control-b <something>`: if you have two tmuxes nested,
+  use `control-b` twice to do a command on the inner one instead of
+  the outer one
+
+## Fetch base Ubuntu image
+
+Make sure you're using the same version of Ubuntu as the mainline
+Riju:
+
+```
+$ make sync-ubuntu
+```
+
+## Start Riju server
+
+Use `dep`, the Riju build tool, to compile the Docker image that the
+Riju server will run inside:
+
+```
+$ dep image:runtime
+```
+
+Start Riju in development mode:
+
+```
+$ make shell I=runtime E=1 CMD="make dev"
+```
+
+You should now be able to navigate to <http://localhost:6119> and see
+that Riju is running, although it does not have any languages
+installed.
+
+## Build languages
+
+Building all languages supported by Riju is a lengthy process which
+often requires some debugging as something upstream has broken since
+the last time I built everything. You may be more interested in
+getting your favorite language(s) up and running. To do that, find the
+relevant language (say `foo.yaml`) in the `langs` subdirectory, and
+run:
+
+```
+$ dep image:lang-foo
+```
+
+After this completes successfully, you'll automatically be able to use
+that language in the web interface without needing to restart.
+
+You can also run:
+
+```
+$ dep test:lang-foo
+```
+
+This will, in addition to building the language image, run the defined
+integration tests to make sure it is functioning properly.
+
+If you *do* want to build and test all supported languages, run:
+
+```
+$ dep deploy:ready
+```
+
+Expect this to take many hours.