From 28d1ed64ecc963fe34d874b59cffb0e61ed67c1d Mon Sep 17 00:00:00 2001 From: Thierry Carrez Date: Wed, 26 Feb 2020 16:10:17 +0100 Subject: [PATCH] POC Xwiki farm at wiki.opendev.org This spec describes evaluating Xwiki as a potential wiki farm setup for Opendev communities at wiki.opendev.org, using an initial test community and initially leveraging Xwiki.com "open source free hosting" offer. Change-Id: Iacc3ad4af69d99ac61ecc51ddaf2c345c3f01f9a --- doc/source/index.rst | 3 +- specs/xwiki-farm.rst | 208 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 210 insertions(+), 1 deletion(-) create mode 100644 specs/xwiki-farm.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index fd1cc4f..c489d89 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -34,6 +34,7 @@ permits. specs/cleanup-test-node-python specs/deploy-ci-dashboard specs/jenkins-job-builder_2.0.0-api-changes + specs/jitsi-meet specs/nodepool-drivers specs/puppet-module-functional-testing specs/refstack_dot_org @@ -44,7 +45,7 @@ permits. specs/translation_check_site specs/wiki_modernization specs/website-stats - specs/jitsi-meet + specs/xwiki-farm Help Wanted =========== diff --git a/specs/xwiki-farm.rst b/specs/xwiki-farm.rst new file mode 100644 index 0000000..68636d5 --- /dev/null +++ b/specs/xwiki-farm.rst @@ -0,0 +1,208 @@ +:: + + Copyright 2020 Thierry Carrez + + This work is licensed under a Creative Commons Attribution 3.0 + Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode + +========== +Xwiki farm +========== + +This document describes setting up a wiki farm based on `Xwiki`_ to serve the +needs for lightweight, structured document publication (between etherpad +and git-driven formal documentation) within Opendev communities. + +Problem Description +=================== + +Opendev serves multiple subcommunities. Some of them have expressed the need +for a wiki: a lightweight way to publish information while retaining clear +history and authorship. This is traditionally very helpful at early stages +of the formation of communities. + +Our current response is to ask them to set up pages on the Mediawiki instance +on wiki.openstack.org. Beyond the obvious domain problem, this creates +additional issues: + +* it increases our dependency on a difficult-to-maintain platform + +* it makes it hard to structure information or search within a given community + scope + +Proposed Change +=============== + +I evaluated various solutions. `Xwiki`_ emerged as a good candidate: + +* open source (although a bit open core) + +* limited maintenance costs, includes `spam prevention tooling`_ + +* `"structured wiki"`_ approach, which limits stale pages + +* pluggable into openstackID for authentication + +* support for `subwikis`_ (wikis with a root document and search context which + live under the same main wiki domain) allowing each community to have what + looks like a separate wiki + +`Xwiki.com`_, the company behind Xwiki, offers `free hosting`_ for open source +communities. That offer is for the basic version of their cloud service. +It includes up to 10 subwikis, unlimited users, 20Gb of storage, and limited +tech support. They agreed to include usage of a custom domain, as well as +manual configuration of OpenStackID authentication, although it would +technically not be covered in the free hosting offer. + +As a proof-of-concept, we propose to accept the free hosting offer and set up +a wiki farm at wiki.opendev.org. Then we'd evaluate the software using a +guinea pig community. + +The OSF is helping bootstrapping the OpenInfra labs community (formerly +known as Massachussets Open Cloud), a community of practice around operating +OpenStack clouds for academic networks. That community is interested in +using Opendev for project infrastructure, including Gerrit for managing code +repositories. At those early stages they need a mailing-list (already set up +at lists.opendev.org) and a wiki to share information. + +The proposed plan is to create a subwiki for the Open Infra Labs community, +and after some time evaluate how successful that setup is, before thinking +about next steps (offer subwikis to other communities, hosting ourselves). + +.. _`Xwiki`: https://xwiki.org +.. _`spam prevention tooling`: https://www.xwiki.org/xwiki/bin/view/Documentation/AdminGuide/AntiSpam +.. _`"structured wiki"`: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/ContentOrganization/ +.. _`subwikis`: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/ContentOrganization/WikiVsNestedPages/ +.. _`Xwiki.com`: https://xwiki.com +.. _`free hosting`: https://xwiki.com/en/Blog/XWikiCloudFreeForOpenSource + +Alternatives +------------ + +Doubling down on Mediawiki +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We could host separate Mediawikis for each community under OpenDev, based on +the puppet modules that we use to maintain wiki.openstack.org. However +mediawiki has not been very pleasant to maintain, and we tried to reduce our +exposure to it rather than increase it. Xwiki's structured pages model also +seems more adapted to our needs than Mediawiki's flat model. + +Enabling gitea-wiki +~~~~~~~~~~~~~~~~~~~ + +Gitea has a nice wiki feature (attached to specific repositories rather than +specific communities). Since we are already using Gitea, it would make sense +to enable that feature instead of relying on additional software. + +However our gitea system is currently a set of independent setups, kept in +sync via git pushes from gerrit. To enable the wiki feature, you need to be +able to write to the git repos within gitea (and keep that consistent across +the installation), which is still an unsolved problem at this point. +Additionally, you need to enable user management and authentication support +in Gitea, which is also an area nobody is planning to work on. + +Direct Xwiki hosting +~~~~~~~~~~~~~~~~~~~~ + +We could host Xwiki directly, rather than rely on Xwiki.com cloud hosting. +That would have the benefit of not appearing to endorse an open core +company, and keep our data and access log under our direct control. However, +the open core model followed by Xwiki.com relies on a relatively sane +demarcation between xwiki code and "pro" plugins, and Xwiki.com being a +French company, they have to abide to pretty drastic data collection, +retention and communication laws. Overall, the benefits of being able to +outsource hosting and maintenance of the platform, as well as the immediate +availability of the solution, justifies the positive trade-off. + +Shall the proof-of-concept be successful, or shall we ever exceed the +10-subwiki limit, we would consider self-hosting the solution. Usage of a +custom domain reduced the impact of a future transition. + +Open questions +-------------- + +Authentication +~~~~~~~~~~~~~~ + +Opendev did not make a clear decision on single-sign-on. As such, +wiki.opendev.org would be set up with OpenStackID integration to avoid +creating another set of crednetials, or increasing our UbuntuOne technical +debt. Should we migrate to another SSO solution in the future, accounts for +the proof-of-concept can easily be recreated if that ends up being necessary. + +However this issue should be tackled before we expand to other subwikis, and +certainly before we ever consider moving wiki.openstack.org content. + +SSL +~~~ + +It is unclear at this moment how SSL certificate would be handled for +wiki.opendev.org. This should be clarified with Xwiki support as we set up +the instance. + + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + ttx + +Gerrit Topic +------------ + +Use Gerrit topic "xwiki-farm" for all patches related to this spec. + +.. code-block:: bash + + git-review -t xwiki-farm + +Work Items +---------- + +* Set up main instance with OpenStackID integration, SSL. +* Set up openinfralabs subwiki and open it up in that community +* Evaluate after a few months of usage + +Repositories +------------ + +None. + +Servers +------- + +None. + +DNS Entries +----------- + +wiki.opendev.org will have to be created a point to wherever XWiki.com +asks us to point. + +Documentation +------------- + +Documentation of the wiki set up should be added. + +Security +-------- + +Wiki is isolated from the rest of opendev systems. We should make sure we do +not accidentally leak profile information (by default Xwiki lists email +addresses and OIDC addresses in the autogenarted profile page, this needs to +be disabled). + +Testing +------- + +None. + +Dependencies +============ + +None.