Here are my notes from a single-host (soon a 2-host setup just to have a separate builder as advised) deployment using SSL certificates:

• https://docs.pagure.org/koji/server_howto/#setting-up-a-koji-build-system says "all services may live on the same machine", but later it is advised to run the builder on a separate host. This should be mentioned earlier.
• typo: the on listed below => the one listed below
• https://docs.pagure.org/koji/server_howto/#setup-postgresql-and-populate-schema :
  • it says to import /usr/share/doc/koji*/docs/schema.sql but does not say where this file comes from.
  • the note that says not to replace the * in /usr/share/doc/koji*/docs/schema.sql comes too late, I already had imported the schema. I don't understand this though, from a technical point of view: "In test it was discovered that when the path is resolved to a specific version of koji then not all of the tables were created correctly."
• https://docs.pagure.org/koji/server_howto/#authorize-koji-web-and-koji-hub-resources : the second note contains uninterpreted and tags
• https://docs.pagure.org/koji/server_howto/#ssl-certificate-authentication
• https://docs.pagure.org/koji/server_howto/#etc-httpd-conf-d-ssl-conf : this section made me struggle for a full day on my single-host setup, because it made me modify ssl.conf in a way that affected not only kojihub but all components. To my understanding, SSLVerifyClient and SSLVerifyDepth are useless (and harmful), because they're already enforced for login in /etc/httpd/conf.d/kojihub.conf and /etc/httpd/conf.d/kojiweb.conf. If I understand correctly, the SSLCertificateFile change makes also kojiweb use kojihub's certificate... But since this certificate is signed by a CA that we created ourselves, it's not trusted so kojiweb is detected as insecure by browsers.
• related to that, it could be useful to give some tips for certificate signing so that kojiweb can use a proper certificate for display. For example simply say that kojiweb's certificate that we created is only for authentication and that we should use a different, signed, certificate in apache.
• https://docs.pagure.org/koji/server_howto/#authentication-configuration : it could be useful to give tips to extract the exact DN of the kojiweb certificate in the form that mod_ssl uses. It seems to be a common difficulty in deployment. I didn't find a way to produce the DN as expected by mod_ssl >= 2.3.11 so in the end I set the LegacyDNStringFormat option because information abunds on the net about how you can produce that legacy-format DN with openssl and a certificate file. The link to mod_ssl's documentation was not sufficient for me because it is incomplete on the subject of ordering. It says the C= entry is at the end, but not how to order the other entries.
• https://docs.pagure.org/koji/server_howto/#id5 : I think this is obsolete (and wrong to put it as is in ssl.conf). It's already present as a comment in kojiweb.conf and the doc already says you need to follow the instructions in that file.
• https://docs.pagure.org/koji/server_howto/#etc-kojiweb-web-conf : the example shows a ClientCA entry but there's no such entry in the default web.conf in 1.16.1. Is the doc obsolete or is it missing from the configuration file?
• https://docs.pagure.org/koji/server_howto/#etc-kojid-kojid-conf : there's a 'user' entry but it's missing from the default configuration file.
• https://docs.pagure.org/koji/server_howto/#authentication-configuration-ssl-certificates : there's a 'ca' entry but it's missing from the configuration file.
• https://docs.pagure.org/koji/server_howto/#etc-kojira-kojira-conf : there's 'ca' entry but it's missing from the configuration file
• about kojira.conf: the principal and keytab entries are uncommented in the default configuration file. They should be commented to let us uncomment the relevant lines depending on the authentication method. And they are actually present twice (once uncommented, once commented)!

Maybe some of my comments about default configuration files are not true because I first installed RPMs for 1.15.1 then updated them to 1.16.1.

In https://docs.pagure.org/koji/server_howto/#koji-filesystem-skeleton we're told to create /mnt/koji, create dirs in it then chown all those dirs to apache.

In my setup, which is based on a default apache installation in CentOS 7, this was not sufficient.

Apache wouldn't allow accessing /kojifiles/repos/7.6-build/5/x86_64/toplink/packages/, because toplink is a symlink to /mnt/koji and /mnt/koji doesn't belong to apache. Changing owner to apache fixed it. Could be related to the SymLinksIfOwnerMatch option in apache. I couldn't find it in default configuration files, but maybe it's a default.

Other missing information in the docs:

• the syntax to build from a git repository (koji build git+...) is not mentioned in the documentation at all, unless I'm mistaken
• the bootstrap guide does not mention the srpm-build group, which seems necessary

On CentOS 7 mock fails because systemd-nspawn doesn't support the --chdir option.
In mock_output.log: /usr/bin/systemd-nspawn: unrecognized option '--chdir=/chroot_tmpdir/scmroot/nfrotz'

Solutions: use a backported systemd, use a recent fedora or mageia for build nodes, disable nspawn in /etc/mock/site-defaults.cfg: config_opts['use_nspawn'] = False

You might want to warn somewhere in the docs.

Thank you very much for this list!

I set up a Koji environment recently following the docs and ran into some of these problems as well. I'm submitting PRs for each of them.

This issue has been migrated to Fedora Forge:
https://forge.fedoraproject.org/koji/koji/issues/1131

Please continue any further discussion there.