From a1f8bd66ae1aff2e3d4dcb3f07702d0b9d83ed92 Mon Sep 17 00:00:00 2001
From: Maarten de Waard <maarten@greenhost.nl>
Date: Thu, 9 Jan 2020 14:32:40 +0100
Subject: [PATCH] move existing documentation into sphinx format
---
.gitignore | 1 +
README.md | 50 +-----------------------
VERSION | 1 +
docs/Makefile | 20 ++++++++++
docs/conf.py | 60 ++++++++++++++++++++++++++++
docs/helmchart.md | 62 +++++++++++++++++++++++++++++
docs/index.rst | 20 ++++++++++
docs/installation_instructions.md | 14 +++++++
docs/local_development.md | 29 ++++++++++++++
docs/make.bat | 35 +++++++++++++++++
docs/requirements.txt | 3 ++
docs/usage.md | 12 ++++++
helmchart/single-sign-on/README.md | 63 +-----------------------------
13 files changed, 259 insertions(+), 111 deletions(-)
create mode 100644 VERSION
create mode 100644 docs/Makefile
create mode 100644 docs/conf.py
create mode 100644 docs/helmchart.md
create mode 100644 docs/index.rst
create mode 100644 docs/installation_instructions.md
create mode 100644 docs/local_development.md
create mode 100644 docs/make.bat
create mode 100644 docs/requirements.txt
create mode 100644 docs/usage.md
diff --git a/.gitignore b/.gitignore
index fd89143..5b19dca 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+docs/_build/
.env
__pycache__
*.lock
diff --git a/README.md b/README.md
index dbb9eda..cfe29c7 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1 @@
-# Install
-
-Clone the repo and make sure to also fetch the submodules.
-```
-git submodule update --init
-```
-
-Installation should be done via the helm using the helmchart contained in `./helmchart`.
-Make sure to edit the values in `./helmchart/single-sign-on/values.yaml` according to your needs
-
-For Details on how to configure the chart. Refer to `./helmchart/single-sign-on/README.md`
-
-# Using SSO
-
-To use OpenID Connect or oAuth you need to set up an oAuth Client for every application that
-needs to authenticate it's users. You can leverage the Hydra Admin API to create oAuth clients.
-As a starting point, you can have a look at the script provided in `test/`.
-
-To use SSO, configure your oAuth client (for example nextcloud) and create a new oAuth client object.
-After your server is running, refer to `https://sso.<YOUR.DOMAIN>/.well-known/openid-configuration` as a reference on how to configure your openID Connect or oAuth client.
-
-# Testing
-
-In order to run tests locally, you can start the environment via `docker-compose`.
-Install docker-compose via `pip install docker-compose` after you [insalled
-docker](https://docs.docker.com/v17.12/install/) on your machine.
-Running `docker-compose up --build` after that builds and starts all containers.
-The default configuration works if you are running the setup on your local
-machine. You need to change the following values in the docker-compose.yml file in case
-you run the containers on a remote machine:
-
-```
- environment:
- - URLS_SELF_ISSUER=http://YOUR_SERVER_FQDN:4444/
- - URLS_CONSENT=http://YOUR_SERVER_FQDN:5001/
- - URLS_LOGIN=http://YOUR_SERVER_FQDN:5000/
- - URLS_LOGOUT=http://YOUR_SERVER_FQDN:5000/logout
- - URLS_POST_LOGOUT_REDIRECT=http://YOUR_SERVER_FQDN:5000/
-```
-
-Notice that you need to create users and applications before being able to login.
-You can use the scripts located in `user-panel/utils` to create users for testing.
-
-If you don't have a test application yourself, you can use the small OpeinID Connect
-test application located at `test/login_logout/`. Instructions on how to run the test
-application can be found in `test/login_logout/README.md`.
-
-Also refer to `.gitlab-ci.yml` to get an idea on how to run all of the tests that are
-contained in this repository.
+Please refer to the [online documentation](...) for all the details
diff --git a/VERSION b/VERSION
new file mode 100644
index 0000000..3b04cfb
--- /dev/null
+++ b/VERSION
@@ -0,0 +1 @@
+0.2
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d4bb2cb
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..758b3a7
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,60 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'single-sign-on'
+copyright = '2020, OpenAppStack'
+author = 'OpenAppStack'
+
+# The full version, including alpha/beta/rc tags
+with open('../VERSION') as version_file:
+ release = version_file.read()
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ 'recommonmark'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Readthedocs.io needs us to tell it what the index file is. This defaults to
+# 'contents'
+master_doc = 'index'
diff --git a/docs/helmchart.md b/docs/helmchart.md
new file mode 100644
index 0000000..d4cdec9
--- /dev/null
+++ b/docs/helmchart.md
@@ -0,0 +1,62 @@
+# Single sign-on
+
+Single sign-on adds an Authentication server to your k8s cluster, that can be used by
+applications within your cluster and by external applications to log in your users.
+This chart also includes a minimalistic user-panel which can be used
+to create new users, assign roles to users and grant users access to applications.
+
+## Prerequisites
+
+ * Kubernetes 1.13+ with Beta APIs enabled
+ * helm 2.14.3+
+ * ORY helm chart repository installed
+ * `helm repo add ory https://k8s.ory.sh/helm/charts && helm repo update`
+
+## Configuration
+
+You can configure the chart by changing the default values in the `./values.yaml` file.
+The following table lists the configurable parameters of the single sign-on chart and their
+default values. Values in **bold** letters need to be changed for Routing and TLS to work.
+
+| Parameter | Description | Default |
+| ------------------------------------ | ------------------------------------------------------- | ------------------------- |
+| `singleSignOnHost` | **FQDN of the openID Connect / oAuth2 server** | **sso.oas.example.net** |
+| `loginProviderImage.repository` | Name of image repository to be used for login provider | open.greenhost.net:4567/openappstack/single-sign-on/login_provider |
+| `loginProviderImage.tag` | Release version of login provider image | master |
+| `consentProviderImage.repository` | Name of image repository to be used for consent provider| open.greenhost.net:4567/openappstack/single-sign-on/consent_provider |
+| `consentProviderImage.tag` | Release version of consent provider image | master |
+| `userpanel.ingress.host` | **FQDN of the userpanel** | **admin.oas.example.net** |
+| `userpanel.oAuth.client_secret` | oAuth2 client secret | YouReallyNeedToChangeThis |
+| `userbackend.username` | Username of the admin user | admin |
+| `userbackend.password` | Password of the admin user | YouReallyNeedToChangeThis |
+| `userbackend.email` | Email address of the admin user | admin@example.net |
+| `userbackend.postgres.password` | Root pw of the psql DB | postgres |
+| `hydra.hydra.config.urls.self.issuer`| **Base URI of the oAuth server** | **https://sso.oas.example.net** |
+| `hydra.hydra.config.urls.login` | **URI that will be used for the login page** | **https://sso.oas.example.net/login** |
+| `hydra.hydra.config.urls.consent` | **URI that will be used for permission checks** | **https://sso.oas.example.net/consent** |
+| `hydra.hydra.config.secrets.system` | Secret that is used to generate secure tokens | YouReallyNeedToChangeThis |
+
+## Installing and uninstalling the Chart
+
+To install the chart with the realease name `single-sign-on` first clone the repository,
+and then run helm install.
+
+```
+$ git clone https://open.greenhost.net/openappstack/single-sign-on
+$ cd single-sign-on/helmchart/single-sign-on/
+$ helm install -n single-sign-on .
+```
+
+The last command will deploy the single sign-on components on your server and applies a
+default configuration. You should change the default configuration before running the command.
+The [configuration](#configuration) section lists all configuration parameters.
+
+In case you already ran the install command, you can uninstall the deployment by executing:
+
+```
+$ helm list # [OPTIONAL] - Lists all deployed releases
+$ helm delete single-sign-on --purge
+```
+
+> **WARNING**: Executing the `delete` command with the `purge` flag will delete all data that is related to the applications. Don't run this command in a production environment if you are not absolutely sure that you have a restorable backup of your data.
+
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..78f3efa
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,20 @@
+.. single-sign-on documentation master file, created by
+ sphinx-quickstart on Thu Jan 9 10:37:53 2020.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to single-sign-on's documentation!
+==========================================
+
+This project provides a single sign on solution based on
+[hydra](https://github.com/ory/hydra) and in combination with a [user
+panel](https://open.greenhost.net/openappstack/user-panel).
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ installation_instructions
+ usage
+ helmchart
+ local_development
diff --git a/docs/installation_instructions.md b/docs/installation_instructions.md
new file mode 100644
index 0000000..a51f902
--- /dev/null
+++ b/docs/installation_instructions.md
@@ -0,0 +1,14 @@
+## Install
+
+Clone the repo and make sure to also fetch the submodules.
+```
+git submodule update --init
+```
+
+Installation should be done via the helm using the helmchart contained in
+`./helmchart`. Make sure to edit the values in
+`./helmchart/single-sign-on/values.yaml` according to your needs
+
+For Details on how to configure the chart. Refer to
+`./helmchart/single-sign-on/README.md`
+
diff --git a/docs/local_development.md b/docs/local_development.md
new file mode 100644
index 0000000..56eb18e
--- /dev/null
+++ b/docs/local_development.md
@@ -0,0 +1,29 @@
+# Testing
+
+In order to run tests locally, you can start the environment via
+`docker-compose`. Install docker-compose via `pip install docker-compose` after
+you [insalled docker](https://docs.docker.com/v17.12/install/) on your machine.
+Running `docker-compose up --build` after that builds and starts all containers.
+The default configuration works if you are running the setup on your local
+machine. You need to change the following values in the docker-compose.yml file
+in case you run the containers on a remote machine:
+
+```yaml
+environment:
+ - URLS_SELF_ISSUER=http://YOUR_SERVER_FQDN:4444/
+ - URLS_CONSENT=http://YOUR_SERVER_FQDN:5001/
+ - URLS_LOGIN=http://YOUR_SERVER_FQDN:5000/
+ - URLS_LOGOUT=http://YOUR_SERVER_FQDN:5000/logout
+ - URLS_POST_LOGOUT_REDIRECT=http://YOUR_SERVER_FQDN:5000/ ```
+```
+
+Notice that you need to create users and applications before being able to
+login. You can use the scripts located in `user-panel/utils` to create users
+for testing.
+
+If you don't have a test application yourself, you can use the small OpeinID
+Connect test application located at `test/login_logout/`. Instructions on how to
+run the test application can be found in `test/login_logout/README.md`.
+
+Also refer to `.gitlab-ci.yml` to get an idea on how to run all of the tests
+that are contained in this repository.
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..2119f51
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..020d719
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,3 @@
+sphinx>=2.3.1
+sphinx_rtd_theme>=0.4.3
+recommonmark>=0.6.0
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..0ff7c8d
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,12 @@
+## Using SSO
+
+To use OpenID Connect or oAuth you need to set up an oAuth Client for every
+application that needs to authenticate it's users. You can leverage the Hydra
+Admin API to create oAuth clients. As a starting point, you can have a look at
+the script provided in `test/`.
+
+To use SSO, configure your oAuth client (for example nextcloud) and create a new
+oAuth client object. After your server is running, refer to
+`https://sso.<YOUR.DOMAIN>/.well-known/openid-configuration` as a reference on
+how to configure your openID Connect or oAuth client.
+
diff --git a/helmchart/single-sign-on/README.md b/helmchart/single-sign-on/README.md
index d4cdec9..7fba9ed 100644
--- a/helmchart/single-sign-on/README.md
+++ b/helmchart/single-sign-on/README.md
@@ -1,62 +1 @@
-# Single sign-on
-
-Single sign-on adds an Authentication server to your k8s cluster, that can be used by
-applications within your cluster and by external applications to log in your users.
-This chart also includes a minimalistic user-panel which can be used
-to create new users, assign roles to users and grant users access to applications.
-
-## Prerequisites
-
- * Kubernetes 1.13+ with Beta APIs enabled
- * helm 2.14.3+
- * ORY helm chart repository installed
- * `helm repo add ory https://k8s.ory.sh/helm/charts && helm repo update`
-
-## Configuration
-
-You can configure the chart by changing the default values in the `./values.yaml` file.
-The following table lists the configurable parameters of the single sign-on chart and their
-default values. Values in **bold** letters need to be changed for Routing and TLS to work.
-
-| Parameter | Description | Default |
-| ------------------------------------ | ------------------------------------------------------- | ------------------------- |
-| `singleSignOnHost` | **FQDN of the openID Connect / oAuth2 server** | **sso.oas.example.net** |
-| `loginProviderImage.repository` | Name of image repository to be used for login provider | open.greenhost.net:4567/openappstack/single-sign-on/login_provider |
-| `loginProviderImage.tag` | Release version of login provider image | master |
-| `consentProviderImage.repository` | Name of image repository to be used for consent provider| open.greenhost.net:4567/openappstack/single-sign-on/consent_provider |
-| `consentProviderImage.tag` | Release version of consent provider image | master |
-| `userpanel.ingress.host` | **FQDN of the userpanel** | **admin.oas.example.net** |
-| `userpanel.oAuth.client_secret` | oAuth2 client secret | YouReallyNeedToChangeThis |
-| `userbackend.username` | Username of the admin user | admin |
-| `userbackend.password` | Password of the admin user | YouReallyNeedToChangeThis |
-| `userbackend.email` | Email address of the admin user | admin@example.net |
-| `userbackend.postgres.password` | Root pw of the psql DB | postgres |
-| `hydra.hydra.config.urls.self.issuer`| **Base URI of the oAuth server** | **https://sso.oas.example.net** |
-| `hydra.hydra.config.urls.login` | **URI that will be used for the login page** | **https://sso.oas.example.net/login** |
-| `hydra.hydra.config.urls.consent` | **URI that will be used for permission checks** | **https://sso.oas.example.net/consent** |
-| `hydra.hydra.config.secrets.system` | Secret that is used to generate secure tokens | YouReallyNeedToChangeThis |
-
-## Installing and uninstalling the Chart
-
-To install the chart with the realease name `single-sign-on` first clone the repository,
-and then run helm install.
-
-```
-$ git clone https://open.greenhost.net/openappstack/single-sign-on
-$ cd single-sign-on/helmchart/single-sign-on/
-$ helm install -n single-sign-on .
-```
-
-The last command will deploy the single sign-on components on your server and applies a
-default configuration. You should change the default configuration before running the command.
-The [configuration](#configuration) section lists all configuration parameters.
-
-In case you already ran the install command, you can uninstall the deployment by executing:
-
-```
-$ helm list # [OPTIONAL] - Lists all deployed releases
-$ helm delete single-sign-on --purge
-```
-
-> **WARNING**: Executing the `delete` command with the `purge` flag will delete all data that is related to the applications. Don't run this command in a production environment if you are not absolutely sure that you have a restorable backup of your data.
-
+Please refer to the [online documentation](.../helmchart)
--
GitLab