Publish static web content

Software Factory provides default Zuul jobs to build and publish static website content. A user can use them to publish websites on a Software Factory instance that will be publicly accessible on http://<custom-name>.sftests.com/.

The following static content type are supported:

• raw
• Sphinx
• Pelican

Activate the build-pages job

The build-pages job is well suited to be triggered in the check pipeline. It builds the website source. The job fails if a processing error occurs. After a successful build, the built website is available in the pages directory on the log server.

In .zuul.yaml add the following:

- project:
    name: myproject
    check:
      jobs:
        - build-pages

The build-pages job expects to find the source of the website at the root of the repository. If the source is contained in a specific directory then the var scr_dir must be updated.

- project:
    name: myproject
    check:
      jobs:
        - build-pages:
            vars:
               src_dir: website

Activate the build-and-publish-pages job

build-and-publish-pages is a base job that must be used as parent job in your custom publishing job. This custom job should be triggered by the gate or the post pipeline to build and then publish the website on the Software Factory gateway.

The following code block give an example of the base job customization to define in a yaml file under the config repository zuul.d/.

- job:
    name: myproject-build-and-publish-pages
    parent: build-and-publish-pages
    final: true
    vars:
      vhost_name: www-myproject
    allowed-projects:
      - myproject

vhost_name is the name of the Apache Virtual Host and that means the website will be accessible at http://www.myproject.sftests.com. Furthermore, note that final set to true and allowed-projects set to the project name that will use that job are important options. Indeed it ensures that, only, myproject can use this publication’s job.

Once the custom job definition is merged, the project’s .zuul.yaml can be updated to publish during the gate pipeline.

- project:
    name: myproject
    check:
      jobs:
        - build-pages
    gate:
      jobs:
        - myproject-build-and-publish-pages

As an alternative, the publication job can be configured in the post pipeline.

- project:
    name: myproject
    check:
      jobs:
        - build-pages
    gate:
      jobs:
        - build-pages
    post:
      jobs:
        - myproject-build-and-publish-pages

Then next commits merged on myproject will be built and published and accessible via the Virtual Host name.

Hostname resolution

The Software Factory instance’s domain DNS configuration must be configured with a wildcard for all subdomains to be redirected to the Software Factory gateway IP. If you run a Software Factory in a test environment you might not have a real DNS entry configured then you should setup your local resolver.

For exemple adding in /etc/hosts:

echo "<SF IP> <custom-name>.sftests.com" | sudo tee -a /etc/hosts