From 34845f94147ff7afd585d64a6f14c0b7b0abce98 Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Tue, 24 Nov 2020 08:46:04 +0100 Subject: [PATCH] work on docs --- .drone.star | 17 +- Dockerfile | 4 +- README.md | 89 +---- accounts/templates/CONFIGURATION.tmpl | 4 - docs/.gitignore | 1 + docs/Makefile | 27 +- docs/README.md | 3 + docs/_index.md | 2 + docs/extensions/accounts/_index.md | 2 +- docs/extensions/accounts/getting-started.md | 22 -- docs/extensions/glauth/_index.md | 2 +- docs/extensions/glauth/configuration-hints.md | 16 + docs/extensions/glauth/getting-started.md | 14 - docs/extensions/konnectd/_index.md | 1 + docs/extensions/konnectd/getting-started.md | 161 --------- docs/extensions/ocis-phoenix/_index.md | 2 +- .../ocis-phoenix/getting-started.md | 339 ------------------ docs/extensions/ocs/_index.md | 2 +- docs/extensions/ocs/getting-started.md | 161 --------- docs/extensions/proxy/_index.md | 3 +- docs/extensions/proxy/about.md | 10 - docs/extensions/proxy/getting-started.md | 53 --- docs/extensions/settings/_index.md | 4 +- docs/extensions/settings/getting-started.md | 279 -------------- docs/extensions/settings/values.md | 2 +- docs/extensions/storage/_index.md | 4 +- docs/extensions/store/_index.md | 2 +- docs/extensions/store/getting-started.md | 279 -------------- docs/extensions/thumbnails/_index.md | 2 +- docs/extensions/thumbnails/getting-started.md | 297 --------------- docs/extensions/thumbnails/releasing.md | 45 --- docs/extensions/webdav/_index.md | 2 +- docs/extensions/webdav/getting-started.md | 276 -------------- docs/ocis/deployment/_index.md | 4 +- docs/ocis/deployment/bridge.md | 2 +- docs/ocis/development/_index.md | 4 +- docs/ocis/development/build-docs.md | 20 ++ docs/ocis/development/build.md | 48 +++ docs/ocis/development/building-docs.md | 40 --- docs/ocis/development/building.md | 46 --- .../development/continuous-integration.md | 56 +++ docs/ocis/development/debugging.md | 27 +- docs/ocis/{ => development}/extensions.md | 10 +- docs/ocis/development/getting-started.md | 89 ++--- docs/ocis/development/testing.md | 7 +- docs/ocis/development/tracing.md | 62 ++-- docs/ocis/flow-docs/_index.md | 8 + docs/ocis/{ => flow-docs}/login-flow.md | 2 +- .../{ => flow-docs}/public-upload-flow.md | 2 +- docs/ocis/{ => flow-docs}/request-flow.md | 2 +- docs/ocis/getting-started.md | 12 +- docs/ocis/storage-backends/_index.md | 8 + docs/ocis/{ => storage-backends}/eos.md | 0 glauth/templates/CONFIGURATION.tmpl | 4 - konnectd/templates/CONFIGURATION.tmpl | 4 - ocis-phoenix/templates/CONFIGURATION.tmpl | 4 - ocis/docker/eos-ocis-dev/README.md | 4 + ocis/templates/CONFIGURATION.tmpl | 4 +- ocs/templates/CONFIGURATION.tmpl | 4 - proxy/templates/CONFIGURATION.tmpl | 4 - settings/templates/CONFIGURATION.tmpl | 4 - storage/templates/CONFIGURATION.tmpl | 4 - store/templates/CONFIGURATION.tmpl | 4 - thumbnails/templates/CONFIGURATION.tmpl | 4 - webdav/templates/CONFIGURATION.tmpl | 4 - 65 files changed, 326 insertions(+), 2298 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/README.md delete mode 100644 docs/extensions/accounts/getting-started.md create mode 100644 docs/extensions/glauth/configuration-hints.md delete mode 100644 docs/extensions/glauth/getting-started.md delete mode 100644 docs/extensions/konnectd/getting-started.md delete mode 100644 docs/extensions/ocis-phoenix/getting-started.md delete mode 100644 docs/extensions/ocs/getting-started.md delete mode 100644 docs/extensions/proxy/about.md delete mode 100644 docs/extensions/proxy/getting-started.md delete mode 100644 docs/extensions/settings/getting-started.md delete mode 100644 docs/extensions/store/getting-started.md delete mode 100644 docs/extensions/thumbnails/getting-started.md delete mode 100644 docs/extensions/thumbnails/releasing.md delete mode 100644 docs/extensions/webdav/getting-started.md create mode 100644 docs/ocis/development/build-docs.md create mode 100644 docs/ocis/development/build.md delete mode 100644 docs/ocis/development/building-docs.md delete mode 100644 docs/ocis/development/building.md create mode 100644 docs/ocis/development/continuous-integration.md rename docs/ocis/{ => development}/extensions.md (92%) create mode 100644 docs/ocis/flow-docs/_index.md rename docs/ocis/{ => flow-docs}/login-flow.md (99%) rename docs/ocis/{ => flow-docs}/public-upload-flow.md (85%) rename docs/ocis/{ => flow-docs}/request-flow.md (98%) create mode 100644 docs/ocis/storage-backends/_index.md rename docs/ocis/{ => storage-backends}/eos.md (100%) diff --git a/.drone.star b/.drone.star index 72445ec71..9452f3943 100644 --- a/.drone.star +++ b/.drone.star @@ -3,12 +3,13 @@ config = { 'accounts': 'frontend', 'glauth':'', 'konnectd':'', + 'ocis': '', 'ocis-phoenix':'', 'ocis-pkg':'', - 'storage':'', 'ocs':'', 'proxy':'', 'settings':'frontend', + 'storage':'', 'store':'', 'thumbnails':'', 'webdav':'', @@ -1255,13 +1256,6 @@ def docs(ctx): 'arch': 'amd64', }, 'steps': [ - { - 'name': 'prepare', - 'image': 'owncloudci/alpine:latest', - 'commands': [ - 'make -C docs docs-copy' - ], - }, { 'name': 'generate-config-docs', 'image': 'webhippie/golang:1.14', @@ -1273,6 +1267,13 @@ def docs(ctx): }, ], }, + { + 'name': 'prepare', + 'image': 'owncloudci/alpine:latest', + 'commands': [ + 'make -C docs docs-copy' + ], + }, { 'name': 'test', 'image': 'owncloudci/hugo:0.71.0', diff --git a/Dockerfile b/Dockerfile index 0c3f5d9c3..53052e8bb 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,7 +13,7 @@ WORKDIR /ocis/ocis RUN make clean generate build -FROM amd64/alpine:3 +FROM alpine:3 RUN apk update && \ apk upgrade && \ @@ -29,4 +29,4 @@ LABEL maintainer="ownCloud GmbH " \ ENTRYPOINT ["/usr/bin/ocis"] CMD ["server"] -COPY --from=build /ocis/ocis/bin/ocis /usr/bin/ocis \ No newline at end of file +COPY --from=build /ocis/ocis/bin/ocis /usr/bin/ocis diff --git a/README.md b/README.md index 160bfb7da..be4b8252b 100644 --- a/README.md +++ b/README.md @@ -5,97 +5,20 @@ [![Codacy Badge](https://app.codacy.com/project/badge/Grade/dc97ddfa167641d8b107e9b618823c71)](https://www.codacy.com/gh/owncloud/ocis/dashboard?utm_source=github.com&utm_medium=referral&utm_content=owncloud/ocis&utm_campaign=Badge_Grade) [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/dc97ddfa167641d8b107e9b618823c71)](https://www.codacy.com/gh/owncloud/ocis/dashboard?utm_source=github.com&utm_medium=referral&utm_content=owncloud/ocis&utm_campaign=Badge_Coverage) [![Go Doc](https://godoc.org/github.com/owncloud/ocis?status.svg)](http://godoc.org/github.com/owncloud/ocis) -[![Go Report](http://goreportcard.com/badge/github.com/owncloud/ocis)](http://goreportcard.com/report/github.com/owncloud/ocis) -[![](https://images.microbadger.com/badges/image/owncloud/ocis.svg)](http://microbadger.com/images/owncloud/ocis "Get your own image badge on microbadger.com") +[![Go Report](https://goreportcard.com/badge/github.com/owncloud/ocis)](https://goreportcard.com/report/github.com/owncloud/ocis) +[![](https://images.microbadger.com/badges/image/owncloud/ocis.svg)](https://hub.docker.com/r/owncloud/ocis "oCIS docker image") -**This project is under heavy development, it's not in a working state yet!** +## Run ownCloud Infinite Scale -## Install - -You can download prebuilt binaries from the GitHub releases or from our [download mirrors](http://download.owncloud.com/ocis/ocis/). For instructions how to install this on your platform you should take a look at our [documentation](https://owncloud.github.io/ocis/) +Please see [Getting Started](https://owncloud.github.io/ocis/getting-started/) ## Development -Make sure you have a working Go environment, for further reference or a guide take a look at the [install instructions](http://golang.org/doc/install.html). This project requires Go >= v1.13. - -```console -git clone https://github.com/owncloud/ocis.git -cd ocis/ocis - -make generate build - -./bin/ocis -h -``` - -### Folder Structure - -This is a monorepo for multiple microservices. The individual services are located in subfolders like `accounts`. The code in the `ocis` subfolder aggregates all the go modules and implements commands to start the individual services or the full-stack server with a default config. It also builds a single binary and docker images. - -## Prerequisites - -### Redis server - -You will need to start a redis server as a cache. The ownCloud storage driver currently will try to connect to the default port. -A quick way to start one for testing is using this docker instance: `docker run -e REDIS_DATABASES=1 -p 6379:6379 -d webhippie/redis:latest` - -### Root storage - -To prepare the root storage you should fill it with two folders. They are necessary for resolving the home and ownCloud storages. This is subject to change. - -```console -mkdir -p /var/tmp/reva/root/{home,oc} -``` - -## Quickstart - -- Make sure that the binary was built with the above steps. -- Now start all services with the following command - -```console -./bin/ocis server -``` - -- Open -- Accept the self-signed certificate (it is regenerated every time the server starts) -- Login using one of the demo accounts: - -```console -einstein:relativity -marie:radioactivity -richard:superfluidity -``` - -## Create a local Docker image for testing - -Navigate into the root folder of the repository and execute - -```console -docker build -t owncloud/ocis:dev . -``` - -To run it, execute - -```console -docker run --rm -ti owncloud/ocis:dev -``` - -The image can be tagged however you like, just make sure you run the right one then - -## Running single extensions - -The list of available extensions can be found in the "Extensions" section when running `./bin/ocis`. - -For example to run the "phoenix" extension: - -```console -./bin/ocis --log-level debug phoenix -``` - -⚠ do not use the **run** subcommand for running extensions +Please see [Development - Getting Started](https://owncloud.github.io/ocis/development/getting-started/) ## Security -If you find a security issue please contact [security@owncloud.com](mailto:security@owncloud.com) first. +If you find a security issue please contact [security@owncloud.com](mailto:security@owncloud.com) first ## Contributing diff --git a/accounts/templates/CONFIGURATION.tmpl b/accounts/templates/CONFIGURATION.tmpl index c5d669edd..66aa779c5 100644 --- a/accounts/templates/CONFIGURATION.tmpl +++ b/accounts/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/ocis_accounts/configuration) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..1bffed552 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +hugo/ \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index 6475bef92..97ccde5e1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,11 +1,34 @@ +config-docs-generate: + make -C ../accounts config-docs-generate + make -C ../glauth config-docs-generate + make -C ../konnectd config-docs-generate + make -C ../ocis config-docs-generate + make -C ../ocis-phoenix config-docs-generate + make -C ../ocis-pkg config-docs-generate + make -C ../ocs config-docs-generate + make -C ../proxy config-docs-generate + make -C ../settings config-docs-generate + make -C ../storage config-docs-generate + make -C ../store config-docs-generate + make -C ../thumbnails config-docs-generate + make -C ../webdav config-docs-generate .PHONY: docs-copy docs-copy: - mkdir -p hugo/content/; \ + mkdir -p hugo/content/ cd hugo; \ git init; \ + git config advice.detachedHead false; \ git remote rm origin; \ git remote add origin https://github.com/owncloud/owncloud.github.io; \ git fetch --depth=1; \ git checkout origin/source -f; \ - rsync -ax --delete --exclude hugo/ --exclude Makefile ../. content/; \ + rsync -ax --delete --exclude hugo/ --exclude Makefile --exclude README.md ../. content/; \ + +.PHONY: docs-serve +docs-serve: config-docs-generate docs-copy + docker run --rm --network host -v $(shell pwd)/hugo:/src owncloudci/hugo:0 server + +.PHONY: clean +clean: + rm -rf hugo diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..e9fc98a96 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# documentation + +To contribute to documentation please see also: [Documentation](http://owncloud.github.io/ocis/development/build-docs/) diff --git a/docs/_index.md b/docs/_index.md index be9104e36..4819168e0 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -2,6 +2,8 @@ title: ownCloud --- +{{< toc >}} + ## Developer Documentation Welcome to our developer documentation. Here you can find developer documentation on: diff --git a/docs/extensions/accounts/_index.md b/docs/extensions/accounts/_index.md index c701c32ea..afa91e8f8 100644 --- a/docs/extensions/accounts/_index.md +++ b/docs/extensions/accounts/_index.md @@ -1,7 +1,7 @@ --- title: Accounts date: 2018-05-02T00:00:00+00:00 -weight: 10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/accounts geekdocFilePath: _index.md diff --git a/docs/extensions/accounts/getting-started.md b/docs/extensions/accounts/getting-started.md deleted file mode 100644 index fa2f567ba..000000000 --- a/docs/extensions/accounts/getting-started.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 20 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/accounts -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -## Installation - -So far we are offering two different variants for the installation. You can choose between [Docker](https://www.docker.com/) or pre-built binaries which are stored on our download mirrors and GitHub releases. Maybe we will also provide system packages for the major distributions later if we see the need for it. - -### Docker - -TBD - -### Binaries - -TBD diff --git a/docs/extensions/glauth/_index.md b/docs/extensions/glauth/_index.md index 8bb4d00d3..63f6298f1 100644 --- a/docs/extensions/glauth/_index.md +++ b/docs/extensions/glauth/_index.md @@ -1,7 +1,7 @@ --- title: "GLAuth" date: 2018-05-02T00:00:00+00:00 -weight: 10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/glauth geekdocFilePath: _index.md diff --git a/docs/extensions/glauth/configuration-hints.md b/docs/extensions/glauth/configuration-hints.md new file mode 100644 index 000000000..9ca953295 --- /dev/null +++ b/docs/extensions/glauth/configuration-hints.md @@ -0,0 +1,16 @@ +--- +title: "Configuration Hints" +date: 2018-05-02T00:00:00+00:00 +weight: 20 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/extensions/glauth +geekdocFilePath: configuration-hints.md +--- + +{{< toc >}} + +## Configuration hints + +The default setup does not use a fallback backend. It can be enabled by setting the `GLAUTH_FALLBACK_DATASTORE` environment variable. + +When using `owncloud` make sure to use the full URL to the [ownCloud 10 graph api app](https://github.com/owncloud/graphapi) endpoint, eg.: `GLAUTH_FALLBACK_SERVERS="https://demo.owncloud.com/apps/graphapi/v1.0"` diff --git a/docs/extensions/glauth/getting-started.md b/docs/extensions/glauth/getting-started.md deleted file mode 100644 index 67af22487..000000000 --- a/docs/extensions/glauth/getting-started.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 20 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/glauth -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -## Configuration Tips - -The default setup does not use a fallback backend. It can be enabled by setting the `GLAUTH_FALLBACK_DATASTORE` environment variable. When using `owncloud` make sure to use the full URL to the [ownCloud 10 graph api app](https://github.com/owncloud/graphapi) endpoint, eg.: `GLAUTH_FALLBACK_SERVERS="https://demo.owncloud.com/apps/graphapi/v1.0"` diff --git a/docs/extensions/konnectd/_index.md b/docs/extensions/konnectd/_index.md index be2859ce8..970db4e06 100644 --- a/docs/extensions/konnectd/_index.md +++ b/docs/extensions/konnectd/_index.md @@ -1,5 +1,6 @@ --- title: Konnectd +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/konnectd geekdocFilePath: _index.md diff --git a/docs/extensions/konnectd/getting-started.md b/docs/extensions/konnectd/getting-started.md deleted file mode 100644 index 61eef70d9..000000000 --- a/docs/extensions/konnectd/getting-started.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 10 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/konnectd -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -## Installation - -So far we are offering two different variants for the installation. You can choose between [Docker](https://www.docker.com/) or pre-built binaries which are stored on our download mirrors and GitHub releases. Maybe we will also provide system packages for the major distributions later if we see the need for it. - -### Docker - -Docker images for ocis-reva are hosted on https://hub.docker.com/r/owncloud/ocis-konnectd. - -The `latest` tag always reflects the current master branch. - -```console -docker pull owncloud/ocis-konnectd -``` - -### Binaries - -The pre-built binaries for different platforms are downloadable at https://download.owncloud.com/ocis/ocis-konnectd/ . Specific releases are organized in separate folders. They are in sync which every release tag on GitHub. The binaries from the current master branch can be found in https://download.owncloud.com/ocis/ocis-konnectd/testing/ - -```console -curl https://download.owncloud.com/ocis/ocis-konnectd/1.0.0-beta1/ocis-konnectd-1.0.0-beta1-darwin-amd64 --output ocis-konnectd -chmod +x ocis-konnectd -./ocis-konnectd server -``` - -## 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-konnectd --help`. - -### Server - -The server command is used to start the http and debug server on two addresses within a single process. The http server is serving the general webservice while the debug server is used for health check, readiness check and to server the metrics mentioned below. For further help please execute: - -{{< highlight txt >}} -konnectd server --help -{{< / highlight >}} - -### Health - -The health command is used to execute a health check, if the exit code equals zero the service should be up and running, if the exist code is greater than zero the service is not in a healthy state. Generally this command is used within our Docker containers, it could also be used within Kubernetes. - -{{< highlight txt >}} -konnectd health --help -{{< / highlight >}} - -### Version -The version command lists the versions of all running instances. For further help please execute: - -{{< highlight txt >}} -konnectd version --help -{{< /highlight >}} - -## 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 `KONNECTD_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:9134/metrics`. - -go_gc_duration_seconds -: A summary of the GC invocation durations - -go_gc_duration_seconds_sum -: A summary of the GC invocation durations - -go_gc_duration_seconds_count -: A summary of the GC invocation durations - -go_goroutines -: Number of goroutines that currently exist - -go_info -: Information about the Go environment - -go_memstats_alloc_bytes -: Number of bytes allocated and still in use - -go_memstats_alloc_bytes_total -: Total number of bytes allocated, even if freed - -go_memstats_buck_hash_sys_bytes -: Number of bytes used by the profiling bucket hash table - -go_memstats_frees_total -: Total number of frees - -go_memstats_gc_cpu_fraction -: The fraction of this program's available CPU time used by the GC since the program started - -go_memstats_gc_sys_bytes -: Number of bytes used for garbage collection system metadata - -go_memstats_heap_alloc_bytes -: Number of heap bytes allocated and still in use - -go_memstats_heap_idle_bytes -: Number of heap bytes waiting to be used - -go_memstats_heap_inuse_bytes -: Number of heap bytes that are in use - -go_memstats_heap_objects -: Number of allocated objects - -go_memstats_heap_released_bytes -: Number of heap bytes released to OS - -go_memstats_heap_sys_bytes -: Number of heap bytes obtained from system - -go_memstats_last_gc_time_seconds -: Number of seconds since 1970 of last garbage collection - -go_memstats_lookups_total -: Total number of pointer lookups - -go_memstats_mallocs_total -: Total number of mallocs - -go_memstats_mcache_inuse_bytes -: Number of bytes in use by mcache structures - -go_memstats_mcache_sys_bytes -: Number of bytes used for mcache structures obtained from system - -go_memstats_mspan_inuse_bytes -: Number of bytes in use by mspan structures - -go_memstats_mspan_sys_bytes -: Number of bytes used for mspan structures obtained from system - -go_memstats_next_gc_bytes -: Number of heap bytes when next garbage collection will take place - -go_memstats_other_sys_bytes -: Number of bytes used for other system allocations - -go_memstats_stack_inuse_bytes -: Number of bytes in use by the stack allocator - -go_memstats_stack_sys_bytes -: Number of bytes obtained from system for stack allocator - -go_memstats_sys_bytes -: Number of bytes obtained from system - -go_threads -: Number of OS threads created - -promhttp_metric_handler_requests_in_flight -: Current number of scrapes being served - -promhttp_metric_handler_requests_total -: Total number of scrapes by HTTP status code diff --git a/docs/extensions/ocis-phoenix/_index.md b/docs/extensions/ocis-phoenix/_index.md index a1dadd6f9..52e442ec8 100644 --- a/docs/extensions/ocis-phoenix/_index.md +++ b/docs/extensions/ocis-phoenix/_index.md @@ -1,7 +1,7 @@ --- title: "oCIS Web" date: 2018-05-02T00:00:00+00:00 -weight: 10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/ocis-phoenix geekdocFilePath: _index.md diff --git a/docs/extensions/ocis-phoenix/getting-started.md b/docs/extensions/ocis-phoenix/getting-started.md deleted file mode 100644 index b35f10e81..000000000 --- a/docs/extensions/ocis-phoenix/getting-started.md +++ /dev/null @@ -1,339 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 20 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/ocis-phoenix -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -## Installation - -So far we are offering two different variants for the installation. You can choose between [Docker](https://www.docker.com/) or pre-built binaries which are stored on our download mirrors and GitHub releases. Maybe we will also provide system packages for the major distributions later if we see the need for it. - -### Docker - -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. - -### Environment variables - -If you prefer to configure the service with environment variables you can see the available variables below. - -#### Global - -PHOENIX_CONFIG_FILE -: Path to config file, empty default value - -PHOENIX_LOG_LEVEL -: Set logging level, defaults to `info` - -PHOENIX_LOG_COLOR -: Enable colored logging, defaults to `true` - -PHOENIX_LOG_PRETTY -: Enable pretty logging, defaults to `true` - -#### Server - -PHOENIX_TRACING_ENABLED -: Enable sending traces, defaults to `false` - -PHOENIX_TRACING_TYPE -: Tracing backend type, defaults to `jaeger` - -PHOENIX_TRACING_ENDPOINT -: Endpoint for the agent, empty default value - -PHOENIX_TRACING_COLLECTOR -: Endpoint for the collector, empty default value - -PHOENIX_TRACING_SERVICE -: Service name for tracing, defaults to `phoenix` - -PHOENIX_DEBUG_ADDR -: Address to bind debug server, defaults to `0.0.0.0:9104` - -PHOENIX_DEBUG_TOKEN -: Token to grant metrics access, empty default value - -PHOENIX_DEBUG_PPROF -: Enable pprof debugging, defaults to `false` - -PHOENIX_DEBUG_ZPAGES -: Enable zpages debugging, defaults to `false` - -PHOENIX_HTTP_ADDR -: Address to bind http server, defaults to `0.0.0.0:9100` - -PHOENIX_HTTP_ROOT -: Root path of http server, defaults to `/` - -PHOENIX_ASSET_PATH -: Path to custom assets, empty default value - -PHOENIX_WEB_CONFIG -: Path to phoenix config, empty default value - -PHOENIX_WEB_CONFIG_SERVER -: Server URL, defaults to `http://localhost:9135` - -PHOENIX_WEB_CONFIG_THEME -: Theme, defaults to `owncloud` - -PHOENIX_WEB_CONFIG_VERSION -: Version, defaults to `0.1.0` - -PHOENIX_APPS -: Use multiple times to provide multiple apps - -PHOENIX_EXTERNAL_APPS -: Not supported yet, specify a config.json file via `PHOENIX_WEB_CONFIG` - -PHOENIX_OIDC_METADATA_URL -: OpenID Connect metadata URL, defaults to `http://localhost:9130/.well-known/openid-configuration` - -PHOENIX_OIDC_AUTHORITY -: OpenID Connect authority, defaults to `http://localhost:9130` - -PHOENIX_OIDC_CLIENT_ID -: OpenID Connect client ID, defaults to `phoenix` - -PHOENIX_OIDC_RESPONSE_TYPE -: OpenID Connect response type, defaults to `code` - -PHOENIX_OIDC_SCOPE -: OpenID Connect scope, defaults to `openid profile email` - -In case you want to render any additional properties in the config.json you can provide a custom config.json using eg. `PHOENIX_WEB_CONFIG=/path/to/config.json ocis-phoenix server` - -#### Health - -PHOENIX_DEBUG_ADDR -: Address to debug endpoint, defaults to `0.0.0.0:9104` - -### Commandline flags - -If you prefer to configure the service with commandline flags you can see the available variables below. - -#### Global - ---config-file -: Path to config file, empty default value - ---log-level -: Set logging level, defaults to `info` - ---log-color -: Enable colored logging, defaults to `true` - ---log-pretty -: Enable pretty logging, defaults to `true` - -#### Server - ---tracing-enabled -: Enable sending traces, defaults to `false` - ---tracing-type -: Tracing backend type, defaults to `jaeger` - ---tracing-endpoint -: Endpoint for the agent, empty default value - ---tracing-collector -: Endpoint for the collector, empty default value - ---tracing-service -: Service name for tracing, defaults to `phoenix` - ---debug-addr -: Address to bind debug server, defaults to `0.0.0.0:9104` - ---debug-token -: Token to grant metrics access, empty default value - ---debug-pprof -: Enable pprof debugging, defaults to `false` - ---debug-zpages -: Enable zpages debugging, defaults to `false` - ---http-addr -: Address to bind http server, defaults to `0.0.0.0:9100` - ---http-root -: Root path of http server, defaults to `/` - ---asset-path -: Path to custom assets, empty default value - ---web-config -: Path to phoenix config, empty default value - ---web-config-server -: Server URL, defaults to `http://localhost:9135` - ---web-config-theme -: Theme, defaults to `owncloud` - ---web-config-version -: Version, defaults to `0.1.0` - ---web-config-app -: Provide multiple apps, defaults to `""`. Usage: `phoenix --web-config-app files --web-config-app media-viewer` - ---oidc-metadata-url -: OpenID Connect metadata URL, defaults to `http://localhost:9130/.well-known/openid-configuration` - ---oidc-authority -: OpenID Connect authority, defaults to `http://localhost:9130` - ---oidc-client-id -: OpenID Connect client ID, defaults to `phoenix` - ---oidc-response-type -: OpenID Connect response type, defaults to `code` - ---oidc-scope -: OpenID Connect scope, defaults to `openid profile email` - -In case you want to render any additional properties in the config.json you can provide a custom config.json using eg. `ocis-phoenix server --web-config=/path/to/config.json` - -#### Health - ---debug-addr -: Address to debug endpoint, defaults to `0.0.0.0:9104` - -### 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/ocis-phoenix/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/phoenix.yml`, `${HOME}/.ocis/phoenix.yml` or `$(pwd)/config/phoenix.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-phoenix --help`. - -### Server - -The server command is used to start the http and debug server on two addresses within a single process. The http server is serving the general webservice while the debug server is used for health check, readiness check and to server the metrics mentioned below. For further help please execute: - -{{< highlight txt >}} -ocis-phoenix server --help -{{< / highlight >}} - -### Health - -The health command is used to execute a health check, if the exit code equals zero the service should be up and running, if the exist code is greater than zero the service is not in a healthy state. Generally this command is used within our Docker containers, it could also be used within Kubernetes. - -{{< highlight txt >}} -ocis-phoenix health --help -{{< / highlight >}} - -## 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 `PHOENIX_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:9104/metrics`. - -go_gc_duration_seconds -: A summary of the GC invocation durations - -go_gc_duration_seconds_sum -: A summary of the GC invocation durations - -go_gc_duration_seconds_count -: A summary of the GC invocation durations - -go_goroutines -: Number of goroutines that currently exist - -go_info -: Information about the Go environment - -go_memstats_alloc_bytes -: Number of bytes allocated and still in use - -go_memstats_alloc_bytes_total -: Total number of bytes allocated, even if freed - -go_memstats_buck_hash_sys_bytes -: Number of bytes used by the profiling bucket hash table - -go_memstats_frees_total -: Total number of frees - -go_memstats_gc_cpu_fraction -: The fraction of this program's available CPU time used by the GC since the program started - -go_memstats_gc_sys_bytes -: Number of bytes used for garbage collection system metadata - -go_memstats_heap_alloc_bytes -: Number of heap bytes allocated and still in use - -go_memstats_heap_idle_bytes -: Number of heap bytes waiting to be used - -go_memstats_heap_inuse_bytes -: Number of heap bytes that are in use - -go_memstats_heap_objects -: Number of allocated objects - -go_memstats_heap_released_bytes -: Number of heap bytes released to OS - -go_memstats_heap_sys_bytes -: Number of heap bytes obtained from system - -go_memstats_last_gc_time_seconds -: Number of seconds since 1970 of last garbage collection - -go_memstats_lookups_total -: Total number of pointer lookups - -go_memstats_mallocs_total -: Total number of mallocs - -go_memstats_mcache_inuse_bytes -: Number of bytes in use by mcache structures - -go_memstats_mcache_sys_bytes -: Number of bytes used for mcache structures obtained from system - -go_memstats_mspan_inuse_bytes -: Number of bytes in use by mspan structures - -go_memstats_mspan_sys_bytes -: Number of bytes used for mspan structures obtained from system - -go_memstats_next_gc_bytes -: Number of heap bytes when next garbage collection will take place - -go_memstats_other_sys_bytes -: Number of bytes used for other system allocations - -go_memstats_stack_inuse_bytes -: Number of bytes in use by the stack allocator - -go_memstats_stack_sys_bytes -: Number of bytes obtained from system for stack allocator - -go_memstats_sys_bytes -: Number of bytes obtained from system - -go_threads -: Number of OS threads created - -promhttp_metric_handler_requests_in_flight -: Current number of scrapes being served - -promhttp_metric_handler_requests_total -: Total number of scrapes by HTTP status code diff --git a/docs/extensions/ocs/_index.md b/docs/extensions/ocs/_index.md index ae12ce18e..f4371a7ac 100644 --- a/docs/extensions/ocs/_index.md +++ b/docs/extensions/ocs/_index.md @@ -1,7 +1,7 @@ --- title: "Ocs" date: 2018-05-02T00:00:00+00:00 -weight: 10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/ocs geekdocFilePath: _index.md diff --git a/docs/extensions/ocs/getting-started.md b/docs/extensions/ocs/getting-started.md deleted file mode 100644 index c8466cda1..000000000 --- a/docs/extensions/ocs/getting-started.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 10 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/ocs -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -## Installation - -So far we are offering two different variants for the installation. You can choose between [Docker](https://www.docker.com/) or pre-built binaries which are stored on our download mirrors and GitHub releases. Maybe we will also provide system packages for the major distributions later if we see the need for it. - -### Docker - -Docker images for ocis-ocs are hosted on https://hub.docker.com/r/owncloud/ocis-ocs. - -The `latest` tag always reflects the current master branch. - -```console -docker pull owncloud/ocis-ocs -``` - -### Binaries - -The pre-built binaries for different platforms are downloadable at https://download.owncloud.com/ocis/ocs/ . Specific releases are organized in separate folders. They are in sync which every release tag on GitHub. The binaries from the current master branch can be found in https://download.owncloud.com/ocis/ocs/testing/ - -```console -curl https://download.owncloud.com/ocis/ocis-ocs/1.0.0-beta1/ocis-ocs-1.0.0-beta1-darwin-amd64 --output ocis-ocs -chmod +x ocis-ocs -./ocis-ocs server -``` - -## 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-ocs --help`. - -### Server - -The server command is used to start the http and debug server on two addresses within a single process. The http server is serving the general webservice while the debug server is used for health check, readiness check and to server the metrics mentioned below. For further help please execute: - -{{< highlight txt >}} -ocs server --help -{{< / highlight >}} - -### Health - -The health command is used to execute a health check, if the exit code equals zero the service should be up and running, if the exist code is greater than zero the service is not in a healthy state. Generally this command is used within our Docker containers, it could also be used within Kubernetes. - -{{< highlight txt >}} -ocs health --help -{{< / highlight >}} - -### Version -The version command lists the versions of all running instances. For further help please execute: - -{{< highlight txt >}} -ocs version --help -{{< /highlight >}} - -## 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 `OCS_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:9114/metrics`. - -go_gc_duration_seconds -: A summary of the GC invocation durations - -go_gc_duration_seconds_sum -: A summary of the GC invocation durations - -go_gc_duration_seconds_count -: A summary of the GC invocation durations - -go_goroutines -: Number of goroutines that currently exist - -go_info -: Information about the Go environment - -go_memstats_alloc_bytes -: Number of bytes allocated and still in use - -go_memstats_alloc_bytes_total -: Total number of bytes allocated, even if freed - -go_memstats_buck_hash_sys_bytes -: Number of bytes used by the profiling bucket hash table - -go_memstats_frees_total -: Total number of frees - -go_memstats_gc_cpu_fraction -: The fraction of this program's available CPU time used by the GC since the program started - -go_memstats_gc_sys_bytes -: Number of bytes used for garbage collection system metadata - -go_memstats_heap_alloc_bytes -: Number of heap bytes allocated and still in use - -go_memstats_heap_idle_bytes -: Number of heap bytes waiting to be used - -go_memstats_heap_inuse_bytes -: Number of heap bytes that are in use - -go_memstats_heap_objects -: Number of allocated objects - -go_memstats_heap_released_bytes -: Number of heap bytes released to OS - -go_memstats_heap_sys_bytes -: Number of heap bytes obtained from system - -go_memstats_last_gc_time_seconds -: Number of seconds since 1970 of last garbage collection - -go_memstats_lookups_total -: Total number of pointer lookups - -go_memstats_mallocs_total -: Total number of mallocs - -go_memstats_mcache_inuse_bytes -: Number of bytes in use by mcache structures - -go_memstats_mcache_sys_bytes -: Number of bytes used for mcache structures obtained from system - -go_memstats_mspan_inuse_bytes -: Number of bytes in use by mspan structures - -go_memstats_mspan_sys_bytes -: Number of bytes used for mspan structures obtained from system - -go_memstats_next_gc_bytes -: Number of heap bytes when next garbage collection will take place - -go_memstats_other_sys_bytes -: Number of bytes used for other system allocations - -go_memstats_stack_inuse_bytes -: Number of bytes in use by the stack allocator - -go_memstats_stack_sys_bytes -: Number of bytes obtained from system for stack allocator - -go_memstats_sys_bytes -: Number of bytes obtained from system - -go_threads -: Number of OS threads created - -promhttp_metric_handler_requests_in_flight -: Current number of scrapes being served - -promhttp_metric_handler_requests_total -: Total number of scrapes by HTTP status code diff --git a/docs/extensions/proxy/_index.md b/docs/extensions/proxy/_index.md index 541be599f..2a63dc7c2 100644 --- a/docs/extensions/proxy/_index.md +++ b/docs/extensions/proxy/_index.md @@ -1,8 +1,9 @@ --- title: Proxy +weight: 20 geekdocRepo: https://github.com/owncloud/ocis 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 an proxy service that routes requests to the correct extensions. diff --git a/docs/extensions/proxy/about.md b/docs/extensions/proxy/about.md deleted file mode 100644 index 10157aa08..000000000 --- a/docs/extensions/proxy/about.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "About" -date: 2020-02-07T00:00:00+00:00 -weight: 10 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/proxy -geekdocFilePath: about.md ---- - -This service provides an proxy service that routes requests to the correct services. diff --git a/docs/extensions/proxy/getting-started.md b/docs/extensions/proxy/getting-started.md deleted file mode 100644 index 67a23addf..000000000 --- a/docs/extensions/proxy/getting-started.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 15 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/proxy -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -## Installation - -So far we are offering two different variants for the installation. You can choose between [Docker](https://www.docker.com/) or pre-built binaries which are stored on our download mirrors and GitHub releases. Maybe we will also provide system packages for the major distributions later if we see the need for it. - -### Docker - -Docker images for ocis-reva are hosted on https://hub.docker.com/r/owncloud/ocis-proxy. - -The `latest` tag always reflects the current master branch. - -```console -docker pull owncloud/ocis-proxy -``` - -### Binaries - -The pre-built binaries for different platforms are downloadable at https://download.owncloud.com/ocis/ocis-proxy/ . Specific releases are organized in separate folders. They are in sync which every release tag on GitHub. The binaries from the current master branch can be found in https://download.owncloud.com/ocis/ocis-proxy/testing/ - -```console -curl https://download.owncloud.com/ocis/ocis-proxy/1.0.0-beta1/ocis-proxy-1.0.0-beta1-darwin-amd64 --output ocis-proxy -chmod +x ocis-proxy -./ocis-proxy server -``` - -## 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-proxy --help`. - -### Server - -The server command is used to start the http server. For further help please execute: - -{{< highlight txt >}} -proxy server --help -{{< / highlight >}} - -### Version -The version command lists the versions of all running instances. For further help please execute: - -{{< highlight txt >}} -proxy version --help -{{< /highlight >}} diff --git a/docs/extensions/settings/_index.md b/docs/extensions/settings/_index.md index a00ebc2cf..840b55e8c 100644 --- a/docs/extensions/settings/_index.md +++ b/docs/extensions/settings/_index.md @@ -1,7 +1,7 @@ --- title: "Settings" date: 2018-05-02T00:00:00+00:00 -weight: 10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/settings geekdocFilePath: _index.md @@ -14,7 +14,7 @@ for other extensions to register new settings within oCIS. It is responsible for settings values as well. For ease of use, this extension provides an ocis-web extension which allows users to change their settings values. -Please refer to the [ocis-web extension docs](https://owncloud.github.io/ocis/extensions/#external-phoenix-apps) +Please refer to the [ocis-web extension docs]({{< relref "../../ocis/development/extensions/#external-phoenix-apps" >}}) for running ocis-web extensions. {{< mermaid class="text-center">}} diff --git a/docs/extensions/settings/getting-started.md b/docs/extensions/settings/getting-started.md deleted file mode 100644 index 571a82527..000000000 --- a/docs/extensions/settings/getting-started.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 25 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/settings -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -## Installation - -So far we are offering two different variants for the installation. You can choose between [Docker](https://www.docker.com/) or pre-built binaries which are stored on our download mirrors and GitHub releases. Maybe we will also provide system packages for the major distributions later if we see the need for it. - -### Docker - -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. - -### Environment variables - -If you prefer to configure the service with environment variables you can see the available variables below. - -#### Global - -SETTINGS_CONFIG_FILE -: Path to config file, empty default value - -SETTINGS_LOG_LEVEL -: Set logging level, defaults to `info` - -SETTINGS_LOG_COLOR -: Enable colored logging, defaults to `true` - -SETTINGS_LOG_PRETTY -: Enable pretty logging, defaults to `true` - -#### Server - -SETTINGS_TRACING_ENABLED -: Enable sending traces, defaults to `false` - -SETTINGS_TRACING_TYPE -: Tracing backend type, defaults to `jaeger` - -SETTINGS_TRACING_ENDPOINT -: Endpoint for the agent, empty default value - -SETTINGS_TRACING_COLLECTOR -: Endpoint for the collector, empty default value - -SETTINGS_TRACING_SERVICE -: Service name for tracing, defaults to `settings` - -SETTINGS_DEBUG_ADDR -: Address to bind debug server, defaults to `0.0.0.0:9194` - -SETTINGS_DEBUG_TOKEN -: Token to grant metrics access, empty default value - -SETTINGS_DEBUG_PPROF -: Enable pprof debugging, defaults to `false` - -SETTINGS_DEBUG_ZPAGES -: Enable zpages debugging, defaults to `false` - -SETTINGS_HTTP_ADDR -: Address to bind http server, defaults to `0.0.0.0:9190` - -SETTINGS_HTTP_NAMESPACE -: The http namespace - -SETTINGS_HTTP_ROOT -: Root path of http server, defaults to `/` - -#### Health - -SETTINGS_DEBUG_ADDR -: Address to debug endpoint, defaults to `0.0.0.0:9194` - -### Commandline flags - -If you prefer to configure the service with commandline flags you can see the available variables below. - -#### Global - ---config-file -: Path to config file, empty default value - ---log-level -: Set logging level, defaults to `info` - ---log-color -: Enable colored logging, defaults to `true` - ---log-pretty -: Enable pretty logging, defaults to `true` - -#### Server - ---tracing-enabled -: Enable sending traces, defaults to `false` - ---tracing-type -: Tracing backend type, defaults to `jaeger` - ---tracing-endpoint -: Endpoint for the agent, empty default value - ---tracing-collector -: Endpoint for the collector, empty default value - ---tracing-service -: Service name for tracing, defaults to `settings` - ---debug-addr -: Address to bind debug server, defaults to `0.0.0.0:9194` - ---debug-token -: Token to grant metrics access, empty default value - ---debug-pprof -: Enable pprof debugging, defaults to `false` - ---debug-zpages -: Enable zpages debugging, defaults to `false` - ---http-addr -: Address to bind http server, defaults to `0.0.0.0:9190` - ---http-namespace -: Namespace for internal services communication, defaults to `com.owncloud.web` - ---http-root -: Root path of http server, defaults to `/` - -#### Health - ---debug-addr -: Address to debug endpoint, defaults to `0.0.0.0:9194` - -### 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/settings/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/settings.yml`, `${HOME}/.ocis/settings.yml` or `$(pwd)/config/settings.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-settings --help`. - -### Server - -The server command is used to start the http and debug server on two addresses within a single process. The http server is serving the general webservice while the debug server is used for health check, readiness check and to server the metrics mentioned below. For further help please execute: - -{{< highlight txt >}} -settings server --help -{{< / highlight >}} - -### Health - -The health command is used to execute a health check, if the exit code equals zero the service should be up and running, if the exist code is greater than zero the service is not in a healthy state. Generally this command is used within our Docker containers, it could also be used within Kubernetes. - -{{< highlight txt >}} -settings health --help -{{< / highlight >}} - -### Version -The version command lists the versions of all running instances. For further help please execute: - -{{< highlight txt >}} -settings version --help -{{< /highlight >}} - -## 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 `SETTINGS_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:9194/metrics`. - -go_gc_duration_seconds -: A summary of the GC invocation durations - -go_gc_duration_seconds_sum -: A summary of the GC invocation durations - -go_gc_duration_seconds_count -: A summary of the GC invocation durations - -go_goroutines -: Number of goroutines that currently exist - -go_info -: Information about the Go environment - -go_memstats_alloc_bytes -: Number of bytes allocated and still in use - -go_memstats_alloc_bytes_total -: Total number of bytes allocated, even if freed - -go_memstats_buck_hash_sys_bytes -: Number of bytes used by the profiling bucket hash table - -go_memstats_frees_total -: Total number of frees - -go_memstats_gc_cpu_fraction -: The fraction of this program's available CPU time used by the GC since the program started - -go_memstats_gc_sys_bytes -: Number of bytes used for garbage collection system metadata - -go_memstats_heap_alloc_bytes -: Number of heap bytes allocated and still in use - -go_memstats_heap_idle_bytes -: Number of heap bytes waiting to be used - -go_memstats_heap_inuse_bytes -: Number of heap bytes that are in use - -go_memstats_heap_objects -: Number of allocated objects - -go_memstats_heap_released_bytes -: Number of heap bytes released to OS - -go_memstats_heap_sys_bytes -: Number of heap bytes obtained from system - -go_memstats_last_gc_time_seconds -: Number of seconds since 1970 of last garbage collection - -go_memstats_lookups_total -: Total number of pointer lookups - -go_memstats_mallocs_total -: Total number of mallocs - -go_memstats_mcache_inuse_bytes -: Number of bytes in use by mcache structures - -go_memstats_mcache_sys_bytes -: Number of bytes used for mcache structures obtained from system - -go_memstats_mspan_inuse_bytes -: Number of bytes in use by mspan structures - -go_memstats_mspan_sys_bytes -: Number of bytes used for mspan structures obtained from system - -go_memstats_next_gc_bytes -: Number of heap bytes when next garbage collection will take place - -go_memstats_other_sys_bytes -: Number of bytes used for other system allocations - -go_memstats_stack_inuse_bytes -: Number of bytes in use by the stack allocator - -go_memstats_stack_sys_bytes -: Number of bytes obtained from system for stack allocator - -go_memstats_sys_bytes -: Number of bytes obtained from system - -go_threads -: Number of OS threads created - -promhttp_metric_handler_requests_in_flight -: Current number of scrapes being served - -promhttp_metric_handler_requests_total -: Total number of scrapes by HTTP status code diff --git a/docs/extensions/settings/values.md b/docs/extensions/settings/values.md index 3e025d2b0..4594c6fb8 100644 --- a/docs/extensions/settings/values.md +++ b/docs/extensions/settings/values.md @@ -14,7 +14,7 @@ provided by this service. ## Identifying settings values A *settings value* is uniquely identified by four attributes. Three of them are coming from the definition of -the setting within it's settings bundle (see [Settings Bundles](https://owncloud.github.io/extensions/ocis_settings/bundles/) +the setting within it's settings bundle (see [Settings Bundles]({{< relref "bundles.md" >}}) for an example). The fourth identifies the user. - extension: Key of the extension that registered the settings bundle, - bundleKey: Key of the settings bundle, diff --git a/docs/extensions/storage/_index.md b/docs/extensions/storage/_index.md index 3de169462..cd17f4584 100644 --- a/docs/extensions/storage/_index.md +++ b/docs/extensions/storage/_index.md @@ -1,7 +1,7 @@ --- -title: "Reva" +title: "Storage" date: 2018-05-02T00:00:00+00:00 -weight: 10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/storage geekdocFilePath: _index.md diff --git a/docs/extensions/store/_index.md b/docs/extensions/store/_index.md index b1de3b501..9a5e1345a 100644 --- a/docs/extensions/store/_index.md +++ b/docs/extensions/store/_index.md @@ -1,7 +1,7 @@ --- title: "Store" date: 2018-05-02T00:00:00+00:00 -weight: 10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/store geekdocFilePath: _index.md diff --git a/docs/extensions/store/getting-started.md b/docs/extensions/store/getting-started.md deleted file mode 100644 index 6bc739ebf..000000000 --- a/docs/extensions/store/getting-started.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 20 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/store -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -## Installation - -So far we are offering two different variants for the installation. You can choose between [Docker](https://www.docker.com/) or pre-built binaries which are stored on our download mirrors and GitHub releases. Maybe we will also provide system packages for the major distributions later if we see the need for it. - -### Docker - -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. - -### Environment variables - -If you prefer to configure the service with environment variables you can see the available variables below. - -#### Global - -STORE_CONFIG_FILE -: Path to config file, empty default value - -STORE_LOG_LEVEL -: Set logging level, defaults to `info` - -STORE_LOG_COLOR -: Enable colored logging, defaults to `true` - -STORE_LOG_PRETTY -: Enable pretty logging, defaults to `true` - -#### Server - -STORE_TRACING_ENABLED -: Enable sending traces, defaults to `false` - -STORE_TRACING_TYPE -: Tracing backend type, defaults to `jaeger` - -STORE_TRACING_ENDPOINT -: Endpoint for the agent, empty default value - -STORE_TRACING_COLLECTOR -: Endpoint for the collector, empty default value - -STORE_TRACING_SERVICE -: Service name for tracing, defaults to `store` - -STORE_DEBUG_ADDR -: Address to bind debug server - -STORE_DEBUG_TOKEN -: Token to grant metrics access, empty default value - -STORE_DEBUG_PPROF -: Enable pprof debugging, defaults to `false` - -STORE_DEBUG_ZPAGES -: Enable zpages debugging, defaults to `false` - -STORE_HTTP_ADDR -: Address to bind http server, defaults to `0.0.0.0:9461` - -STORE_HTTP_NAMESPACE -: The http namespace - -STORE_HTTP_ROOT -: Root path of http server, defaults to `/` - -#### Health - -STORE_DEBUG_ADDR -: Address to debug endpoint - -### Commandline flags - -If you prefer to configure the service with commandline flags you can see the available variables below. - -#### Global - ---config-file -: Path to config file, empty default value - ---log-level -: Set logging level, defaults to `info` - ---log-color -: Enable colored logging, defaults to `true` - ---log-pretty -: Enable pretty logging, defaults to `true` - -#### Server - ---tracing-enabled -: Enable sending traces, defaults to `false` - ---tracing-type -: Tracing backend type, defaults to `jaeger` - ---tracing-endpoint -: Endpoint for the agent, empty default value - ---tracing-collector -: Endpoint for the collector, empty default value - ---tracing-service -: Service name for tracing, defaults to `store` - ---debug-addr -: Address to bind debug server - ---debug-token -: Token to grant metrics access, empty default value - ---debug-pprof -: Enable pprof debugging, defaults to `false` - ---debug-zpages -: Enable zpages debugging, defaults to `false` - ---http-addr -: Address to bind http server, defaults to `0.0.0.0:9461` - ---http-namespace -: Namespace for internal services communication, defaults to `com.owncloud.web` - ---http-root -: Root path of http server, defaults to `/` - -#### Health - ---debug-addr -: Address to debug endpoint - -### 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/store/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/store.yml`, `${HOME}/.ocis/store.yml` or `$(pwd)/config/store.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-store --help`. - -### Server - -The server command is used to start the http and debug server on two addresses within a single process. The http server is serving the general webservice while the debug server is used for health check, readiness check and to server the metrics mentioned below. For further help please execute: - -{{< highlight txt >}} -store server --help -{{< / highlight >}} - -### Health - -The health command is used to execute a health check, if the exit code equals zero the service should be up and running, if the exist code is greater than zero the service is not in a healthy state. Generally this command is used within our Docker containers, it could also be used within Kubernetes. - -{{< highlight txt >}} -store health --help -{{< / highlight >}} - -### Version -The version command lists the versions of all running instances. For further help please execute: - -{{< highlight txt >}} -store version --help -{{< /highlight >}} - -## 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 `STORE_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:9460/metrics`. - -go_gc_duration_seconds -: A summary of the GC invocation durations - -go_gc_duration_seconds_sum -: A summary of the GC invocation durations - -go_gc_duration_seconds_count -: A summary of the GC invocation durations - -go_goroutines -: Number of goroutines that currently exist - -go_info -: Information about the Go environment - -go_memstats_alloc_bytes -: Number of bytes allocated and still in use - -go_memstats_alloc_bytes_total -: Total number of bytes allocated, even if freed - -go_memstats_buck_hash_sys_bytes -: Number of bytes used by the profiling bucket hash table - -go_memstats_frees_total -: Total number of frees - -go_memstats_gc_cpu_fraction -: The fraction of this program's available CPU time used by the GC since the program started - -go_memstats_gc_sys_bytes -: Number of bytes used for garbage collection system metadata - -go_memstats_heap_alloc_bytes -: Number of heap bytes allocated and still in use - -go_memstats_heap_idle_bytes -: Number of heap bytes waiting to be used - -go_memstats_heap_inuse_bytes -: Number of heap bytes that are in use - -go_memstats_heap_objects -: Number of allocated objects - -go_memstats_heap_released_bytes -: Number of heap bytes released to OS - -go_memstats_heap_sys_bytes -: Number of heap bytes obtained from system - -go_memstats_last_gc_time_seconds -: Number of seconds since 1970 of last garbage collection - -go_memstats_lookups_total -: Total number of pointer lookups - -go_memstats_mallocs_total -: Total number of mallocs - -go_memstats_mcache_inuse_bytes -: Number of bytes in use by mcache structures - -go_memstats_mcache_sys_bytes -: Number of bytes used for mcache structures obtained from system - -go_memstats_mspan_inuse_bytes -: Number of bytes in use by mspan structures - -go_memstats_mspan_sys_bytes -: Number of bytes used for mspan structures obtained from system - -go_memstats_next_gc_bytes -: Number of heap bytes when next garbage collection will take place - -go_memstats_other_sys_bytes -: Number of bytes used for other system allocations - -go_memstats_stack_inuse_bytes -: Number of bytes in use by the stack allocator - -go_memstats_stack_sys_bytes -: Number of bytes obtained from system for stack allocator - -go_memstats_sys_bytes -: Number of bytes obtained from system - -go_threads -: Number of OS threads created - -promhttp_metric_handler_requests_in_flight -: Current number of scrapes being served - -promhttp_metric_handler_requests_total -: Total number of scrapes by HTTP status code diff --git a/docs/extensions/thumbnails/_index.md b/docs/extensions/thumbnails/_index.md index d0ca7f2e6..14ec38f27 100644 --- a/docs/extensions/thumbnails/_index.md +++ b/docs/extensions/thumbnails/_index.md @@ -1,7 +1,7 @@ --- title: "Thumbnails" date: 2018-05-02T00:00:00+00:00 -weight: 10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/thumbnails geekdocFilePath: _index.md diff --git a/docs/extensions/thumbnails/getting-started.md b/docs/extensions/thumbnails/getting-started.md deleted file mode 100644 index 99aee374c..000000000 --- a/docs/extensions/thumbnails/getting-started.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 20 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/thumbnails -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -## Installation - -So far we are offering two different variants for the installation. You can choose between [Docker](https://www.docker.com/) or pre-built binaries which are stored on our download mirrors and GitHub releases. Maybe we will also provide system packages for the major distributions later if we see the need for it. - -### Docker - -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. - -### Environment variables - -If you prefer to configure the service with environment variables you can see the available variables below. - -#### Global - -THUMBNAILS_CONFIG_FILE -: Path to config file, empty default value - -THUMBNAILS_LOG_LEVEL -: Set logging level, defaults to `info` - -THUMBNAILS_LOG_COLOR -: Enable colored logging, defaults to `true` - -THUMBNAILS_LOG_PRETTY -: Enable pretty logging, defaults to `true` - -#### Server - -THUMBNAILS_TRACING_ENABLED -: Enable sending traces, defaults to `false` - -THUMBNAILS_TRACING_TYPE -: Tracing backend type, defaults to `jaeger` - -THUMBNAILS_TRACING_ENDPOINT -: Endpoint for the agent, empty default value - -THUMBNAILS_TRACING_COLLECTOR -: Endpoint for the collector, empty default value - -THUMBNAILS_TRACING_SERVICE -: Service name for tracing, defaults to `ocis-thumbnails` - -THUMBNAILS_DEBUG_ADDR -: Address to bind debug server, defaults to `0.0.0.0:9114` - -THUMBNAILS_DEBUG_TOKEN -: Token to grant metrics access, empty default value - -THUMBNAILS_DEBUG_PPROF -: Enable pprof debugging, defaults to `false` - -THUMBNAILS_DEBUG_ZPAGES -: Enable zpages debugging, defaults to `false` - -THUMBNAILS_GRPC_NAME -: Name of the service, defaults to `thumbnails` - -THUMBNAILS_GRPC_ADDR -: Address to bind grpc server, defaults to `0.0.0.0:9185` - -THUMBNAILS_GRPC_NAMESPACE -: Set the base namespace for the grpc namespace", defaults to `com.owncloud.api` - -THUMBNAILS_FILESYSTEMSTORAGE_ROOT -: Root path of the filesystem storage directory, defaults to `/ocis-thumbnails/` - -THUMBNAILS_WEBDAVSOURCE_BASEURL -: Base url for a webdav api, defaults to `https://localhost:9200/remote.php/webdav/` - -THUMBNAILS_RESOLUTIONS -: List of resolutions supported by the service, defaults to `["16x16", "32x32", "64x64", "128x128"] - -#### Health - -THUMBNAILS_DEBUG_ADDR -: Address to debug endpoint, defaults to `0.0.0.0:9189` - -### Commandline flags - -If you prefer to configure the service with commandline flags you can see the available variables below. - -#### Global - ---config-file -: Path to config file, empty default value - ---log-level -: Set logging level, defaults to `info` - ---log-color -: Enable colored logging, defaults to `true` - ---log-pretty -: Enable pretty logging, defaults to `true` - -#### Server - ---tracing-enabled -: Enable sending traces, defaults to `false` - ---tracing-type -: Tracing backend type, defaults to `jaeger` - ---tracing-endpoint -: Endpoint for the agent, empty default value - ---tracing-collector -: Endpoint for the collector, empty default value - ---tracing-service -: Service name for tracing, defaults to `thumbnails` - ---debug-addr -: Address to bind debug server, defaults to `0.0.0.0:9189` - ---debug-token -: Token to grant metrics access, empty default value - ---debug-pprof -: Enable pprof debugging, defaults to `false` - ---debug-zpages -: Enable zpages debugging, defaults to `false` - ---grpc-name -: Name of the service, defaults to `thumbnails` - ---grpc-addr -: Address to bind grpc server, defaults to `0.0.0.0:9185` - ---grpc-namespace -: Set the base namespace for the grpc namespace", defaults to `com.owncloud.api` - ---filesystemstorage-root -: Root path of the filesystem storage directory, defaults to `/ocis-thumbnails/` - ---webdavsource-baseurl -: Base url for a webdav api, defaults to `https://localhost:9200/remote.php/webdav/` - ---thumbnail-resolution -: List of resolutions supported by the service, defaults to `["16x16", "32x32", "64x64", "128x128"] - -#### Health - ---debug-addr -: Address to debug endpoint, defaults to `0.0.0.0:9189` - -### 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/thumbnails/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/thumbnails.yml`, `${HOME}/.ocis/thumbnails.yml` or `$(pwd)/config/thumbnails.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-thumbnails --help`. - -### Server - -The server command is used to start the http and debug server on two addresses within a single process. The http server is serving the general webservice while the debug server is used for health check, readiness check and to server the metrics mentioned below. For further help please execute: - -{{< highlight txt >}} -{{ Name }} server --help -{{< / highlight >}} - -### Health - -The health command is used to execute a health check, if the exit code equals zero the service should be up and running, if the exist code is greater than zero the service is not in a healthy state. Generally this command is used within our Docker containers, it could also be used within Kubernetes. - -{{< highlight txt >}} -{{ Name }} health --help -{{< / highlight >}} - -### Version -The version command lists the versions of all running instances. For further help please execute: - -{{< highlight txt >}} -{{ Name }} version --help -{{< /highlight >}} - -## 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 `THUMBNAILS_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:9114/metrics`. - -go_gc_duration_seconds -: A summary of the GC invocation durations - -go_gc_duration_seconds_sum -: A summary of the GC invocation durations - -go_gc_duration_seconds_count -: A summary of the GC invocation durations - -go_goroutines -: Number of goroutines that currently exist - -go_info -: Information about the Go environment - -go_memstats_alloc_bytes -: Number of bytes allocated and still in use - -go_memstats_alloc_bytes_total -: Total number of bytes allocated, even if freed - -go_memstats_buck_hash_sys_bytes -: Number of bytes used by the profiling bucket hash table - -go_memstats_frees_total -: Total number of frees - -go_memstats_gc_cpu_fraction -: The fraction of this program's available CPU time used by the GC since the program started - -go_memstats_gc_sys_bytes -: Number of bytes used for garbage collection system metadata - -go_memstats_heap_alloc_bytes -: Number of heap bytes allocated and still in use - -go_memstats_heap_idle_bytes -: Number of heap bytes waiting to be used - -go_memstats_heap_inuse_bytes -: Number of heap bytes that are in use - -go_memstats_heap_objects -: Number of allocated objects - -go_memstats_heap_released_bytes -: Number of heap bytes released to OS - -go_memstats_heap_sys_bytes -: Number of heap bytes obtained from system - -go_memstats_last_gc_time_seconds -: Number of seconds since 1970 of last garbage collection - -go_memstats_lookups_total -: Total number of pointer lookups - -go_memstats_mallocs_total -: Total number of mallocs - -go_memstats_mcache_inuse_bytes -: Number of bytes in use by mcache structures - -go_memstats_mcache_sys_bytes -: Number of bytes used for mcache structures obtained from system - -go_memstats_mspan_inuse_bytes -: Number of bytes in use by mspan structures - -go_memstats_mspan_sys_bytes -: Number of bytes used for mspan structures obtained from system - -go_memstats_next_gc_bytes -: Number of heap bytes when next garbage collection will take place - -go_memstats_other_sys_bytes -: Number of bytes used for other system allocations - -go_memstats_stack_inuse_bytes -: Number of bytes in use by the stack allocator - -go_memstats_stack_sys_bytes -: Number of bytes obtained from system for stack allocator - -go_memstats_sys_bytes -: Number of bytes obtained from system - -go_threads -: Number of OS threads created - -promhttp_metric_handler_requests_in_flight -: Current number of scrapes being served - -promhttp_metric_handler_requests_total -: Total number of scrapes by HTTP status code diff --git a/docs/extensions/thumbnails/releasing.md b/docs/extensions/thumbnails/releasing.md deleted file mode 100644 index da0fc028d..000000000 --- a/docs/extensions/thumbnails/releasing.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "Releasing" -date: 2018-05-02T00:00:00+00:00 -weight: 40 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/thumbnails -geekdocFilePath: releasing.md ---- - -{{< toc >}} - -To release a new version of ocis-thumbnails, you have to follow a few simple steps. - -## Preperation - -1. Create a new branch e.g. `release-x.x.x` where `x.x.x` is the version you want to release. -2. Checkout the preparation branch. -3. Create a new changelog folder and move the unreleased snippets there. -{{< highlight txt >}} -mkdir changelog/x.x.x_yyyy-MM-dd/ # yyyy-MM-dd is the current date -mv changelog/unreleased/* changelog/x.x.x_yyyy-MM-dd/ -{{< / highlight >}} -4. Commit and push the changes -{{< highlight txt >}} -git add --all -git commit -m "prepare release x.x.x" -git push -{{< / highlight >}} -5. Create a pull request to the master branch. - -## Release -1. After the preparation branch has been merged update your local master. -{{< highlight txt >}} -git checkout master -git pull -{{< / highlight >}} -2. Create a new tag (preferably signed). -{{< highlight txt >}} -git tag -s vx.x.x -m "release vx.x.x" -git push --tags -{{< / highlight >}} -3. Wait for CI and check that the GitHub release was published. - - -Congratulations, you just released ocis-thumbnails! diff --git a/docs/extensions/webdav/_index.md b/docs/extensions/webdav/_index.md index 77fd49925..53abbe1ed 100644 --- a/docs/extensions/webdav/_index.md +++ b/docs/extensions/webdav/_index.md @@ -1,7 +1,7 @@ --- title: WebDaV date: 2018-05-02T00:00:00+00:00 -weight: 10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/extensions/webdav geekdocFilePath: _index.md diff --git a/docs/extensions/webdav/getting-started.md b/docs/extensions/webdav/getting-started.md deleted file mode 100644 index d975cb3bc..000000000 --- a/docs/extensions/webdav/getting-started.md +++ /dev/null @@ -1,276 +0,0 @@ ---- -title: "Getting Started" -date: 2018-05-02T00:00:00+00:00 -weight: 20 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/extensions/webdav -geekdocFilePath: getting-started.md ---- - -{{< toc >}} - -### Installation - -So far we are offering two different variants for the installation. You can choose between [Docker](https://www.docker.com/) or pre-built binaries which are stored on our download mirrors and GitHub releases. Maybe we will also provide system packages for the major distributions later if we see the need for it. - -#### Docker - -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. - -#### Environment variables - -If you prefer to configure the service with environment variables you can see the available variables below. - -##### Global - -WEBDAV_CONFIG_FILE -: Path to config file, empty default value - -WEBDAV_LOG_LEVEL -: Set logging level, defaults to `info` - -WEBDAV_LOG_COLOR -: Enable colored logging, defaults to `true` - -WEBDAV_LOG_PRETTY -: Enable pretty logging, defaults to `true` - -##### Server - -WEBDAV_TRACING_ENABLED -: Enable sending traces, defaults to `false` - -WEBDAV_TRACING_TYPE -: Tracing backend type, defaults to `jaeger` - -WEBDAV_TRACING_ENDPOINT -: Endpoint for the agent, empty default value - -WEBDAV_TRACING_COLLECTOR -: Endpoint for the collector, empty default value - -WEBDAV_TRACING_SERVICE -: Service name for tracing, defaults to `webdav` - -WEBDAV_DEBUG_ADDR -: Address to bind debug server, defaults to `0.0.0.0:9119` - -WEBDAV_DEBUG_TOKEN -: Token to grant metrics access, empty default value - -WEBDAV_DEBUG_PPROF -: Enable pprof debugging, defaults to `false` - -WEBDAV_DEBUG_ZPAGES -: Enable zpages debugging, defaults to `false` - -WEBDAV_HTTP_ADDR -: Address to bind http server, defaults to `0.0.0.0:9115` - -WEBDAV_HTTP_ROOT -: Root path of http server, defaults to `/` - -##### Health - -WEBDAV_DEBUG_ADDR -: Address to debug endpoint, defaults to `0.0.0.0:9119` - -#### Commandline flags - -If you prefer to configure the service with commandline flags you can see the available variables below. - -##### Global - ---config-file -: Path to config file, empty default value - ---log-level -: Set logging level, defaults to `info` - ---log-color -: Enable colored logging, defaults to `true` - ---log-pretty -: Enable pretty logging, defaults to `true` - -##### Server - ---tracing-enabled -: Enable sending traces, defaults to `false` - ---tracing-type -: Tracing backend type, defaults to `jaeger` - ---tracing-endpoint -: Endpoint for the agent, empty default value - ---tracing-collector -: Endpoint for the collector, empty default value - ---tracing-service -: Service name for tracing, defaults to `webdav` - ---debug-addr -: Address to bind debug server, defaults to `0.0.0.0:9119` - ---debug-token -: Token to grant metrics access, empty default value - ---debug-pprof -: Enable pprof debugging, defaults to `false` - ---debug-zpages -: Enable zpages debugging, defaults to `false` - ---http-addr -: Address to bind http server, defaults to `0.0.0.0:9115` - ---http-namespace -: Namespace for internal services communication, defaults to `com.owncloud.web` - ---http-root -: Root path of http server, defaults to `/` - -##### Health - ---debug-addr -: Address to debug endpoint, defaults to `0.0.0.0:9119` - -#### 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/webdav/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/webdav.yml`, `${HOME}/.ocis/webdav.yml` or `$(pwd)/config/webdav.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-webdav --help`. - -#### Server - -The server command is used to start the http and debug server on two addresses within a single process. The http server is serving the general webservice while the debug server is used for health check, readiness check and to server the metrics mentioned below. For further help please execute: - -{{< highlight txt >}} -webdav server --help -{{< / highlight >}} - -#### Health - -The health command is used to execute a health check, if the exit code equals zero the service should be up and running, if the exist code is greater than zero the service is not in a healthy state. Generally this command is used within our Docker containers, it could also be used within Kubernetes. - -{{< highlight txt >}} -webdav health --help -{{< / highlight >}} - -### Version -The version command lists the versions of all running instances. For further help please execute: - -{{< highlight txt >}} -webdav version --help -{{< /highlight >}} - -### 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 `WEBDAV_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:9119/metrics`. - -go_gc_duration_seconds -: A summary of the GC invocation durations - -go_gc_duration_seconds_sum -: A summary of the GC invocation durations - -go_gc_duration_seconds_count -: A summary of the GC invocation durations - -go_goroutines -: Number of goroutines that currently exist - -go_info -: Information about the Go environment - -go_memstats_alloc_bytes -: Number of bytes allocated and still in use - -go_memstats_alloc_bytes_total -: Total number of bytes allocated, even if freed - -go_memstats_buck_hash_sys_bytes -: Number of bytes used by the profiling bucket hash table - -go_memstats_frees_total -: Total number of frees - -go_memstats_gc_cpu_fraction -: The fraction of this program's available CPU time used by the GC since the program started - -go_memstats_gc_sys_bytes -: Number of bytes used for garbage collection system metadata - -go_memstats_heap_alloc_bytes -: Number of heap bytes allocated and still in use - -go_memstats_heap_idle_bytes -: Number of heap bytes waiting to be used - -go_memstats_heap_inuse_bytes -: Number of heap bytes that are in use - -go_memstats_heap_objects -: Number of allocated objects - -go_memstats_heap_released_bytes -: Number of heap bytes released to OS - -go_memstats_heap_sys_bytes -: Number of heap bytes obtained from system - -go_memstats_last_gc_time_seconds -: Number of seconds since 1970 of last garbage collection - -go_memstats_lookups_total -: Total number of pointer lookups - -go_memstats_mallocs_total -: Total number of mallocs - -go_memstats_mcache_inuse_bytes -: Number of bytes in use by mcache structures - -go_memstats_mcache_sys_bytes -: Number of bytes used for mcache structures obtained from system - -go_memstats_mspan_inuse_bytes -: Number of bytes in use by mspan structures - -go_memstats_mspan_sys_bytes -: Number of bytes used for mspan structures obtained from system - -go_memstats_next_gc_bytes -: Number of heap bytes when next garbage collection will take place - -go_memstats_other_sys_bytes -: Number of bytes used for other system allocations - -go_memstats_stack_inuse_bytes -: Number of bytes in use by the stack allocator - -go_memstats_stack_sys_bytes -: Number of bytes obtained from system for stack allocator - -go_memstats_sys_bytes -: Number of bytes obtained from system - -go_threads -: Number of OS threads created - -promhttp_metric_handler_requests_in_flight -: Current number of scrapes being served - -promhttp_metric_handler_requests_total -: Total number of scrapes by HTTP status code diff --git a/docs/ocis/deployment/_index.md b/docs/ocis/deployment/_index.md index d308ed69f..63730901a 100644 --- a/docs/ocis/deployment/_index.md +++ b/docs/ocis/deployment/_index.md @@ -1,7 +1,7 @@ --- title: "Deployment" date: 2020-10-01T20:35:00+01:00 -weight: -10 +weight: 20 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/ocis/deployment geekdocFilePath: _index.md @@ -10,7 +10,7 @@ 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 [Getting started](https://owncloud.github.io/ocis/getting-started/). +This section handles deployments and operations for admins. If want to just try oCIS you may also follow [Getting started]({{< ref "../getting-started.md" >}}). ### Setup oCIS on your server oCIS deployments are super simple, yet there are many configurations possible for advanced setups. diff --git a/docs/ocis/deployment/bridge.md b/docs/ocis/deployment/bridge.md index 079e3c102..9f276170a 100644 --- a/docs/ocis/deployment/bridge.md +++ b/docs/ocis/deployment/bridge.md @@ -1,6 +1,6 @@ --- title: "Bridge" -date: 2022-02-27T20:35:00+01:00 +date: 2020-02-27T20:35:00+01:00 weight: 30 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/ocis/deployment diff --git a/docs/ocis/development/_index.md b/docs/ocis/development/_index.md index c3fc85927..4baa60168 100644 --- a/docs/ocis/development/_index.md +++ b/docs/ocis/development/_index.md @@ -1,10 +1,8 @@ --- title: "Development" date: 2020-10-01T20:35:00+01:00 -weight: -12 +weight: 10 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: _index.md --- - -{{< toc >}} diff --git a/docs/ocis/development/build-docs.md b/docs/ocis/development/build-docs.md new file mode 100644 index 000000000..b8de161b9 --- /dev/null +++ b/docs/ocis/development/build-docs.md @@ -0,0 +1,20 @@ +--- +title: "Documentation" +date: 2020-07-27T08:39:38+00:00 +weight: 99 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/development +geekdocFilePath: build-docs.md +--- + +{{< toc >}} + +## Build the documentation + +Just run `make -C docs docs-serve` from within the root level of the oCIS git repository. + +## Add changes to the documentation + +Please keep this documentation in sync with the oCIS source code. + +Changes on the documentation are automatically applied to [this site](https://owncloud.github.io) when merged to the master branch. diff --git a/docs/ocis/development/build.md b/docs/ocis/development/build.md new file mode 100644 index 000000000..70f766267 --- /dev/null +++ b/docs/ocis/development/build.md @@ -0,0 +1,48 @@ +--- +title: "Build" +date: 2020-02-27T20:35:00+01:00 +weight: 30 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/development +geekdocFilePath: build.md +--- + +{{< toc >}} + +## Build requirements + +see [Development - Getting Started]({{< relref "getting-started.md/#requirements">}}) + +## Get the sources + +{{< highlight txt >}} +git clone https://github.com/owncloud/ocis.git +cd ocis +{{< / highlight >}} + +## Build the oCIS binary + +The oCIS binary source is in the `ocis` folder inside the oCIS repository. In this folder you can build the oCIS binary: + +{{< highlight txt >}} +make generate +make build +{{< / highlight >}} + +After building you have the binary within the `bin/` folder. Try to run it: `./bin/ocis -h` + +## Build a local oCIS docker image + +If you are developing and want to run your local changes in a docker or docker-compose setup, you have to build an image locally. + +Therefore run following commands in the root of the oCIS repository: + +{{< highlight txt >}} +docker build -t owncloud/ocis:dev . +{{< / highlight >}} + +Then you can test as usual via + +{{< highlight txt >}} +docker run --rm -ti owncloud/ocis:dev +{{< / highlight >}} diff --git a/docs/ocis/development/building-docs.md b/docs/ocis/development/building-docs.md deleted file mode 100644 index adcdbe625..000000000 --- a/docs/ocis/development/building-docs.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Build the documentation" -date: 2020-07-27T08:39:38+00:00 -weight: 99 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/ocis/development -geekdocFilePath: building-docs.md ---- - -## Buildling the documentation - -Following steps can be applied for every oCIS extension repository. - -### Setting up - -- Install [hugo](https://gohugo.io/getting-started/installing/) -- Run `make docs` - -### Viewing the documentation - -To view the rendered docs in the browser run: -```bash -cd hugo -hugo -D server -``` - -Then open "http://localhost:1313/" - -When making changes to the docs, run - -```bash -rsync -ax --delete ../docs/ content/ -``` - -in the hugo folder and the server will pick up the changes and reload the page automatically. - -### Deploying the documentation - -The documentation is automatically deployed from the master branch to https://owncloud.github.io - diff --git a/docs/ocis/development/building.md b/docs/ocis/development/building.md deleted file mode 100644 index 190af94a4..000000000 --- a/docs/ocis/development/building.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "Build ocis" -date: 2020-02-27T20:35:00+01:00 -weight: 30 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/ocis/development -geekdocFilePath: building.md ---- - -## Build requirements - -All required tools besides `go` and `make` are bundled or getting automatically installed within the `GOPATH`. All commands to build this project are part of our `Makefile`. - -The installation of Go is out of the scope of this document, please follow the official documentation for [Go](https://golang.org/doc/install), to build this project you have to install Go >= v1.13. - -## Get the sources - -{{< highlight txt >}} -git clone https://github.com/owncloud/ocis.git -cd ocis -{{< / highlight >}} - -## Build the oCIS binary - -The oCIS binary source is in the ocis/ocis folder. In this folder you can build the ocis binary: - -{{< highlight txt >}} -make generate -make build -{{< / highlight >}} - -Finally, you should have the binary within the `bin/` folder now, give it a try with `./bin/ocis -h` to see all available options. - -## Build a local ocis docker image - -If you are developing on a local branch based on docker / docker-compose setup, here is how to build a new ocis image. In the root folder: - -{{< highlight txt >}} -docker build -t owncloud/ocis:dev . -{{< / highlight >}} - -Then you can test as usual via - -{{< highlight txt >}} -docker run --rm -ti owncloud/ocis:dev -{{< / highlight >}} diff --git a/docs/ocis/development/continuous-integration.md b/docs/ocis/development/continuous-integration.md new file mode 100644 index 000000000..7dc273e73 --- /dev/null +++ b/docs/ocis/development/continuous-integration.md @@ -0,0 +1,56 @@ +--- +title: "Continuous Integration" +date: 2020-10-01T20:35:00+01:00 +weight: 100 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/development +geekdocFilePath: continuous-integration.md +--- + +{{< toc >}} + +oCIS uses [DRONE](https://www.drone.io/) as CI system. You can find the pipeline logs [here](https://drone.owncloud.com/owncloud/ocis) or in your PR. + +## Concepts + +The pipeline is defined in [Starlark](https://github.com/bazelbuild/starlark) and transformed to YAML upon pipeline run. This enables us to do a highly dynamic and non repeating pipeline configuration. + +Upon running the pipeline, your branch gets merged to the master branch. This ensures that we always test your changeset if as it was applied to the master of oCIS. Please note that this does not apply to the pipeline definition (`.drone.star`). + +## Things done in CI + +- static code analysis +- linting +- running UI tests +- running ownCloud 10 test suite against oCIS +- build and release docker images +- build and release binaries +- build and release documentation + +## Flags in commit message and PR title + +You may add flags to your commit message or PR title in order to speed up pipeline runs and take load from the CI runners. + +- `[CI SKIP]`: no ci is run on the commit or PR + +- `[docs-only]`: please add this flag, if you only changed documentation. This will only trigger documentation related CI steps. + +### Knowledge base + +- My pipeline fails because some CI related files or commands are missing. + + Please make sure to rebase your branch onto the lastest master of oCIS. It could be that the pipeline definition (`.drone.star`) was changed on the master branch. This is is the only file, that will not be auto merged to master upon pipeline run. So things could be out of sync. + +- How can I see the YAML drone pipeline definition? + + In order to see the Yaml pipeline definition you can use the drone-cli to convert the Starlark file. + + ``` + drone starlark + ``` + + {{< hint info >}} + If you experience a `"build" struct has no .title attribute` error you need a patched drone-cli binary. + You need to build it yourself from this [source code](https://github.com/micbar/drone-cli/tree/add-more-flags). + (There is also an open [PR](https://github.com/drone/drone-cli/pull/175) for that on drone-cli) + {{< /hint >}} diff --git a/docs/ocis/development/debugging.md b/docs/ocis/development/debugging.md index fa27dbc7c..67c67986a 100644 --- a/docs/ocis/development/debugging.md +++ b/docs/ocis/development/debugging.md @@ -7,6 +7,8 @@ geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: debugging.md --- +{{< toc >}} + ## Debugging As a single binary for easy deployment running `ocis server` just forks itself to start all the services, which makes debugging those processes a little harder. @@ -52,22 +54,23 @@ Then you can set a breakpoint in the service you need and attach to the process ```json { - "version": "0.2.0", - "configurations": [ - { - "name": "ocis attach", - "type": "go", - "request": "attach", - "mode": "local", - "processId": 12897, - } - ] + "version": "0.2.0", + "configurations": [ + { + "name": "ocis attach", + "type": "go", + "request": "attach", + "mode": "local", + "processId": 12897 + } + ] } ``` #### Start all services independently to replace one of them with a debug process 1. You can use this `./ocis.sh` script to start all services independently, so they don't get restrarted by the runtime when you kill them: + ```bash #/bin/sh LOG_LEVEL="debug" @@ -128,7 +131,6 @@ bin/ocis --log-level=$LOG_LEVEL proxy & 3. Kill the service you want to start in debug mode: - ```console # kill 17628 ``` @@ -203,15 +205,16 @@ Debug wherever the call trace leads you to ... good luck! You can either run and manage the services independently, or you can update the `go.mod` file and replace dependencies with your local version. To debug the reva frontend we need to add two replacements: + ``` // use the local ocis-reva repo replace github.com/owncloud/ocis-reva => ../ocis-reva // also use the local reva repo replace github.com/cs3org/reva => ../reva ``` + {{< hint info >}} The username and password only work when basic auth is available. Otherwise you have to obtain a bearer token, eg. by grabbing it from the browser. {{< /hint >}} Rebuild ocis to make sure the dependency is used. It should be sufficient to just restart the service you want to debug. - diff --git a/docs/ocis/extensions.md b/docs/ocis/development/extensions.md similarity index 92% rename from docs/ocis/extensions.md rename to docs/ocis/development/extensions.md index 5406f083d..ad93e37ef 100644 --- a/docs/ocis/extensions.md +++ b/docs/ocis/development/extensions.md @@ -1,9 +1,9 @@ --- -title: "Extension" +title: "Extensions" date: 2020-02-27T20:35:00+01:00 weight: 40 geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/ocis +geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: extensions.md --- @@ -119,11 +119,7 @@ PHOENIX_ASSET_PATH="`pwd`/../phoenix/dist" bin/ocis phoenix ## The ownCloud design system -The owncloud design system contains a set of ownCloud vue components for phoenix or your own ocis extensions. Use it for a consistent look and feel. - -Point your browser to https://owncloud.github.io/owncloud-design-system and check the available components. Live editing the examples in the browser is supported. - -note: There is a bug with navigation sub items: either click a nav item twice or refresh the page +The [ownCloud design system](https://owncloud.design/) contains a set of ownCloud vue components for phoenix or your own ocis extensions. Please use it for a consistent look and feel. ## External phoenix apps diff --git a/docs/ocis/development/getting-started.md b/docs/ocis/development/getting-started.md index b87370d0d..e36207330 100644 --- a/docs/ocis/development/getting-started.md +++ b/docs/ocis/development/getting-started.md @@ -1,5 +1,5 @@ --- -title: "Getting Started with Development" +title: "Getting Started" date: 2020-07-07T20:35:00+01:00 weight: 15 geekdocRepo: https://github.com/owncloud/ocis @@ -9,72 +9,49 @@ geekdocFilePath: getting-started.md {{< toc >}} -## Docker dev environment +## Requirements -### Option 1: Plain docker +We want contribution to oCIS and the creation of extensions to be as easy as possible. +So we are trying to reflect this the used tooling. It should be kept simple and quick to be set up. -To build and run your local ocis code with default storage driver +Besides of standard development tools like git and a text editor, you need following software for development: -``` -docker run --rm -ti --name ocis -v $PWD:/ocis -p 9200:9200 owncloud/eos-ocis-dev -``` +- Go >= v1.13 ([install instructions](https://golang.org/doc/install)) +- Yarn ([install instructions](https://classic.yarnpkg.com/en/docs/install)) +- docker ([install instructions](https://docs.docker.com/get-docker/)) +- docker-compose ([install instructions](https://docs.docker.com/compose/install/)) -The eos-ocis-dev container will build and run oCIS using the ownCloud storage driver and store files in the container at `/var/tmp/reva/data//files` +If you find tools needed besides the mentioned above, please feel free to open an issue or open a PR. -To check the uploaded files start digging with: `docker exec -it ocis ls -l /var/tmp/reva/` +## Repository structure -{{< hint info >}} -On MacOS do not mount a local folder to the `/var/tmp/reva/` path. The fuse driver used by docker [does not support extended attributes](https://docs.docker.com/v18.09/docker-for-mac/osxfs/). See [#182](https://github.com/owncloud/ocis/issues/182) for more details. -{{< /hint >}} +This repository follows the [golang-standard project-layout](https://github.com/golang-standards/project-layout). +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. -### Option 2: Docker compose +Each of the extensions live in a subfolder (eg. `accounts` or `settings`) in this repository, technically creating independant Go modules. -With the `docker-compose.yml` file in ocis repo you can also start ocis via compose: +The `ocis` folder does also contain a Go module but is no extension at all. Instead this module is used to import all extensions and furthermore implement commands to start the extensions. With the resulting oCIS binary you can start single extensions or even all extensions at the same time. -``` -docker-compose up -d ocis -``` +The `docs` folder contains the source for the [oCIS documentation](https://owncloud.github.io/ocis/). -{{< hint info >}} -We are only starting the `ocis` container here. -{{< /hint >}} +The `deployments` folder contains documented deployment configurations and templates. -## Verification +The `scripts` folder contains scripts to perform various build, install, analysis, etc operations. -Check the services are running +## Starting points -``` -$ docker-compose exec ocis ./bin/ocis list -+--------------------------+-----+ -| EXTENSION | PID | -+--------------------------+-----+ -| accounts | 172 | -| api | 204 | -| glauth | 187 | -| graph | 41 | -| graph-explorer | 55 | -| konnectd | 196 | -| ocs | 59 | -| phoenix | 29 | -| proxy | 22 | -| registry | 226 | -| reva-auth-basic | 96 | -| reva-auth-bearer | 104 | -| reva-frontend | 485 | -| reva-gateway | 78 | -| reva-sharing | 286 | -| reva-storage-eos | 129 | -| reva-storage-eos-data | 134 | -| reva-storage-home | 442 | -| reva-storage-home-data | 464 | -| reva-storage-oc | 149 | -| reva-storage-oc-data | 155 | -| reva-storage-public-link | 168 | -| reva-users | 420 | -| settings | 23 | -| thumbnails | 201 | -| web | 218 | -| webdav | 63 | -+--------------------------+-----+ -``` +Depending on what you want do develop there are different starting points. These will be described below. + +### Developing oCIS + +If you want to contribute to oCIS: + +- see [contribution guidelines](https://github.com/owncloud/ocis#contributing) +- make sure the tooling is set up by [building oCIS]({{< relref "build.md" >}}) and [building the docs]({{< relref "build-docs.md" >}}) +- create or pick an [open issue](https://github.com/owncloud/ocis/issues) to develop on +- open a PR and get things done + +### Developing extensions + +If you want to develop an extension, start here: [Extensions]({{< relref "extensions.md">}}) diff --git a/docs/ocis/development/testing.md b/docs/ocis/development/testing.md index 3fb3d2558..ba86f5076 100644 --- a/docs/ocis/development/testing.md +++ b/docs/ocis/development/testing.md @@ -7,6 +7,7 @@ geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: testing.md --- +{{< toc >}} ## Acceptance tests @@ -15,6 +16,7 @@ We are using the ownCloud 10 acceptance test suite against oCIS. To set this up ### Getting the tests All you need to do to get the acceptance tests is check out the core repo: + ``` git clone https://github.com/owncloud/core.git ``` @@ -28,6 +30,7 @@ File versions need a redis server. Start one with docker by using: ### Run ocis To start ocis: + ``` PROXY_ENABLE_BASIC_AUTH=true bin/ocis server ``` @@ -35,6 +38,7 @@ PROXY_ENABLE_BASIC_AUTH=true bin/ocis server `PROXY_ENABLE_BASIC_AUTH` will allow the acceptance tests to make requests against the provisioning api (and other endpoints) using basic auth. ### Run the acceptance tests + First we will need to clone the testing app in owncloud which contains the skeleton files required for running the tests. In the ownCloud 10 core clone the testing app with the following command: @@ -42,7 +46,7 @@ In the ownCloud 10 core clone the testing app with the following command: git clone https://github.com/owncloud/testing apps/testing ``` -Then run the api acceptance tests with the following command from the root of the OCIS repo: +Then run the api acceptance tests with the following command from the root of the oCIS repository: ``` make test-acceptance-api \ TEST_SERVER_URL=https://localhost:9200 \ @@ -87,6 +91,7 @@ If you want to work on a specific issue 2. locally run each of the tests marked with that issue in the expected failures file. E.g.: + ``` make test-acceptance-api \ TEST_SERVER_URL=https://localhost:9200 \ diff --git a/docs/ocis/development/tracing.md b/docs/ocis/development/tracing.md index 7da876677..c07bb6d8e 100644 --- a/docs/ocis/development/tracing.md +++ b/docs/ocis/development/tracing.md @@ -7,41 +7,43 @@ geekdocEditPath: edit/master/docs/ocis/development geekdocFilePath: tracing.md --- +{{< toc >}} + By default, we use [Jaeger](https://www.jaegertracing.io) for request tracing within oCIS. You can follow these steps to get started: 1. Start Jaeger by using the all-in-one docker image: - ```console - docker run -d --name jaeger \ - -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \ - -p 5775:5775/udp \ - -p 6831:6831/udp \ - -p 6832:6832/udp \ - -p 5778:5778 \ - -p 16686:16686 \ - -p 14268:14268 \ - -p 14250:14250 \ - -p 9411:9411 \ - jaegertracing/all-in-one:1.17 - ``` + ```console + docker run -d --name jaeger \ + -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \ + -p 5775:5775/udp \ + -p 6831:6831/udp \ + -p 6832:6832/udp \ + -p 5778:5778 \ + -p 16686:16686 \ + -p 14268:14268 \ + -p 14250:14250 \ + -p 9411:9411 \ + jaegertracing/all-in-one:1.17 + ``` 2. Every single oCIS service has its own environment variables for enabling and configuring tracing. - 1. You can enable and configure tracing on each service individually. For example, enable tracing - in Reva when starting the oCIS single binary like this: - ```console - REVA_TRACING_ENABLED=true \ - REVA_TRACING_ENDPOINT=localhost:6831 \ - REVA_TRACING_COLLECTOR=http://localhost:14268/api/traces \ - ./bin/ocis server - ``` - 2. Enabling and configuring tracing on oCIS itself will forward the configuration to all services: - ```console - OCIS_TRACING_ENABLED=true \ - OCIS_TRACING_ENDPOINT=localhost:6831 \ - OCIS_TRACING_COLLECTOR=http://localhost:14268/api/traces \ - ./bin/ocis server - ``` - If you want to set individual tracing configuration for each service, make sure to set - `OCIS_TRACING_ENABLED=false`. + 1. You can enable and configure tracing on each service individually. For example, enable tracing + in Reva when starting the oCIS single binary like this: + ```console + REVA_TRACING_ENABLED=true \ + REVA_TRACING_ENDPOINT=localhost:6831 \ + REVA_TRACING_COLLECTOR=http://localhost:14268/api/traces \ + ./bin/ocis server + ``` + 2. Enabling and configuring tracing on oCIS itself will forward the configuration to all services: + ```console + OCIS_TRACING_ENABLED=true \ + OCIS_TRACING_ENDPOINT=localhost:6831 \ + OCIS_TRACING_COLLECTOR=http://localhost:14268/api/traces \ + ./bin/ocis server + ``` + If you want to set individual tracing configuration for each service, make sure to set + `OCIS_TRACING_ENABLED=false`. 3. Make the actual request that you want to trace. 4. Open up the [Jaeger UI](http://localhost:16686) to analyze request traces. diff --git a/docs/ocis/flow-docs/_index.md b/docs/ocis/flow-docs/_index.md new file mode 100644 index 000000000..62593da78 --- /dev/null +++ b/docs/ocis/flow-docs/_index.md @@ -0,0 +1,8 @@ +--- +title: "Flow documentation" +date: 2020-10-01T20:35:00+01:00 +weight: 30 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/flow-docs +geekdocFilePath: _index.md +--- diff --git a/docs/ocis/login-flow.md b/docs/ocis/flow-docs/login-flow.md similarity index 99% rename from docs/ocis/login-flow.md rename to docs/ocis/flow-docs/login-flow.md index 9f03c9fd4..81f471d6c 100644 --- a/docs/ocis/login-flow.md +++ b/docs/ocis/flow-docs/login-flow.md @@ -3,7 +3,7 @@ title: "Login Flow" date: 2020-05-04T20:47:00+01:00 weight: 43 geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/ocis +geekdocEditPath: edit/master/docs/ocis/flow-docs geekdocFilePath: login-flow.md --- diff --git a/docs/ocis/public-upload-flow.md b/docs/ocis/flow-docs/public-upload-flow.md similarity index 85% rename from docs/ocis/public-upload-flow.md rename to docs/ocis/flow-docs/public-upload-flow.md index b72e5b033..78adf0c04 100644 --- a/docs/ocis/public-upload-flow.md +++ b/docs/ocis/flow-docs/public-upload-flow.md @@ -3,7 +3,7 @@ title: "Public upload Flow" date: 2020-07-27T14:16:00+01:00 weight: 47 geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/ocis +geekdocEditPath: edit/master/docs/ocis/flow-docs geekdocFilePath: public-upload-flow.md --- diff --git a/docs/ocis/request-flow.md b/docs/ocis/flow-docs/request-flow.md similarity index 98% rename from docs/ocis/request-flow.md rename to docs/ocis/flow-docs/request-flow.md index b219f2cd1..b74fac66e 100644 --- a/docs/ocis/request-flow.md +++ b/docs/ocis/flow-docs/request-flow.md @@ -3,7 +3,7 @@ title: "Request Flow" date: 2020-04-27T16:07:00+01:00 weight: 45 geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/docs/ocis +geekdocEditPath: edit/master/docs/ocis/flow-docs geekdocFilePath: request-flow.md --- diff --git a/docs/ocis/getting-started.md b/docs/ocis/getting-started.md index 6b01901d6..0c2af1dd6 100644 --- a/docs/ocis/getting-started.md +++ b/docs/ocis/getting-started.md @@ -1,7 +1,7 @@ --- title: "Getting Started" date: 2020-02-27T20:35:00+01:00 -weight: -15 +weight: 0 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/docs/ocis geekdocFilePath: getting-started.md @@ -47,7 +47,7 @@ docker run --rm -ti -p 9200:9200 owncloud/ocis ### Login to oCIS Web -Open https://localhost:9200 and login using one of the demo accounts: +Open [https://localhost:9200](https://localhost:9200) and login using one of the demo accounts: ```console einstein:relativity @@ -61,11 +61,9 @@ moss:vista admin:admin ``` -### Basic Commands +### Basic Management Commands -The program provides a few sub-commands on execution. The available configuration methods have already been mentioned above. Generally you can always see a formatted help output if you execute the binary via `ocis --help`. - -The server command is used to start the http and debug server on two addresses within a single process. The http server is serving the general web service while the debug server is used for health check, readiness check and to server the metrics mentioned below. +The oCIS single binary contains multiple extensions and the `ocis` command helps you to manage them. You already used `ocis server` to run all available extensions in the [Run oCIS]({{< relref "#run-ocis" >}}) section. We now will show you some more management commands, which you may also explore by typing `ocis --help` or going to the [docs]({{< relref "configuration.md" >}}). To start oCIS server: @@ -73,7 +71,7 @@ To start oCIS server: ocis server {{< / highlight >}} -The list command prints all running oCIS services. +The list command prints all running oCIS extensions. {{< highlight txt >}} ocis list {{< / highlight >}} diff --git a/docs/ocis/storage-backends/_index.md b/docs/ocis/storage-backends/_index.md new file mode 100644 index 000000000..08bcd434f --- /dev/null +++ b/docs/ocis/storage-backends/_index.md @@ -0,0 +1,8 @@ +--- +title: "Storage backends" +date: 2020-02-27T20:35:00+01:00 +weight: 40 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/storage-backends +geekdocFilePath: _index.md +--- diff --git a/docs/ocis/eos.md b/docs/ocis/storage-backends/eos.md similarity index 100% rename from docs/ocis/eos.md rename to docs/ocis/storage-backends/eos.md diff --git a/glauth/templates/CONFIGURATION.tmpl b/glauth/templates/CONFIGURATION.tmpl index 7b939478d..e46dd9a74 100644 --- a/glauth/templates/CONFIGURATION.tmpl +++ b/glauth/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/ocis_glauth/configuration) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/konnectd/templates/CONFIGURATION.tmpl b/konnectd/templates/CONFIGURATION.tmpl index 928157c35..fd3928db0 100644 --- a/konnectd/templates/CONFIGURATION.tmpl +++ b/konnectd/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/ocis_konnectd/configuration) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/ocis-phoenix/templates/CONFIGURATION.tmpl b/ocis-phoenix/templates/CONFIGURATION.tmpl index 7ae23b1c0..566dfce13 100644 --- a/ocis-phoenix/templates/CONFIGURATION.tmpl +++ b/ocis-phoenix/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/ocis_phoenix/configuration) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/ocis/docker/eos-ocis-dev/README.md b/ocis/docker/eos-ocis-dev/README.md index a2e6e9f7a..2a588bfb5 100644 --- a/ocis/docker/eos-ocis-dev/README.md +++ b/ocis/docker/eos-ocis-dev/README.md @@ -2,6 +2,10 @@ Image is based on [owncloud/eos-base](https://hub.docker.com/r/owncloud/eos-base) from [eos-stack](https://github.com/owncloud-docker/eos-stack) +{{< hint info >}} +On MacOS do not mount a local folder to the `/var/tmp/reva/` path. The fuse driver used by docker [does not support extended attributes](https://docs.docker.com/v18.09/docker-for-mac/osxfs/). See [#182](https://github.com/owncloud/ocis/issues/182) for more details. +{{< /hint >}} + ## Build ```shell docker build -t owncloud/eos-ocis-dev:latest . diff --git a/ocis/templates/CONFIGURATION.tmpl b/ocis/templates/CONFIGURATION.tmpl index 55b2249ed..71cd95483 100644 --- a/ocis/templates/CONFIGURATION.tmpl +++ b/ocis/templates/CONFIGURATION.tmpl @@ -1,7 +1,7 @@ --- title: "Configuration" date: "{{ date "2006-01-02T15:04:05-0700" now }}" -weight: 20 +weight: 2 geekdocRepo: https://github.com/owncloud/ocis geekdocEditPath: edit/master/ocis/templates geekdocFilePath: CONFIGURATION.tmpl @@ -25,7 +25,7 @@ geekdocFilePath: CONFIGURATION.tmpl oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/proxy/configuration/) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. +Each extension has its dedicated documentation page (e.g. [proxy configuration]({{"{{"}}< relref "../extensions/accounts/configuration.md" >{{"}}"}})) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. ### Configuration using config files diff --git a/ocs/templates/CONFIGURATION.tmpl b/ocs/templates/CONFIGURATION.tmpl index 5c190dbe1..614ed317e 100644 --- a/ocs/templates/CONFIGURATION.tmpl +++ b/ocs/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/ocis_ocs/configuration) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/proxy/templates/CONFIGURATION.tmpl b/proxy/templates/CONFIGURATION.tmpl index bedf5af16..c18cf7e7b 100644 --- a/proxy/templates/CONFIGURATION.tmpl +++ b/proxy/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/proxy/configuration/) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/settings/templates/CONFIGURATION.tmpl b/settings/templates/CONFIGURATION.tmpl index 1e24058bf..d0379013f 100644 --- a/settings/templates/CONFIGURATION.tmpl +++ b/settings/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/proxy/configuration/) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/storage/templates/CONFIGURATION.tmpl b/storage/templates/CONFIGURATION.tmpl index 096c42cfe..78b5b5ac3 100644 --- a/storage/templates/CONFIGURATION.tmpl +++ b/storage/templates/CONFIGURATION.tmpl @@ -36,10 +36,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/proxy/configuration/) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/store/templates/CONFIGURATION.tmpl b/store/templates/CONFIGURATION.tmpl index 6b6ec0bf7..a5b5d071c 100644 --- a/store/templates/CONFIGURATION.tmpl +++ b/store/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/proxy/configuration/) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/thumbnails/templates/CONFIGURATION.tmpl b/thumbnails/templates/CONFIGURATION.tmpl index e45aa1ad5..1c92e4ca5 100644 --- a/thumbnails/templates/CONFIGURATION.tmpl +++ b/thumbnails/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/proxy/configuration/) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: diff --git a/webdav/templates/CONFIGURATION.tmpl b/webdav/templates/CONFIGURATION.tmpl index 559344f67..d746231ce 100644 --- a/webdav/templates/CONFIGURATION.tmpl +++ b/webdav/templates/CONFIGURATION.tmpl @@ -23,10 +23,6 @@ geekdocFilePath: CONFIGURATION.tmpl ## Configuration -oCIS Single Binary is not responsible for configuring extensions. Instead, each extension could either be configured by environment variables, cli flags or config files. - -Each extension has its dedicated documentation page (e.g. https://owncloud.github.io/extensions/proxy/configuration/) which lists all possible configurations. Config files and environment variables are picked up if you use the `./bin/ocis server` command within the oCIS single binary. Command line flags must be set explicitly on the extensions subcommands. - ### Configuration using config files Out of the box extensions will attempt to read configuration details from: