You may adjust the sfconfig.yaml configuration file, to set operator settings, such as the domain name, the admin password, external identity providers, cloud providers…

# vim /etc/software-factory/sfconfig.yaml
# sfconfig --skip-install

Currently located in /etc/software-factory/sfconfig.yaml, this is the main configuration entry point. If needed, Ansible roles variables can be over-written in /etc/software-factory/custom-vars.yaml file as well.


The /etc/software-factory is versioned with git, you can use git diff and git commit to check files modifications.


Any modification to sfconfig.yaml needs to be manually applied with the sfconfig script. Run sfconfig after saving the sfconfig.yaml file.

Configuration and reconfiguration

  • Connect as root via SSH to the install-server.
  • Edit the configuration file /etc/software-factory/sfconfig.yaml:
    • set the configuration according to your needs.
    • all parameters are editable and should be self-explanatory.
  • Edit the architecture file /etc/software-factory/arch.yaml (see Architecture documentation)
    • set the architecture according to your needs.
  • Run sfconfig to apply the configuration.

Fully Qualified Domain Name

The “fqdn” parameter defines the hostname used to access SF services. It is an important parameter since it is used by external identity providers to redirect a user after authentication. Thus the name needs to be resolvable, either manually with the /etc/hosts, either with a proper DNS record.

This parameter will be used to create virtual host names for each service, such as zuul.fqdn and gerrit.fqdn.


If the fqdn parameter is not set, the deployment will use the default domain and users need to set their local /etc/hosts file with:



For consistency, hosts defined in the arch inventory will have their fqdn hostname set to: name.fqdn

Update FQDN

To update the fqdn, you have to change the fqdn in /etc/software-factory/sfconfig.yaml and run:



When changing the fqdn for a deployment, the fqdn is updated for config, sf-jobs and zuul-jobs projects. All the others projects configured in the software factory deployment should be updated by users.

cd myproject
git remote set-url origin https://$fqdn/r/myproject
sed -i 's/$old_fqdn/fqdn' .gitreview
git add -A .
git commit -m 'update fqdn in gitreview'
git review

SSL Certificates

By default, sfconfig creates a self-signed certificate. To use another certificate, you need to copy the required files to the install-server, e.g. in /etc/software-factory/, and set those options in sfconfig.yaml:

  tls_cert_file: /etc/software-factory/my-tls.crt
  tls_chain_file: /etc/software-factory/my-tls.chain
  tls_key_file: /etc/software-factory/my-tls.key

Then deploy the new certificates by running sfconfig.

Authorizing the localCA

When deployed using a self-signed certificate, you can authorize the local CA by adding: https://fqdn/localCA.pem to your browser’s CA trust.

Automatic TLS certificates with Let’s Encrypt

Software Factory comes with the lecm utility to automatically manage TLS certificates. To enable HTTPS security with let’s encrypt, you need to enable this option in sfconfig.yaml (and run sfconfig afterwards).

  use_letsencrypt: true

A certificate will be automatically created and renewed, you can check the status using the lecm utility:

$ lecm -l
|               Item               |     Status    |                          subjectAltName                          |                          Location                         | Days |
|     |   Generated   |                          |    /etc/letsencrypt/pem/    |  89  |

Services configuration

Check the management documentation for more details about the services configuration and how to manage them.