Génévée

A merovingian king/queen name generator. Beyond its (let's face it, limited) intrinsic usefulness, this project is primarily meant to demonstrate a web front-end development workflow using SJW and guix.

Dependences

The following instructions hence assumes that you already have guix installed. Regarding SJW, it is available from the loom guix channel. Depending on how you chose to make it available, the following lines could be slightly different but to avoid luring you with some irrealistic simplicity, we will assume in what follows that you have cloned the loom channel in a sibling folder from this repository, so that its root is located at ../loom relatively to this repository. The syntax will be lighter if you add the loom to your known guix channels.

Build from a local clone of this repository (hacking)

The Génévée website can be built with this line:

$ guix shell -L ../loom -D -f guix.scm -- make

This is of course a one liner, but if you're actually working on an improvement you'll probably want to spawn a development environment with:

$ guix shell -L ../loom -D -f guix.scm

You improve the code in your favourite text editor, and from time to time when you want to see your changes applied you simply recompile the site with make in the previously-spawned shell environment:

[env]$ make

which will create or refresh main.js.

Alternatively if your editor handles compilation, calling make from some button or shortcut, you probably just want to run it from an enriched environment containing it plus the requirements for this package:

$ guix shell -L ../loom -D -f guix.scm emacs -- emacs

Simply opening the index.html from your browser lets you see your changes and work on them. On more complex projects requiring a back-end, you'll want to add a web server to your own environment and point it to your working copy. You can of course draw inspiration from the deployment section below, but respawning a VM each time you edit a line is by no means practical so even if your development server lives in a container or virtual machine, you'll be better off directly writing to the source files it hosts as long as your tweaking the code.

Prepare for distribution (checking)

You're becoming satisfied with your improvement and are seriously considering to submit a patch. You commit all your changes and build this site as any regular guix package the usual way:

$ guix build -L ../loom -f guix.scm

The site's files are directly at the root of the directory which path is displayed by the previous command right before it returns (your hash will be different and that's ok):

…
/gnu/store/f2w493gg7cn94dgbx8dyg2fr0srxm8qa-genevee-0.1.0
$ ls /gnu/store/f2w493gg7cn94dgbx8dyg2fr0srxm8qa-genevee-0.1.0
index.html  main.js  scribish.ttf  style.css

Building the site this way helps you make sure that you haven't forgotten any implicit dependency, for instance if you have introduced a new SJW library in the code and forgot to add it in Génévée's native-input field in guix.scm.

If the content of this directory works as expected and is up to your standards, on to pushing the commit or sending a patch. Otherwise edit, commit --amend, rinse and repeat.

Deploy !

Maybe you're used to seeing usual UNIX programs built with guix and you expect the content of a /gnu/store package's root to look like a profile with the usual bin/, etc/, share/, etc. directories. The cool thing with the above structure is that the package becomes directly useful as a kind of symbolic reference to a given state of the site's source.

To a guix system

Suppose you want to host it on a guix server. All you have to do is add a web server service to its configuration, nginx for the sake of the example, and point a location to the genevee package itself:

(define genevee (load "guix.scm"))

…

(service nginx-service-type
 (nginx-configuration
  (server-blocks
   (list (nginx-server-configuration
          (root genevee))))))

In fact, have you noticed the genevee-in-a-vm.scm in this repository ? These few lines are actually enough to let you spin a local demo of a server hosting Génévée in virtually (ahah) no time.

$ `guix system vm -L ../loom genevee-in-a-vm.scm` -nic user,model=virtio-net-pci,hostfwd=tcp::8000-:80

Once the VM is up, visit http://localhost:8000 to admire your local instance of Génévée.

Anywhere else

The target server where you want to deploy Génévée is the last remaining part of your fleet not (yet) running guix ? That's too bad but don't worry, you can still benefit from this structure and use the cool script deploy.sh (included). Assuming you SSH into your host at my.vps.net, and you want to put Génévée into, say, /srv/httpd/Génévée/ — where you have write access — simply call:

./deploy.sh my.vps.net:/srv/httpd/Génévée

Of course this just calls rsync with the path expanded from the evaluation of guix build like above. Adapt to your taste when you use a different protocol to sync into production.