146 lines
5.3 KiB
Markdown
146 lines
5.3 KiB
Markdown
# 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 ? 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.
|
|
|
|
```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 your taste when you use a different protocol
|
|
to sync into production.
|