Fatbuildrweb

Listening interface and port

These instructions are valid only for Fatbuildrweb running as an autonomous service. Please refer to your HTTP server reference documentation to control this setting for Fatbuildrweb running as a WSGI application.

By default, Fatbuildrweb autonomous service listens on localhost interface and port TCP/5000.

Edit Fatbuildr site configuration file /etc/fatbuildr/fatbuildr.ini. If not already present, add [web] section.

In this section, define parameter host with the host IP address to which Fatbuildrweb should bind its socket listening for incoming connections. Special value 0.0.0.0 means all network interfaces.

The TCP port can also be changed with port parameter (ex: 1234`).

For example:

[web]
host = 0.0.0.0
port = 1234

To apply the settings, restart the service:

# systemctl restart fatbuildrweb.service

Please refer to configuration parameters reference documentation for full details about available parameters.

Binding network socket to priviled ports ⇐ 1024 (ex: 80/HTTP) requires CAP_NET_BIND_SERVICE Linux capability. By default, only the root user has this capability. Fatbuildrweb autonomous service can be given this capability with a systemd drop-in unit configuration file for fatbuildrweb.service.

First create service drop-in directory:

# mkdir /etc/systemd/system/fatbuildrweb.service.d

Create configuration file in this directory (ex: /etc/systemd/system/fatbuildrweb.service.d/net-bind-cap.conf) with this parameter:

[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE

Make systemd reload unit configuration files:

# systemctl daemon-reload

Edit Fatbuildr site configuration file /etc/fatbuildr/fatbuildr.ini to setup the port value below 1024 (ex: 80/HTTP), and apply the configuration by restarting the service:

# systemctl restart fatbuildrweb.service

Mono-instance mode

By default, Fatbuildrweb is setup in multi-instances modes, it serves all instances defined in Fatbuildr installation. This can be changed to serve one specific instance and remove instance name in URL paths.

This feature can typically be used to serve instances behind their specific Apache2 virtual hosts or nginx sites with their dedicated network server names (ex: prod.example.org and staging.example.org).

Autonomous Service

Edit Fatbuildr site configuration file /etc/fatbuildr/fatbuildr.ini. If not already present, add [web] section.

In this section, define parameter instance with the name of the Fatbuildr instance to serve. For example:

[web]
instance = prod

Apply the new configuration by restarting the service:

# systemctl restart fatbuildrweb.service

WSGI Application

Settings of WSGI application depends on the HTTP server and the WSGI module. The following subsections provides configuration instructions for some combinations of those.

If you need help to setup Fatbuildrweb as a WSGI application in mono-instance mode with a different combination of HTTP server and WSGI module, please open an issue. If you want to contribute documentation for an additional HTTP server or WSGI module, please open a pull request!

Apache2 and mod_wsgi

Edit the configuration snippet used to declare Fatbuildr WSGI application in Apache2 HTTP server configuration file to modify the first argument of the WSGIDaemonProcess directive:

--- a/site.conf
+++ b/site.conf
@@ -1,4 +1,4 @@
-WSGIDaemonProcess fatbuildrweb-all user=fatbuildr group=fatbuildr locale=en_US.UTF-8
+WSGIDaemonProcess fatbuildrweb-prod user=fatbuildr group=fatbuildr locale=en_US.UTF-8
 WSGIScriptAlias / /usr/share/fatbuildr/wsgi/fatbuildrweb.wsgi
 WSGIPassAuthorization On

The -all special suffix value enables multi-instances mode. For example, to setup mono-instance mode on the prod instance, replace the -all suffix by -prod.

Finally reload the Apache2 HTTP service to enable modifications:

  • On Debian/Ubuntu:

    # systemctl reload apache2.service

  • On RHEL:

    # systemctl reload httpd.service

Nginx and uWSGI

Edit Fatbuildr uWSGI service file /etc/systemd/system/fatbuildrweb-uwsgi.service, as deployed in corresponding installation guide, to append the targeted instance name in executable argument:

--- a/etc/systemd/system/fatbuildrweb-uwsgi.service
+++ b/etc/systemd/system/fatbuildrweb-uwsgi.service
@@ -6,7 +6,7 @@
 User=fatbuildr
 Group=fatbuildr
 RuntimeDirectory=fatbuildrweb
-ExecStart=/usr/bin/uwsgi --ini /usr/share/fatbuildr/wsgi/uwsgi/fatbuildrweb.ini
+ExecStart=/usr/bin/uwsgi --ini /usr/share/fatbuildr/wsgi/uwsgi/fatbuildrweb.ini --pyargv=prod

 [Install]
 WantedBy=multi-user.target

For example, to setup mono-instance mode on the prod instance, append --pyargv=prod argument. The default value of the pyargv parameter is all, it is defined in the INI file and it enables multi-instances mode.

Finally restart the service to apply changes:

# systemctl restart fatbuildrweb-uwsgi.service

Reverse Proxies

Reverse proxies usually perform some buffering for performance reasons. While this is recommended for most use-cases, this introduces annoying latencies when watching tasks outputs on Fatbuildrweb REST API and web pages. For this reason, Fatbuildrweb set X-Accel-Buffering: no in the impacted reponse header to instruct potential intermediate reverse proxy to avoid buffering on these reponses. However, this header is usually removed at the first reverse proxy. It is not sufficient when multiple reverse proxies are involved between the clients and Fatbuildrweb. In this case, it might be necessary to disable buffering in HTTP reverse proxy configuration when proxying the requests.

For example, this can be disabled with the following configuration setting on Nginx:

proxy_buffering off;

To allow submission of large artifacts builds, it could be necessary to increase the maximum request body size allowed to clients, for example on Nginx:

client_max_body_size 100M;

Some processing can be long in fatbuildrd, thus interval between messages in task output can be long as well. thus time between. Some reverse proxies may close the connection before the end of tasks in absence of message before a short timeout. When this happens, fatbuildrctl reports this error:

WARNING ⸬ Unable to read task output from HTTP request due to chunk encoding error
WARNING ⸬ Unexpected end of task output from HTTP server

This timeout can be increased on reverse proxies to a significantly higher value, for example on Nginx:

proxy_read_timeout 3600;

Please refer to Nginx reference documentation for more details.

Access Policy

Policy definition files

The permissions to access Fatbuildrweb HTML and REST API endpoints are defined by a policy. By default, the vendor policy is defined in file /usr/share/fatbuildr/web/policy.acl. This default policy can be overriden with a site policy by creating a file /etc/fatbuildr/web/policy.acl.

Do not modify the vendor policy file or your modifications can be lost at the next Fatbuildr package upgrade.
The paths to the policy files can be changed in Fatbuildr system configuration file.

The policy files have the INI file format, with sections and parameters.

A policy file must have a global [roles] section. The options of this section are the names of the roles involved in the policy. The values of all options except the anonymous role are a comma-separated list of role members. The list can contain invidual users or group names prefixed by @.

Fatbuildr only supports UNIX NSS backend for retrieving users and groups. If users and groups of your organization are defined in an LDAP directory or SQL database, you must setup a NSS source (eg. sssd) to make the users and groups available to Fatbuildr.
Example 1. Example of role members:
[roles]
users=@devs,john

This policy defines the users role whose members are the individual user john and the members of devs group.

For each declared role, a section must be defined with the actions option. The value of this option is comma-separated of permission actions allowed to this role. This list can also contain values prefixed by @ followed by a role name to include the actions allowed to another role. This makes simple to define a role as an extension of another role.

Example 2. Example of role actions:
[roles]
users=@devs,john
admins=mary

[users]
actions=view-task

[admins]
actions=@users,view-keyring

This policy defines 2 roles users and admins. The users role is allowed to perform the view-task action. The admins is allowed to perform actions allowed to users role and the view-keyring action.

When the anonymous role is declared with allowed actions, all other roles are automatically allowed to perform these actions.
Vendor policy

For reference, here is the content of the default vendor policy file:

# The anonymous role is enabled. Another role 'users' is associated to all
# members of fatbuildr system group.
[roles]
anonymous
users=@fatbuildr

# The anonymous role is permitted to perform all view-* actions.
[anonymous]
actions=view-pipeline,view-registry,view-task,view-keyring

# The users are permitted to perform all anonymous actions plus the build
# action.
[users]
actions=build,edit-registry

Permission actions

Fatbuildrweb supports the following permission actions:

Name Description

view-pipeline

View content instance pipelines definition

view-registry

View content of artifact registries

edit-registry

Edit content of artifact registries

view-task

View tasks queue (running and pending), archives and outputs

view-keyring

Get information about keyring public key

build

Submit build tasks

Custom HTML templates

The HTML pages served by Fatbuildrweb are rendered based on templates. Fatbuildr provides vendor templates installed in directory /usr/share/fatbuildr/web/templates.

All these vendor templates can be individually overriden by site custom templates.

By default, Fatbuildr searches for custom site rendered templates in directory /etc/fatbuildr/web/templates but this can be changed by setting another value to templates parameter in [web] section of site configuration file. Please refer to configuration parameters reference documentation for full details about available parameters.

For example, this feature can be used to add a link in the footer of all HTML pages.

First, copy the corresponding vendor template in template site directory:

# mkdir /etc/fatbuildr/web/templates/layout
# cp /usr/share/fatbuildr/web/templates/layout/base.html.j2 \
     /etc/fatbuildr/web/templates/layout

Edit the new file, for example:

--- /usr/share/fatbuildr/web/templates/layout/base.html.j2
+++ /etc/fatbuildr/web/templates/layout/base.html.j2
@@ -32,6 +32,7 @@
       </main>
       <footer class="pt-5 my-5 text-muted border-top">
         Created by Fatbuildr
+        <a href="https://company.ltd">COMPANY HOME</a>
       </footer>
     </div>
     <script src="{{ url_for('static', filename='js/bootstrap.bundle.min.js') }}"></script>

Restart Fatbuildrweb service or HTTP server to apply changes.

Et voilà !

template modification example