Organizations management page

Makefile

@@ -0,0 +1,41 @@
+pages   := $(shell find . -type f -name '*.adoc')
+
+# Determine whether to use podman
+#
+# podman currently fails when executing in GitHub actions on Ubuntu LTS 20.04,
+# so we never use podman if GITHUB_ACTIONS==true.
+use_podman := $(shell command -v podman 2>&1 >/dev/null; p="$$?"; \
+		if [ "$${GITHUB_ACTIONS}" != "true" ]; then echo "$$p"; else echo 1; fi)
+
+ifeq ($(use_podman),0)
+	engine_cmd  ?= podman
+	engine_opts ?= --rm --tty --userns=keep-id
+else
+	engine_cmd  ?= docker
+	engine_opts ?= --rm --tty --user "$$(id -u)"
+endif
+
+preview_cmd ?= docker run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora vshn/antora-preview:3.0.1.1 --antora=docs --style=appuio
+vale_cmd ?= $(engine_cmd) run $(engine_opts) --volume "$${PWD}"/docs/modules:/pages:Z docker.io/vshn/vale:2.10.5.1 --minAlertLevel=error --config=/pages/ROOT/pages/.vale.ini /pages
+
+UNAME := $(shell uname)
+ifeq ($(UNAME), Linux)
+	OS = linux-x64
+	OPEN = xdg-open
+endif
+ifeq ($(UNAME), Darwin)
+	OS = darwin-x64
+	OPEN = open
+endif
+
+.PHONY: check
+check: ## Run vale agains the documentation to check writing style
+	$(vale_cmd)
+
+.PHONY: preview
+preview: ## Start the preview server with live reload capabilities, available under http://localhost:2020
+	$(preview_cmd)
+
+.PHONY: help
+help: ## Show this help
+	@grep -E -h '\s##\s' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'

docs/modules/ROOT/nav.adoc

@@ -1 +1,4 @@
 * xref:index.adoc[Home]
+
+.How-to guides
+** xref:how-to/organizations.adoc[Managing Organizations]

docs/modules/ROOT/pages/.vale.ini

@@ -0,0 +1,10 @@
+StylesPath = /styles
+MinAlertLevel = warning # suggestion, warning or error
+
+# Only check Asciidoc files
+[*.adoc]
+
+# Using the Microsoft style
+BasedOnStyles = Microsoft
+Microsoft.GenderBias = warning
+Microsoft.RangeFormat = warning

docs/modules/ROOT/pages/how-to/organizations.adoc

@@ -0,0 +1,45 @@
+= Managing Organizations
+
+One of the basic features of the {product} Portal is to provide a centralized location for users to manage access to their projects across all {product} zones.
+
+== Concepts
+
+{product} allows namespaces and projects to belong to a particular {product} organization, as explained in the https://docs.appuio.cloud/user/how-to/manage-projects-and-namespaces.html[Manage Projects and Namespaces] documentation page. On the other hand, the https://control.vshn.net/[VSHN Control Panel] also provides customer management features. Finally, OpenShift also provides a notion of Groups. How are all of these concepts related?
+
+{product} Organizations aren't related to VSHN Control Panel customers nor to OpenShift groups. This makes them independent and cross-zones; this means that a {product} Organization spans across {product} zones automatically, allowing users to grant or deny access to projects from a central location.
+
+== Finding your Username
+
+In order to be able to assign users to organizations, users need to know their username. Users not assigned to an organization are reminded to join one as soon as they log in to the {product} Portal for the first time.
+
+image::how-to/organizations/welcome.png[]
+
+By default, your list of organizations will be empty.
+
+image::how-to/organizations/empty.png[]
+
+== Creating an Organization
+
+To create an organization, click the menu:Organization[] item on the navigation, and then click on the btn:[Add new Organization] button.
+
+image::how-to/organizations/new.png[]
+
+Fill the form with the required information, and click the btn:[Save] button.
+
+The "Name" field is the same one that you must use in your YAML to request the creation of a namespace assigned to your organization. Once created, the organization will appear in your profile.
+
+CAUTION: The name of an organization can't be changed, but you can change its display name.
+
+image::how-to/organizations/list.png[]
+
+== Adding and Removing Users
+
+To add and remove members of an organization, you must be owner of the organization, and you need to know the username of the users you would like to add to it.
+
+Click on the icon:user-group[] "user group" icon next to the name of the organization, and enter the names of the members of your organization. The username of the organization owner appears as the first user.
+
+Click on the btn:[Save] button when done. After a few minutes, those users will be able to access {product} namespaces assigned to your organization.
+
+WARNING: At this time it isn't possible to remove organizations. If you would like to remove an organization, please contact VSHN support.
+
+image::how-to/organizations/members.png[]

docs/modules/ROOT/pages/index.adoc

@@ -1,3 +1,15 @@
-= APPUiO Cloud Portal
+= APPUiO Cloud Portal Documentation
 
-This is the documentation of the https://portal.appuio.cloud/[APPUiO Cloud Portal].
+image::appuio-cloud.svg[APPUiO Cloud,400,link=https://www.appuio.ch/en/offering/cloud/]
+
+Welcome to the https://portal.appuio.cloud/[{product} Portal] documentation site.
+
+[TIP]
+====
+Contributions to the documentation are welcome.
+Just click on btn:[Edit this Page] top-right or head over to https://github.com/appuio/appuio-cloud-docs[GitHub] where the content source is stored.
+====
+
+Didn't find the information you were looking for?
+Would you like to suggest a new help topic?
+https://docs.appuio.cloud/user/contact.html[Get in touch with us.]