Home

Awesome

opam2web

A tool to generate a website from an OPAM universe

This utility creates a static website from an OPAM universe, listing all available packages and their details. A homepage and OPAM documentation is included as well.

The latest release of opam2web is available via opam. To install, simply run:

opam install opam2web

Prerequisties

Optionally create a local switch for the project:

opam switch create . ocaml.4.14.0 --with-test

Build

dune exec -- opam2web will compile and run the utility directly, alternatively you can run:

dune build @all

and the binary will be located in _build/install/default/bin/opam2web after compilation.

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:

DOCKER_BUILDKIT=1 docker build -t opam2web .

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

docker run -p 127.0.0.1:8080:80/tcp --name opam2web ocurrent/opam.ocaml.org:live --root /usr/share/caddy

CLI Usage

opam2web [options]* [repositories]*

Each repository is namespaced by its type:

The order of repositories determines their priority when generating the opam universe to use. Earlier repositories are higher priority.

If no repository is given, the current local opam universe is used.

Some available options are:

Some available predicates are:

For complete command-line configuration options, run

opam2web --help

Example

opam2web -o website path:~/myrepo local:default

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.

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.

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.