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
This commit is contained in:
Thierry Carrez 2020-02-26 16:10:17 +01:00
parent b61b4370af
commit 28d1ed64ec
2 changed files with 210 additions and 1 deletions

View File

@ -34,6 +34,7 @@ permits.
specs/cleanup-test-node-python specs/cleanup-test-node-python
specs/deploy-ci-dashboard specs/deploy-ci-dashboard
specs/jenkins-job-builder_2.0.0-api-changes specs/jenkins-job-builder_2.0.0-api-changes
specs/jitsi-meet
specs/nodepool-drivers specs/nodepool-drivers
specs/puppet-module-functional-testing specs/puppet-module-functional-testing
specs/refstack_dot_org specs/refstack_dot_org
@ -44,7 +45,7 @@ permits.
specs/translation_check_site specs/translation_check_site
specs/wiki_modernization specs/wiki_modernization
specs/website-stats specs/website-stats
specs/jitsi-meet specs/xwiki-farm
Help Wanted Help Wanted
=========== ===========

208
specs/xwiki-farm.rst Normal file
View File

@ -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.