Guix Packages Website

• Summary
• Development shell
• Running the website
• Running the test suite
• Environment variables
• Deploying to the GNU Guix infrastructure
  • Phase 01: Test the website in a production-like environment
  • Phase 02: Send changes to the Guix project for review
  • Phase 03: Wait for the changes to be deployed to production
• Copying

Summary

This is the GNU Guix package browser available at packages.guix.gnu.org. This software uses Artanis.

The exact set of dependencies necessary for the software to run are specified by two files:

• ./envs/guix/dev-shell.scm
• ./envs/guix/channels.scm

The former indicates package dependencies, while the latter indicates their provenance (and, implicitly, their versions).

The main source files of the software are currently organized as follows:

...
├── conf
├── ENTRY
├── lib/gweb
│   ├── aux.scm
│   ├── builders.scm
│   ├── data.scm
│   ├── templates.scm
│   ├── types.scm
│   └── urls.scm
├── pub
│   └── themes
├── test
...

The most important parts are these:

conf

Artanis configuration.

ENTRY

Artanis initialization and HTTP Request → HTTP Response associations.

(gweb builders)

Procedures that build HTTP responses or the bodies of HTTP responses, using data and template procedures.

(gweb data)

Procedures that retrieve data from different places or services.

(gweb templates)

Procedures that take data as inputs and place them into HTML/XML/SVG/Etc templates that represent resources or parts of the resources served by the website.

(gweb types)

Custom data types.

(gweb urls)

URL shorthands.

pub/themes

Named collections of files that define the appearance of the software.

Development shell

You can use a containerized Guix shell to run the website locally or its test suite while you work on it. The Guix time-machine is used so that the shell provides a consistent environment for everybody: it will provide the same software coming from the same Guix channel revision.

Do the following in a terminal to prepare the development shell:

cd path/to/guix-packages-website
guix time-machine --channels=envs/guix/channels.scm -- shell -CN -m envs/guix/dev-shell.scm

It will take some time to be ready. Once it is, you should notice that the command prompt looks different now.

Running the website

To try out the website locally:

1. Make sure you are in a development shell.
2. Change directory to the project root.

3. Run the development server:

   art work

You should now be able access the website from a web browser visiting http://localhost:3000/.

To stop the server, press Ctrl + C in the development shell.

Running the test suite

Run the complete test suite as follows (currently unit tests only):

1. Make sure you are in a development shell.
2. Change directory to the project root.

3. Add website libraries to GUILE_LOAD_PATH:

   export GUILE_LOAD_PATH="$GUILE_LOAD_PATH:$PWD/lib"

4. Run the test suite:

   proba run test

You should see a report indicating the results of the automatic tests.

Environment variables

The Guix Packages Website inspects the following environment variables for configuration and customization.

GUIX_PACKAGES_WEBSITE_DOMAIN_NAME

For example:

GUIX_PACKAGES_WEBSITE_DOMAIN_NAME="packages.mysite.net"

The domain name is currently used to form links that external websites can use to access resources of the Guix packages Website in production environments.

If not available, the website will use the host name and port information from Artanis' configuration.

Deploying to the GNU Guix infrastructure

The bayfront machine in the Guix infrastructure serves an instance of the Guix Packages Website. This instance is configured as a Guix service and its configuration is available in the Guix's maintenance repository. The relevant files are:

hydra/modules/sysadmin/services.scm

Contains the service definition of the Guix Packages Website instance, among other services.

hydra/bayfront.scm

Operating system configuration of the machine of the same name (it uses the service above).

The process of deploying a new version of the website to bayfront follows the Sporadic Delivery practice, it is mostly manual, and consists of the following phases:

• Phase 01: Test the target website version in a production-like environment.
• Phase 02: Send changes to the Guix project for review.
• Phase 03: Wait for the changes to be deployed to production.

The following sections detail these phases.

Phase 01: Test the website in a production-like environment

In this phase, you clone Guix's maintenance repository, create a new branch to update bayfront's configuration so that it serves a new version of the website, and then test the new configuration in a virtual machine. For example:

1. Clone the Guix's maintenance repository to a directory of your preference (in this example, /home/$USER/Projects):

   cd ~/Projects
   git clone https://codeberg.org/guix/maintenance.git

2. Create a new branch to update bayfront's configuration:

   cd maintenance
   git switch -c bayfront/packages-website-service-X.Y.Z

