Merge pull request #209 from tmcgilchrist/docker_instructions

Update install and usage instructions.

README.md

@@ -9,12 +9,19 @@ included as well.
 
 The latest release of opam2web is available via
 [opam](http://opam.ocaml.org). To install, simply run:
+
 ```bash
 opam install opam2web
 ```
 
 ### Prerequisties
 
+Optionally create a local switch for the project:
+
+``` bash
+opam switch create . ocaml.4.14.0 --with-test
+```
+
 - re [github.com/ocaml/ocaml-re](https://github.com/ocaml/ocaml-re)
 - uri [github.com/avsm/ocaml-uri](https://github.com/avsm/ocaml-uri)
 - opam [github.com/ocaml/opam](https://github.com/ocaml/opam)
@@ -23,26 +30,37 @@ opam install opam2web
 - cmdliner [erratique.ch/software/cmdliner](http://erratique.ch/software/cmdliner)
 - js_of_ocaml [ocsigen.org/js_of_ocaml](http://ocsigen.org/js_of_ocaml/)
 
-If you have opam installed:
+### Build
+
+`dune exec -- opam2web` will compile and run the utility directly, alternatively you can run:
+
 ```bash
-opam install re uri opam-lib opamfu cow cmdliner js_of_ocaml
+dune build @all
 ```
 
-### Build
+and the binary will be located in `_build/install/default/bin/opam2web` after compilation.
 
-To build the `opam2web` utility, enter:
-```bash
-make
+At this point you'll either want to try a `docker` build or running the `opam2web` cli locally.
+
+### Docker
+
+The website generation for opam.ocaml.org uses a combination of `docker` and `ocurrent-deployer` to rebuild the site. 
+To replicate the docker image run:
+
+``` bash
+DOCKER_BUILDKIT=1 docker build -t opam2web .
 ```
-The binary will be located in src/_build/opam2web.native after compilation.
 
-To generate the static website corresponding to the `default` remote in the
-local OPAM installation, enter:
-```bash
-make -C src run
+which uses the local Dockerfile and creates an image called `opam2web`. Note this image is rather large at over 18Gb and takes a while to build.
+Once built it can be run as `docker run -p 127.0.0.1:8080:80/tcp opam2web --root /usr/share/caddy` and viewable on http://localhost:8080.
+
+To run the image produced by deploy.ci.ocaml.org run (note the image is multi-arch with x86 and ARM64 support):
+
+``` bash
+docker run -p 127.0.0.1:8080:80/tcp --name opam2web ocurrent/opam.ocaml.org:live --root /usr/share/caddy
 ```
 
-### Usage
+### CLI Usage
 
 ```bash
 opam2web [options]* [repositories]*
@@ -83,6 +101,7 @@ Some available predicates are:
 - `pkg:*`
 
 For complete command-line configuration options, run
+
 ```bash
 opam2web --help
 ```
@@ -96,7 +115,19 @@ will generate the HTML files corresponding to the repository located in
 `~/myrepo` and the remote named `default` in the local OPAM installation.
 Resulting files will be located in the `website` directory.
 
-### TODO
 
-- More complex news system (one page per news, Markdown...)
-- More complex statistics (graphics over time...)
+## Deployment
+
+The deployment uses [ocurrent-deployer][] to watch particular branches on this repository, plus the default branches of [opam-repository][] and [platform-blog][]. 
+When any of them change, it calculates if it needs to rebuild the docker image. A site rebuild is therefore triggered by any merge to opam-repository.
+
+ * `live` branch is deployed on [opam.ocaml.org][]
+ * `staging` branch is deployed on [staging.opam.ocaml.org][]
+
+The deployer service is available at https://deploy.ci.ocaml.org/?repo=ocaml-opam/opam2web and the code for the ocurrent pipeline is in [ocurrent-deployer]().
+
+[ocurrent-deployer]: https://github.com/ocurrent/ocurrent-deployer
+[opam-repository]: https://github.com/ocaml/opam-repository
+[platform-blog]: https://github.com/ocaml/platform-blog
+[opam.ocaml.org]: https://opam.ocaml.org
+[staging.opam.ocaml.org]: https://staging.opam.ocaml.org