Merge pull request #874 from owncloud/improve_docs

[docs-only] improve docs
owncloud · Nov 19, 2020 · 0ea04c0 · 0ea04c0
2 parents 2dcaae3 + e91d67e
commit 0ea04c0
Show file tree

Hide file tree

Showing 39 changed files with 358 additions and 441 deletions.
diff --git a/accounts/templates/CONFIGURATION.tmpl b/accounts/templates/CONFIGURATION.tmpl
@@ -3,8 +3,8 @@ title: "Configuration"
 date: "{{ date "2006-01-02T15:04:05-0700" now }}"
 weight: 20
 geekdocRepo: https://github.com/owncloud/ocis
-geekdocEditPath: edit/master/docs/extensions/accounts
-geekdocFilePath: configuration.md
+geekdocEditPath: edit/master/accounts/templates
+geekdocFilePath: CONFIGURATION.tmpl
 ---
 {{- define "options"}}
 {{ $fnName := (last . ).Flags -}}
@@ -41,7 +41,7 @@ For this configuration to be picked up, have a look at your extension `root` com
 
 So far we support the file formats `JSON` and `YAML`, if you want to get a full example configuration just take a look at [our repository](https://github.com/owncloud/ocis/tree/master/config), there you can always see the latest configuration format. These example configurations include all available options and the default values. The configuration file will be automatically loaded if it's placed at `/etc/ocis/ocis.yml`, `${HOME}/.ocis/ocis.yml` or `$(pwd)/config/ocis.yml`.
 
-### Envrionment variables
+### Environment variables
 
 If you prefer to configure the service with environment variables you can see the available variables below.
 

diff --git a/docs/_index.md b/docs/_index.md
@@ -4,10 +4,15 @@ title: ownCloud
 
 ## Developer Documentation
 
-Welcome to our developer documentation. Here you can find documentation for developers on 
-- The oCIS server 
+Welcome to our developer documentation. Here you can find developer documentation on:
+
+- [oCIS](https://owncloud.github.io/ocis/) server
 - oCIS extensions
-- All Client, like Android, iOS, and the Desktop Client
+- Clients, like:
+    - [Phoenix](https://github.com/owncloud/phoenix) - the new web frontend for oCIS and ownCloud
+    - [ownCloud Android app](https://github.com/owncloud/android)
+    - [ownCloud iOS app](https://github.com/owncloud/ios-app)
+    - [ownCloud Desktop Syncing Client](https://github.com/owncloud/client)
 - Integrations
 
 ## We love open source
@@ -19,11 +24,10 @@ You can also find all client sources on github.
 
 ## Join us
 
-The oCIS server repository on github is a good entrypoint for you to join the project. But we also develop clients for iOS, Android, Desktop and Web.
+The oCIS server repository on github is a good entry point for you to join the project. But we also develop clients for iOS, Android, Desktop and Web.
 
-For communication on development you can join our public chat https://talk.owncloud.com
+For communication on development you can join our public chat [talk.owncloud.com](https://talk.owncloud.com)
 
-If you want to help and improve ownCloud, start coding or open issues on github in the related repositiory. 
+If you want to help and improve ownCloud or oCIS, start coding or open issues on github in the related repository.
 
 We are very happy to hear your feedback and ideas!
-
diff --git a/docs/extensions/accounts/_index.md b/docs/extensions/accounts/_index.md
@@ -7,14 +7,12 @@ geekdocEditPath: edit/master/docs/extensions/accounts
 geekdocFilePath: _index.md
 ---
 
-[![GitHub](https://img.shields.io/github/license/owncloud/ocis-hello)](https://github.com/owncloud/ocis-hello/blob/master/LICENSE)
-
 ## Abstract
-OCIS needs to be able to identify users. Whithout a non reassignable and persistend account ID share metadata cannot be reliably persisted. `ocis-accounts` allows exchanging oidc claims for a uuid. Using a uuid allows users to change the login, mail or even openid connect provider without breaking any persisted metadata that might have been attached to it.
+oCIS needs to be able to identify users. Without a non reassignable and persistent account ID share metadata cannot be reliably persisted. `accounts` allows exchanging oidc claims for a uuid. Using a uuid allows users to change the login, mail or even openid connect provider without breaking any persisted metadata that might have been attached to it.
 
 - persists accounts
 - uses graph api properties
-  -ldap can be synced using the onpremise* attributes
+- ldap can be synced using the onpremise* attributes
 
 ## Table of Contents
 

diff --git a/docs/extensions/accounts/getting-started.md b/docs/extensions/accounts/getting-started.md
@@ -20,49 +20,3 @@ TBD
 ### Binaries
 
 TBD
-
-## Configuration
-
-We provide overall three different variants of configuration. The variant based on environment variables and commandline flags are split up into global values and command-specific values.
-
-### Envrionment variables
-
-If you prefer to configure the service with environment variables you can see the available variables below.
-
-#### Server
-
-OCIS_ACCOUNTS_NAME
-: Name of the accounts service. It will be part of the namespace.
-
-OCIS_ACCOUNTS_NAMESPACE
-: Namespace of the accounts service.
-
-OCIS_ACCOUNTS_ADDRESS
-: Endpoint for the grpc service endpoint.
-
-### Commandline flags
-
-If you prefer to configure the service with commandline flags you can see the available variables below.
-
-### Configuration file
-
-So far we support the file formats `JSON` and `YAML`, if you want to get a full example configuration just take a look at [our repository](https://github.com/owncloud/ocis/accounts/tree/master/pkg/config), there you can always see the latest configuration format. These example configurations include all available options and the default values. The configuration file will be automatically loaded if it's placed at `/etc/ocis/accounts.yml`, `${HOME}/.ocis/accounts.yml` or `$(pwd)/config/accounts.yml`.
-
-## Usage
-
-The program provides a few sub-commands on execution. The available configuration methods have already been mentioned above. Generally you can always see a formated help output if you execute the binary via `ocis-accounts --help`.
-
-### Server
-
-The server command is used to start the grpc server. For further help please execute:
-
-{{< highlight txt >}}
-accounts server --help
-{{< / highlight >}}
-
-### Version
-The version command lists the versions of all running instances. For further help please execute:
-
-{{< highlight txt >}}
-accounts version --help
-{{< /highlight >}}
diff --git a/docs/extensions/ocis-phoenix/getting-started.md b/docs/extensions/ocis-phoenix/getting-started.md
@@ -25,7 +25,7 @@ TBD
 
 We provide overall three different variants of configuration. The variant based on environment variables and commandline flags are split up into global values and command-specific values.
 
-### Envrionment variables
+### Environment variables
 
 If you prefer to configure the service with environment variables you can see the available variables below.
 

diff --git a/docs/extensions/ocis-phoenix/releasing.md b/docs/extensions/ocis-phoenix/releasing.md
@@ -10,7 +10,7 @@ geekdocFilePath: releasing.md
 
 ## Releasing
 
-The next generation Web Frontend is shipped as an ocis Extension. The `ocis-phoenix` extension is also embedded in the single binary and part of the `ocis server` command.
+The next generation Web Frontend is shipped as an oCIS Extension. The `ocis-phoenix` extension is also embedded in the single binary and part of the `ocis server` command.
 
 To update this package within all the deliveries, we need to update the package in the following chain from the bottom to the top.
 

diff --git a/docs/extensions/proxy/_index.md b/docs/extensions/proxy/_index.md
@@ -5,4 +5,4 @@ geekdocEditPath: edit/master/docs/extensions/proxy
 geekdocFilePath: _index.md
 ---
 
-This service provides a basic proxy in front of the public ocis services.
+This service provides a basic proxy in front of the public oCIS services.
diff --git a/docs/extensions/settings/getting-started.md b/docs/extensions/settings/getting-started.md
@@ -25,7 +25,7 @@ TBD
 
 We provide overall three different variants of configuration. The variant based on environment variables and commandline flags are split up into global values and command-specific values.
 
-### Envrionment variables
+### Environment variables
 
 If you prefer to configure the service with environment variables you can see the available variables below.
 

diff --git a/docs/extensions/settings/glossary.md b/docs/extensions/settings/glossary.md
@@ -32,7 +32,7 @@ In the context of this extension and oCIS in general, we are using the following
 ### Settings Bundle
 
 - Collection of related settings
-- Registered by an ocis extension
+- Registered by an oCIS extension
 
 ### Settings Value
 

diff --git a/docs/extensions/store/getting-started.md b/docs/extensions/store/getting-started.md
@@ -25,7 +25,7 @@ TBD
 
 We provide overall three different variants of configuration. The variant based on environment variables and commandline flags are split up into global values and command-specific values.
 
-### Envrionment variables
+### Environment variables
 
 If you prefer to configure the service with environment variables you can see the available variables below.
 

diff --git a/docs/extensions/thumbnails/getting-started.md b/docs/extensions/thumbnails/getting-started.md
@@ -25,7 +25,7 @@ TBD
 
 We provide overall three different variants of configuration. The variant based on environment variables and commandline flags are split up into global values and command-specific values.
 
-### Envrionment variables
+### Environment variables
 
 If you prefer to configure the service with environment variables you can see the available variables below.
 

diff --git a/docs/extensions/webdav/getting-started.md b/docs/extensions/webdav/getting-started.md
@@ -25,7 +25,7 @@ TBD
 
 We provide overall three different variants of configuration. The variant based on environment variables and commandline flags are split up into global values and command-specific values.
 
-#### Envrionment variables
+#### Environment variables
 
 If you prefer to configure the service with environment variables you can see the available variables below.
 

diff --git a/docs/ocis/_index.md b/docs/ocis/_index.md
@@ -1,5 +1,5 @@
 ---
-title: "oCIS"
+title: "oCIS - ownCloud Infinite Scale"
 date: 2020-02-27T20:35:00+01:00
 weight: -10
 geekdocRepo: https://github.com/owncloud/ocis
@@ -11,32 +11,23 @@ geekdocFilePath: _index.md
 
 ## ownCloud Infinite Scale
 
-Welcome to oCIS! We develop a modern file-sync and share plattform, based on our knowledge and experience with the PHP ownCloud server project.
+Welcome to oCIS, the modern file-sync and share platform, which is based on our knowledge and experience with the PHP based [ownCloud server](https://owncloud.com/#server).
 
-### oCIS Server
+### oCIS server
 
-The oCIS server implementation follows go-lang best practices and is based on the [go-micro](https://go-micro.dev/) framework and [REVA](https://reva.link/). We love and stick to [12 Factor](https://12factor.net/). 
+The oCIS server implementation follows [Go](https://golang.org/) best practices and is based on the [go-micro](https://go-micro.dev/) framework and [REVA](https://reva.link/). We love and stick to [12 Factor](https://12factor.net/).
 oCIS is a micro-service based server, which allows scale-out of individual services to meet your specific performance requirements.
-We run a huge test suite, which was originated in ownCloud 10 and continues to grow.
+We run a huge [test suite](https://github.com/owncloud/core/tree/master/tests), which was originated in ownCloud 10 and continues to grow.
 
 ### Architecture Overview
 
 {{< mermaid class="text-center">}}
 graph TD
-ocis-proxy -->
-    ocis-konnectd & ocis-phoenix & ocis-thumbnails & ocis-ocs & ocis-webdav
+proxy -->
+    konnectd & ocis-phoenix & thumbnails & ocs & webdav & storage & accounts & store & settings
 
-ocis-phoenix --> ocis-reva-fronted
-ocis-reva-fronted --> ocis-reva-gateway
-ocis-konnectd --> ocis-glauth
+konnectd --> glauth
 
+storage --> REVA
 
-ocis-reva-gateway --> ocis-reva-users
-ocis-reva-gateway --> ocis-reva-authbasic
-ocis-reva-gateway --> ocis-reva-auth-bearer
-
-ocis-reva-gateway --> ocis-reva-sharing
-ocis-reva-gateway --> ocis-reva-storage-home-*
-ocis-reva-storage-home-* --> ocis-reva-storage-home-*-data
-ocis-reva-sharing --> redis
 {{< /mermaid >}}
diff --git a/docs/ocis/deployment/_index.md b/docs/ocis/deployment/_index.md
@@ -9,16 +9,15 @@ geekdocFilePath: _index.md
 
 {{< toc >}}
 
-## Deployments Scenarios and Examples
-This section handles deployments and operations for admins. If you are looking for a development setup, start with
+## Deployments scenarios and examples
+This section handles deployments and operations for admins. If you are looking for a development setup, start with [Getting started](https://owncloud.github.io/ocis/getting-started/).
 
-### Setup oCIS
-oCIS deployments are super simple, yet there are many configrations possible for advanced setups.
+### Setup oCIS on your server
+oCIS deployments are super simple, yet there are many configurations possible for advanced setups.
 
-- Basic setup - download and run
-- Pick services and manage them individually
-- SSL offloading with Traefik
-- Use an external IDP
+- [Basic oCIS setup]({{< ref "basic-remote-setup.md" >}}) - configure domain, certificates and port
+- [oCIS setup with Traefik for ssl termination]({{< ref "ocis_traefik.md" >}})
+- [oCIS setup with external OIDC IDP]({{< ref "ocis_external_idp.md" >}})
 
 ### Migrate an existing ownCloud 10
 You can run ownCloud 10 and oCIS together. This allows you to use new parts of oCIS already with ownCloud 10 and also to have a smooth transition for users from ownCloud 10 to oCIS.

diff --git a/docs/ocis/deployment/bridge.md b/docs/ocis/deployment/bridge.md
@@ -1,6 +1,6 @@
 ---
 title: "Bridge"
-date: 2020-02-27T20:35:00+01:00
+date: 2022-02-27T20:35:00+01:00
 weight: 30
 geekdocRepo: https://github.com/owncloud/ocis
 geekdocEditPath: edit/master/docs/ocis/deployment

diff --git a/...ocis/deployment/ocis_external_konnectd.md → docs/ocis/deployment/ocis_external_idp.md b/...ocis/deployment/ocis_external_konnectd.md → docs/ocis/deployment/ocis_external_idp.md
@@ -1,59 +1,36 @@
 ---
-title: "ocis with konnectd on external node deployment scenario"
+title: "oCIS with external IDP"
 date: 2020-10-12T14:39:00+01:00
 weight: 26
 geekdocRepo: https://github.com/owncloud/ocis
 geekdocEditPath: edit/master/docs/ocis/deployment
-geekdocFilePath: ocis_external_konnectd.md
+geekdocFilePath: ocis_external_idp.md
 ---
 
 {{< toc >}}
 
-This scenario shows how to setup ocis with konnectd as idp running on a separate node. Both node are having separate domains pointing on the servers.
+This scenario shows how to setup oCIS and konnectd as external IDP (identity provider). Both have separate domains and will be configured to work together.
 
 ## Overview
 
-* ocis and konnectd running on linux nodes behind traefik as reverse proxy
-* Cloudflare DNS is resolving the domains
-* Letsencrypt provides ssl certificates for the domains
-* Traefik docker container terminates ssl and forwards http requests to the services
+* Server 1: oCIS running behind traefik as reverse proxy
+* Server 2: IDP running behind traefik as reverse proxy
+* Valid ssl certificates for the domains for ssl termination
 
-## Nodes
+[Find this example on GitHub](https://github.com/owncloud/ocis/tree/master/deployments/examples/ocis_external_konnectd)
 
-### Requirements
-
-* Server running Ubuntu 20.04 is public availible with a static ip address
-* Two A-records for both domains are pointing on the servers ip address
-* Create user
-
-  `$ sudo adduser username`
-
-* Add user to sudo group
-
-  `$ sudo usermod -aG sudo username`
-
-* Add users pub key to `~/.ssh/authorized_keys`
-* Setup ssh to permit authorisation only by ssh key
-* Install docker
-
-  `$ sudo apt install docker.io`
 
-* Add user to docker group
 
-  `$ sudo usermod -aG docker username`
+## Server Deployment
 
-* Install docker-compose via
-
-  `$ sudo curl -L "https://github.com/docker/compose/releases/download/1.27.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose`
-
-  (docker compose version 1.27.4 as of today)
-* Make docker-compose executable
+### Requirements
 
-  `$ sudo chmod +x /usr/local/bin/docker-compose`
+* 2 Linux servers, each with docker and docker-compose installed
+* Two domains set up and pointing to the target server
 
-* Environment variables for OCIS Stack are provided by .env file
+See also [example server setup]({{< ref "preparing_server.md" >}})
 
-### Setup on ocis server
+### Install oCIS server
 
 * Clone ocis repository
 
@@ -77,7 +54,7 @@ This scenario shows how to setup ocis with konnectd as idp running on a separate
 
   `docker-compose up -d`
 
-### Setup on idp server
+### Install IDP server
 
 * Clone ocis repository
 
@@ -105,11 +82,7 @@ This scenario shows how to setup ocis with konnectd as idp running on a separate
 
   `docker-compose up -d`
 
-### Stack
-
-On both nodes, a traefik dokcer container is terminating ssl and forwards the http requests to the services. The nodes are named according to their services.
-
-### Config
+### Configuration
 
 #### Repository structure
 
@@ -192,3 +165,8 @@ ocis:
       - 9125:9125
 ...
 ```
+
+## Local setup
+For simple local ocis setup see [Getting started]({{< ref "../getting-started.md" >}})
+
+Local setup coming soon