3. Update the Guix Packages Website service configuration defined in hydra/modules/sysadmin/services.scm so that it uses a new version of the website.

4. Create a virtual machine for testing. To do so, you can use an operating system configuration provided by the Guix Packages Website repository which, in turn, provides the service you just modified in the previous step.

   # Change directory to the repository of Guix Packages Website.
   cd path/to/guix-packages-website
   # Create the virtual machine.
   guix system vm -L ~/Projects/maintenance/hydra/modules envs/guix/preproduction-os.scm

   If everything goes fine, the last command will output, right at the end, the location of a script you can use to launch the virtual machine. It looks like /gnu/store/HASH-run-vm.sh.

5. Start the virtual machine by running the script created in the previous step as follows:

   /gnu/store/HASH-run-vm.sh -nic user,model=virtio-net-pci -m 1024M

   A few seconds later, you should see a welcome screen like this:

   |0.0| I am a Guix System. Welcome!
   
   makina login:
   

   Next, you can start testing the service.

6. Check that the Guix Packages Website Service is running by logging in as user root (no password required, just press Enter) and asking herd about the service status:

   herd status guix-packages-website

   If the service is running correctly, you should see a summary along these lines:

   Status of guix-packages-website:
     It is running since 06:20:16 PM (42 seconds ago).
     Main PID: 257.
     Command: /gnu/store/HASH-wrapped-art-for-guix-packages-website work --port=3000 --host=127.0.0.1
     It is enabled.
     Provides: guix-packages-website.
     Requires: user-processes networking.
     Will be respawned.
     Log file: /var/log/guix-packages-website.log

   Now you should be able to access the website in the next step. In the meantime, log out as root by pressing Ctrl + D or running the exit command.

7. Check that the website works as expected in a graphical environment by logging into the system with username tester and password excuseme and then running the following command:

   sway -c sway.config

   This command will start the Sway window manager and the configuration in sway.config will make Qutebrowser launch automatically. Give it a few seconds to start.

   Once you see the web browser is ready, click somewhere in the browser window, press the O key in the keyboard, and enter the following address: localhost:3000.

   You should see the Guix Packages Website load. Now you can test whether it works as expected.

8. If everything works alright, commit your changes to the maintenance repository. They will be sent to the Guix project in Phase 02.

Phase 02: Send changes to the Guix project for review

In Phase 01 you cloned the Guix's maintenance repository, and created a development branch to updated the bayfront configuration so that it serves a new version of the Guix Packages Website. In this phase, you send the changes by email to the Guix project for review.

1. Review the commits in your development branch. Make sure that

   • The changes in each commit are focused in one goal. Don't mix unrelated changes into one commit.
   • The commit messages follow GNU's ChangeLog format. Check the commit history in your copy of the Guix's maintenance repository to see some examples.

2. Submit your changes to Guix following the instructions in the manual. For example, assuming your git send-email is already configured, you could send a patch containing the changes of the latest commit in your branch as follows:

   git send-email -1 \
       --base=REVISION_OF_THE_BASE_COMMIT_HERE \
       --subject-prefix='PATCH maintenance' \
       --to=[email protected] --cc=[email protected]

   This will send a message to [email protected] with subject [PATCH maintenance] First line of the commit message. Guix's sysadmin team will receive a copy of the message at [email protected]. A patching request will be recorded publicly in Guix's issue tracker at https://issues.guix.gnu.org/ (minutes later, you'll receive an automatic response confirming the reception of your message and indicating the issue number assigned to your request).

At this point, your submission will be reviewed and, hopefully, applied to the maintenance repository upstream.

Phase 03: Wait for the changes to be deployed to production

Finally, once your changes have been accepted, it may take a while for them to go live in https://packages.guix.gnu.org/, since the Guix sysadmin team might still need to wait for the right time to issue a guix system reconfigure command at the bayfront machine. So feel free to move on to other projects.

In the meantime, thank you very much for your service!

Copying

Unless otherwise stated, all the files in this repository are placed in the public domain with the following note:

Public domain 2022 Luis Felipe López Acevedo. All rights waived.

The Guix logo (⋎) is licensed under the following terms:

Copyright © 2015 Luis Felipe López Acevedo

Permission is granted to copy, distribute and/or modify this work under the terms of the Creative Commons Attribution-ShareAlike 4.0 International License.