Genevee/README.md

# 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](https://git.marvid.fr/Tissevert/SJW)
and [guix](https://guix.gnu.org/).

## Dependences

The following instructions hence assumes that you already have `guix`
installed. Regarding `SJW`, it is available from the
[loom](https://git.marvid.fr/Tissevert/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:

```sh
$ 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:

```sh
$ 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:

```sh
[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:

```sh
$ 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](#deploy) 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:

```sh
$ 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):

```sh
…
/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](https://guix.gnu.org/fr/manual/devel/en/html_node/package-Reference.html)
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:

```guile
(define genevee (load "guix.scm"))
```
…
```guile
(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 ? This
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.

```sh
$ `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](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:

```sh
./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 taste when you use a different protocol to
sync into production.