UCS Architecture Documentation: New Content and Lessons Learned from Iterative Writing

Our Univention Corporate Server (UCS) architecture documentation has grown with more content and will continue to grow. In this article, I will give you an overview of the newly added content, introduce another level of detail for administrators and solution architects, and share some of the experiences we have gained over the past few months with the new approach of iteratively delivering new documentation.

New for UCS Administrators: Product Components

The newly added section Product components in the documentation provides an overview of the UCS components that particularly administrators interact with. It briefly and clearly describes the most important components, functions and administration options of the UCS portal, the UCS management system and the Univention App Center.

In the section Services you will now find information on the following topics:

1. Subdivision of the UCS Management System into the following areas:
   • Domain Management using Univention Directory Manager (UDM)
   • System Management using Univention Management Console (UMC)
   • Configuration Management using Univention Configuration Registry (UCR)
2. Description of the UCS portal, its subdivision and the technologies used
3. Description of the App Center, how the service works in UCS, its cache, interfaces, actions, integrations and dependencies
4. Description of the Univention app ecosystem with its involved actors such as app developers, app providers and infrastructure operators, the app artifacts and the Univention App Infrastructure

Figure 1: From the document: UDM architecture

To visualize the architecture, we are currently experimenting with ArchiMate, an open standard for enterprise architecture notation and modeling. With its focus on enterprise architectures, the notation is, in my view, excellently suited to visualize the architecture of UCS. As a useful side effect, creating the views creates a formal model that allows for further analysis.

Figure 2: Product components in UCS, visualized with the notation ArchiMate

With this experiment, we want to get away from lines and boxes with their own semantics, and use an established open standard that also conveys clear semantics to the reader.

Lesson learned

Since my post UCS architecture documentation as an example of iterative writing, we have gained some insights that I would like to share:

1. Basically, iterative writing works well for the UCS architecture. We created content in blocks, and each block was reviewed for technical accuracy by different experts on the development team. Assigning specific content to experts for each topic was particularly helpful in breaking down the content.
2. The architecture document is written in the reStructuredText text format and is located in a Git repository. The Sphinx software generates a multi-page HTML document and a PDF from the sources. Moreover, it checks all links and the spelling of the document. A so-called CI/CD pipeline automates the necessary steps. This automation is a must for the publishing process to save recurring efforts and generate reproducible results. As an author, the automation helps me tremendously to keep my focus on the content.
3. So far, we have only partially implemented the agile approach. In hindsight, I think it would have been much more effective to release each of the above topic blocks as soon as they were completed. This would have meant that the content would have been available sooner and could have been useful to customers, partners, and new team members. For future work, I would especially like to start from here.

Outlook: Completing the Product components and Services

Our next goal is to complete the product components. An overview of the contact points Command line and File and Print is still lacking. Subsequently, further content expansion in the area Services is on the agenda. This includes the topics LDAP, Listener, Hooks, UDM REST API, authentication (PAM, LDAP, Kerberos, OpenID Connect, SAML), Samba, networking, email, and monitoring. If you have any preferences for topic priorities, please let me know in the comments.

Of course, any feedback on the architecture documentation is more than welcome. Please use the feedback link next to each heading for this. The link appears in the HTML document to the right of a heading when you hover over it. Also here I will be happy to answer any questions. Leave a comment below the article.