diff --git a/docs/_index.md b/docs/_index.md index 5793457423..8a514d878e 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -22,7 +22,7 @@ Welcome to our developer documentation. Here you can find developer documentatio The oCIS server is Apache v2 licensed. The lower storage layer of oCIS is defined by the CS3 APIs and implemented in the REVA project. Our goal is to develop the CS3 APIs to an open standard and collaborate on the open source REVA reference implementation for CS3 APIs. -You can also find all client sources on GitHub. +You can also find all client sources on [GitHub](https://github.com/owncloud/). ## Join us diff --git a/docs/extensions/storage/users.md b/docs/extensions/storage/users.md index 6284b913ae..a34a4ea291 100644 --- a/docs/extensions/storage/users.md +++ b/docs/extensions/storage/users.md @@ -12,7 +12,7 @@ geekdocFilePath: users.md This is a simple user driver for testing. It contains three users: ``` einstein:relativity -marie:radioactivty +marie:radioactivity richard:superfluidity ``` In order to use the `demo` driver you need to export the relevant environment variable: diff --git a/docs/ocis/_index.md b/docs/ocis/_index.md index 8173cf19b5..7770113ae9 100644 --- a/docs/ocis/_index.md +++ b/docs/ocis/_index.md @@ -15,26 +15,26 @@ Welcome to oCIS, the modern file-sync and share platform, which is based on our ### oCIS microservice runtime -The oCIS runtime allows us to dynamically manage services running in a single process. We use [suture](https://github.com/thejerf/suture) to create a supervisor tree that starts each service in a dedicated goroutine. Be default oCIS will start all built in oCIS extensions in a single process. Individual services can be moved to other nodes to scale-out and meet specific performance requirements. A [go-micro](https://github.com/asim/go-micro/blob/master/registry/registry.go) based registry allows services in multiple nodes to form a distributed microservice architecture. +The oCIS runtime allows us to dynamically manage services running in a single process. We use [suture](https://github.com/thejerf/suture) to create a supervisor tree that starts each service in a dedicated goroutine. By default oCIS will start all built-in oCIS extensions in a single process. Individual services can be moved to other nodes to scale-out and meet specific performance requirements. A [go-micro](https://github.com/asim/go-micro/blob/master/registry/registry.go) based registry allows services in multiple nodes to form a distributed microservice architecture. ### oCIS extensions Every oCIS extension uses [ocis-pkg](https://github.com/owncloud/ocis/ocis-pkg), which implements the [go-micro](https://go-micro.dev/) interfaces for [servers](https://github.com/asim/go-micro/blob/v3.5.0/server/server.go#L17-L37) to register and [clients](https://github.com/asim/go-micro/blob/v3.5.0/client/client.go#L11-L23) to lookup nodes with a service [registry](https://github.com/asim/go-micro/blob/v3.5.0/registry/registry.go). -We are following the [12 Factor](https://12factor.net/)methodology with oCIS. The uniformity of services also allows us to use the same command, logging and configuration mechanism. Configurations are forwarded from the +We are following the [12 Factor](https://12factor.net/) methodology with oCIS. The uniformity of services also allows us to use the same command, logging and configuration mechanism. Configurations are forwarded from the oCIS runtime to the individual extensions. ### go-micro -While the [go-micro](https://go-micro.dev/) framework provides abstractions as well as implementations for the different components in a microservice architecture it uses a more developer focused runtime philosophy: it is used to download a services from a repo, compile them on the fly and start them as individual processes. For oCIS we decided to use a more admin friendly runtime: you can download a single binary and start the contained oCIS extensions with a single `bin/ocis server`. This also makes packaging easier. +While the [go-micro](https://go-micro.dev/) framework provides abstractions as well as implementations for the different components in a microservice architecture, it uses a more developer focused runtime philosophy: It is used to download services from a repo, compile them on the fly and start them as individual processes. For oCIS we decided to use a more admin friendly runtime: You can download a single binary and start the contained oCIS extensions with a single `bin/ocis server`. This also makes packaging easier. -We use[ocis-pkg](https://github.com/owncloud/ocis/ocis-pkg) to configure the default implementations for the go-micro [grpc server](https://github.com/asim/go-micro/tree/v3.5.0/plugins/server/grpc), [client](https://github.com/asim/go-micro/tree/v3.5.0/plugins/client/grpc) and [mdns registry](https://github.com/asim/go-micro/blob/v3.5.0/registry/mdns_registry.go), swapping them out as needed, eg. to use the [kubernetes registry plugin](https://github.com/asim/go-micro/tree/v3.5.0/plugins/registry/kubernetes). +We use [ocis-pkg](https://github.com/owncloud/ocis/ocis-pkg) to configure the default implementations for the go-micro [grpc server](https://github.com/asim/go-micro/tree/v3.5.0/plugins/server/grpc), [client](https://github.com/asim/go-micro/tree/v3.5.0/plugins/client/grpc) and [mdns registry](https://github.com/asim/go-micro/blob/v3.5.0/registry/mdns_registry.go), swapping them out as needed, eg. to use the [kubernetes registry plugin](https://github.com/asim/go-micro/tree/v3.5.0/plugins/registry/kubernetes). ### REVA A lot of embedded services in oCIS are built upon the [REVA](https://reva.link/) runtime. We decided to bundle some of the [CS3 services](https://github.com/cs3org/cs3apis) to logically group them. A [home storage provider](https://github.com/owncloud/ocis/blob/v1.2.0/storage/pkg/command/storagehome.go#L93-L108), which is dealing with [metadata](https://cs3org.github.io/cs3apis/#cs3.storage.provider.v1beta1.ProviderAPI), and the corresponding [data provider](https://github.com/owncloud/ocis/blob/v1.2.0/storage/pkg/command/storagehome.go#L109-L123), which is dealing with [up and download](https://cs3org.github.io/cs3apis/#cs3.gateway.v1beta1.FileUploadProtocol), are one example. The [frontend](https://github.com/owncloud/ocis/blob/v1.2.0/storage/pkg/command/frontend.go) with the [oc flavoured webdav](https://github.com/owncloud/ocis/blob/v1.2.0/storage/pkg/command/frontend.go#L132-L138), [ocs handlers](https://github.com/owncloud/ocis/blob/v1.2.0/storage/pkg/command/frontend.go#L139-L148) and a [datagateway](https://github.com/owncloud/ocis/blob/v1.2.0/storage/pkg/command/frontend.go#L126-L131) are another. ### Protocol driven development -Interacting with oCIS involves a multitude af APIs. The server and all clients rely on [OpenID Connect](https://openid.net/connect/) for authentication. The [embedded konnectd](https://github.com/owncloud/ocis/tree/master/idp) can be replaced with any other OpenID Connect Identity Provider. Clients use the [WebDAV](http://webdav.org/) based [oc sync protocol](https://github.com/cernbox/smashbox/blob/master/protocol/protocol.md) to manage files and folders, [ocs to manage shares](https://doc.owncloud.com/server/developer_manual/core/apis/ocs-share-api.html) and [TUS](https://tus.io/protocols/resumable-upload.html) to upload files in a resumable way. On the server side [REVA](https://reva.link/) is the reference implementation of the [CS3 apis](https://github.com/cs3org/cs3apis) which is defined using [protobuf](https://developers.google.com/protocol-buffers/). By embedding [glauth](https://github.com/glauth/glauth/), oCIS provides a read only [LDAP](https://tools.ietf.org/html/rfc2849) interface to make accounts, including guests available to firewalls and other systems. In the future, we are looking into [the Microsoft Graph API](https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0), which is based on [odata](http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html) as a well defined REST/JSON dialect for the existing endpoints. +Interacting with oCIS involves a multitude af APIs. The server and all clients rely on [OpenID Connect](https://openid.net/connect/) for authentication. The [embedded konnectd](https://github.com/owncloud/ocis/tree/master/idp) can be replaced with any other OpenID Connect Identity Provider. Clients use the [WebDAV](http://webdav.org/) based [oc sync protocol](https://github.com/cernbox/smashbox/blob/master/protocol/protocol.md) to manage files and folders, [ocs to manage shares](https://doc.owncloud.com/server/developer_manual/core/apis/ocs-share-api.html) and [TUS](https://tus.io/protocols/resumable-upload.html) to upload files in a resumable way. On the server side [REVA](https://reva.link/) is the reference implementation of the [CS3 apis](https://github.com/cs3org/cs3apis) which is defined using [protobuf](https://developers.google.com/protocol-buffers/). By embedding [glauth](https://github.com/glauth/glauth/), oCIS provides a read-only [LDAP](https://tools.ietf.org/html/rfc2849) interface to make accounts, including guests available to firewalls and other systems. In the future, we are looking into [the Microsoft Graph API](https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0), which is based on [odata](http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html), as a well defined REST/JSON dialect for the existing endpoints. ### Acceptance test suite We run a huge [test suite](https://github.com/owncloud/core/tree/master/tests), which originated in ownCloud 10 and continues to grow. A detailed description can be found in the developer docs for [testing]({{< relref "development/testing.md" >}}). diff --git a/docs/ocis/development/extensions.md b/docs/ocis/development/extensions.md index e0c52fc48c..bb03be4977 100644 --- a/docs/ocis/development/extensions.md +++ b/docs/ocis/development/extensions.md @@ -11,7 +11,7 @@ geekdocFilePath: extensions.md ## How to build and run ocis-simple -ocis uses build tags to build different flavors of the binary. In order to work on a new extension we are going to reduce the scope a little and use the `simple` tag. Let us begin by creating a dedicated folder: +oCIS uses build tags to build different flavors of the binary. In order to work on a new extension we are going to reduce the scope a little and use the `simple` tag. Let us begin by creating a dedicated folder: ```console mkdir ocis-extension-workshop && ocis-extension-workshop @@ -76,7 +76,7 @@ ps ax | grep ocis Try to kill `ocis hello` -Remember: for now, killing a service will cause ocis to restart it. This is subject to change. +Remember: For now, killing a service will cause ocis to restart it. This is subject to change. In order to be able to manage the processes ourselves we need to start them independently: diff --git a/docs/ocis/development/getting-started.md b/docs/ocis/development/getting-started.md index aeb0576ffa..8f0afcbb41 100644 --- a/docs/ocis/development/getting-started.md +++ b/docs/ocis/development/getting-started.md @@ -25,9 +25,9 @@ If you find tools needed besides the mentioned above, please feel free to open a ## Repository structure -oCIS consists of multiple micro services, also called extensions. We started by having standalone repositories for each of them but quickly noticed, that this adds a time consuming overhead for developers. So we ended up with a monorepo housing all the extensions in one repository. +oCIS consists of multiple micro services, also called extensions. We started by having standalone repositories for each of them, but quickly noticed that this adds a time consuming overhead for developers. So we ended up with a monorepo housing all the extensions in one repository. -Each extension lives in a subfolder (eg. `accounts` or `settings`) in this respository as an independent Go module, following the [golang-standard project-layout](https://github.com/golang-standards/project-layout). They have common Makefile targets and can be used to change, build and run individual extensions. +Each extension lives in a subfolder (eg. `accounts` or `settings`) within this respository as an independent Go module, following the [golang-standard project-layout](https://github.com/golang-standards/project-layout). They have common Makefile targets and can be used to change, build and run individual extensions. The `ocis` folder contains our [go-micro](https://github.com/asim/go-micro/) and [suture](https://github.com/thejerf/suture) based runtime. It is used to import all extensions and implements commands to manage them, similar to a small orchestrator. With the resulting oCIS binary you can start single extensions or even all extensions at the same time. diff --git a/docs/ocis/flow-docs/login-flow.md b/docs/ocis/flow-docs/login-flow.md index 9a3babd3f7..48b11dc08b 100644 --- a/docs/ocis/flow-docs/login-flow.md +++ b/docs/ocis/flow-docs/login-flow.md @@ -10,7 +10,7 @@ geekdocFilePath: login-flow.md ## Login Flow -The following sequence diagram describes the [openid connect auth code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). The eight numbered steps and notes correspond to the [openid connect auth code flow steps](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowSteps). Example requests are based on the spec as well.: +The following sequence diagram describes the [openid connect auth code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). The eight numbered steps and notes correspond to the [openid connect auth code flow steps](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowSteps). Example requests are based on the spec as well: {{< mermaid class="text-center">}} sequenceDiagram diff --git a/docs/ocis/getting-started.md b/docs/ocis/getting-started.md index 60f8f4dae5..b4610bcb33 100644 --- a/docs/ocis/getting-started.md +++ b/docs/ocis/getting-started.md @@ -13,10 +13,10 @@ geekdocFilePath: getting-started.md We are distributing oCIS as binaries and Docker images. -You can find more deployments examples in the [deployment section](https://owncloud.github.io/ocis/deployment/) +You can find more deployment examples in the [deployment section](https://owncloud.github.io/ocis/deployment/). ### Binaries -You can find the latest official release of ocis at [our download mirror](https://download.owncloud.com/ocis/ocis/) or on [GitHub](https://github.com/owncloud/ocis/releases). +You can find the latest official release of oCIS at [our download mirror](https://download.owncloud.com/ocis/ocis/) or on [GitHub](https://github.com/owncloud/ocis/releases). The latest build from the master branch can be found at [our download mirrors testing section](https://download.owncloud.com/ocis/ocis/testing/). To run oCIS as binary you need to download it first and then run the following commands. diff --git a/docs/ocis/metrics.md b/docs/ocis/metrics.md index 6923e951d6..34157df3d3 100644 --- a/docs/ocis/metrics.md +++ b/docs/ocis/metrics.md @@ -10,7 +10,7 @@ geekdocFilePath: metrics.md ## Metrics -This service provides some [Prometheus](https://prometheus.io/) metrics through the debug endpoint, you can optionally secure the metrics endpoint by some random token, which got to be configured through one of the flag `--debug-token` or the environment variable `OCIS_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:8001/metrics`. +This service provides some [Prometheus](https://prometheus.io/) metrics through the debug endpoint, you can optionally secure the metrics endpoint by some random token, which has to be configured either through the flag `--debug-token` or the environment variable `OCIS_DEBUG_TOKEN` mentioned above. By default, the metrics endpoint is bound to `http://0.0.0.0:8001/metrics`. go_gc_duration_seconds : A summary of the GC invocation durations diff --git a/docs/ocis/release_roadmap.md b/docs/ocis/release_roadmap.md index 6917db00d3..ab8a234cd5 100644 --- a/docs/ocis/release_roadmap.md +++ b/docs/ocis/release_roadmap.md @@ -7,15 +7,15 @@ geekdocEditPath: edit/master/docs/ocis geekdocFilePath: release_roadmap.md --- -You may have asked yourself why there are major version 1 tags in our GitHub repository but the readme still states `ownCloud Infinite Scale is currently in a technical preview state. It will be subject to a lot of changes and is not yet ready for general production deployments.`. How can that be if its a major version 1? +You may have asked yourself why there are major version 1 tags in our GitHub repository but the Readme still states `ownCloud Infinite Scale is currently in a technical preview state. It will be subject to a lot of changes and is not yet ready for general production deployments.`. How can that be if its a major version 1? Our initial and also our current plan is to stick to SemVer as versioning scheme. But sometimes there are other factors which cross your plans. Therefore we started releasing oCIS with version `1.0.0 Tech Preview`. ## ownCloud Infinite Scale 1.x technology preview releases -All oCIS releases within major version 1 will be handled as technology previews. There will be no supported releases in terms of us guaranteeing production readiness. We will do releases every 3 weeks. They will sometimes only include bugfixes but also new features or optimizations. +All oCIS releases within major version 1 will be handled as technology previews. There will be no supported releases in terms of us guaranteeing production readiness. We will do releases every 3 weeks, and they will sometimes only include bugfixes, but also introduce new features or optimizations. -We will be fixing bugs if you report them and truly appreciate every report and contribution. We will then do bugfix releases or add the fix to the next minor release. +We will be fixing bugs if you report them and truly appreciate every report and contribution. Depending on the individual case, we will publish bugfix releases or add the fix to the next minor release. We are going to stick to major version 1 until we feel confident about running oCIS in production environments. As a consequence of this we cannot raise the major version, like SemVer requires it, even if we need to introduce breaking changes. We will do our best to avoid breaking changes. If there is no way to circumvent this, we will add an automatic migration or at least point out manual migration steps, since we as oCIS developers are already using oCIS on a personal basis. The best place to see if a breaking change happens is our changelog which is available for every release. If things are not working out for you please contact us immediately. We want to know about this and solve it for you. diff --git a/docs/ocis/storage-backends/eos.md b/docs/ocis/storage-backends/eos.md index 8801b44ae5..1bc6e991f8 100644 --- a/docs/ocis/storage-backends/eos.md +++ b/docs/ocis/storage-backends/eos.md @@ -9,7 +9,7 @@ geekdocFilePath: eos.md {{< toc >}} -oCIS can be configured to run on top of [eos](https://eos.web.cern.ch/). While the [eos documentation](http://eos-docs.web.cern.ch/) does cover a lot of topics it leaves out some details that you may have to either pull from various [docker containers](https://gitlab.cern.ch/eos/eos-docker), the [forums](https://eos-community.web.cern.ch/) or even the [source](https://github.com/cern-eos/eos) itself. +oCIS can be configured to run on top of [eos](https://eos.web.cern.ch/). While the [eos documentation](http://eos-docs.web.cern.ch/) does cover a lot of topics, it leaves out some details that you may have to either pull from various [docker containers](https://gitlab.cern.ch/eos/eos-docker), the [forums](https://eos-community.web.cern.ch/) or even the [source](https://github.com/cern-eos/eos) itself. This document is a work in progress of the current setup.