add generate docs steps and update webdav docs

This commit is contained in:
Michael Barz
2020-10-01 11:55:02 +02:00
parent 456ba52d05
commit e53e57eb3f
21 changed files with 340 additions and 609 deletions
+1 -16
View File
@@ -1,6 +1,6 @@
---
title: "Configuration"
date: "2020-09-30T17:30:16+0200"
date: "2020-09-21T13:14:47+0200"
weight: 20
geekdocRepo: https://github.com/owncloud/ocis-konnectd
geekdocEditPath: edit/master/docs
@@ -108,9 +108,6 @@ Usage: `ocis-konnectd server [command options] [arguments...]`
--http-namespace | $KONNECTD_HTTP_NAMESPACE
: Set the base namespace for service discovery. Default: `com.owncloud.web`.
--name | $KONNECTD_NAME
: Service name. Default: `konnectd`.
--identity-manager | $KONNECTD_IDENTITY_MANAGER
: Identity manager (one of ldap,kc,cookie,dummy). Default: `ldap`.
@@ -177,15 +174,3 @@ Usage: `ocis-konnectd server [command options] [arguments...]`
--disable-identifier-webapp | $KONNECTD_DISABLE_IDENTIFIER_WEBAPP
: Disable built-in identifier-webapp to use a frontend hosted elsewhere.. Default: `true`.
### ocis-konnectd version
Print the versions of the running instances
Usage: `ocis-konnectd version [command options] [arguments...]`
--http-namespace | $KONNECTD_HTTP_NAMESPACE
: Set the base namespace for service discovery. Default: `com.owncloud.web`.
--name | $KONNECTD_NAME
: Service name. Default: `konnectd`.
+10
View File
@@ -0,0 +1,10 @@
---
title: WebDaV
date: 2018-05-02T00:00:00+00:00
weight: 10
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/extensions/webdav
geekdocFilePath: _index.md
---
This service provides the WebDAV API which is required by some ownCloud clients.
+28
View File
@@ -0,0 +1,28 @@
---
title: "Building"
date: 2018-05-02T00:00:00+00:00
weight: 30
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/extensions/webdav
geekdocFilePath: building.md
---
{{< toc >}}
As this project is built with Go, so you need to install that first. 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.12. After the installation of the required tools you need to get the sources:
{{< highlight txt >}}
git clone https://github.com/owncloud/ocis-webdav.git
cd ocis-webdav
{{< / highlight >}}
All required tool besides Go itself and make are bundled or getting automatically installed within the `GOPATH`. All commands to build this project are part of our `Makefile`.
### Backend
{{< 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-webdav -h` to see all available options.
+125
View File
@@ -0,0 +1,125 @@
---
title: "Configuration"
date: "2020-09-30T22:51:03+0200"
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/extensions/webdav
geekdocFilePath: configuration.md
---
{{< toc >}}
## 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_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:
```console
/etc/ocis
$HOME/.ocis
./config
```
For this configuration to be picked up, have a look at your extension `root` command and look for which default config name it has assigned. *i.e: ocis-proxy reads `proxy.json | yaml | toml ...`*.
So far we support the file formats `JSON` and `YAML`, if you want to get a full example configuration just take a look at [our repository](https://github.com/owncloud/ocis/tree/master/config), there you can always see the latest configuration format. These example configurations include all available options and the default values. The configuration file will be automatically loaded if it's placed at `/etc/ocis/ocis.yml`, `${HOME}/.ocis/ocis.yml` or `$(pwd)/config/ocis.yml`.
### Envrionment variables
If you prefer to configure the service with environment variables you can see the available variables below.
### Commandline flags
If you prefer to configure the service with commandline flags you can see the available variables below. Command line flags are only working when calling the subcommand directly.
## Root Command
Serve WebDAV API for oCIS
Usage: `webdav [global options] command [command options] [arguments...]`
--config-file | $WEBDAV_CONFIG_FILE
: Path to config file.
--log-level | $WEBDAV_LOG_LEVEL
: Set logging level. Default: `info`.
--log-pretty | $WEBDAV_LOG_PRETTY
: Enable pretty logging. Default: `true`.
--log-color | $WEBDAV_LOG_COLOR
: Enable colored logging. Default: `true`.
## Sub Commands
### webdav health
Check health status
Usage: `webdav health [command options] [arguments...]`
--debug-addr | $WEBDAV_DEBUG_ADDR
: Address to debug endpoint. Default: `0.0.0.0:9119`.
### webdav server
Start integrated server
Usage: `webdav server [command options] [arguments...]`
--tracing-enabled | $WEBDAV_TRACING_ENABLED
: Enable sending traces.
--tracing-type | $WEBDAV_TRACING_TYPE
: Tracing backend type. Default: `jaeger`.
--tracing-endpoint | $WEBDAV_TRACING_ENDPOINT
: Endpoint for the agent.
--tracing-collector | $WEBDAV_TRACING_COLLECTOR
: Endpoint for the collector.
--tracing-service | $WEBDAV_TRACING_SERVICE
: Service name for tracing. Default: `webdav`.
--debug-addr | $WEBDAV_DEBUG_ADDR
: Address to bind debug server. Default: `0.0.0.0:9119`.
--debug-token | $WEBDAV_DEBUG_TOKEN
: Token to grant metrics access.
--debug-pprof | $WEBDAV_DEBUG_PPROF
: Enable pprof debugging.
--debug-zpages | $WEBDAV_DEBUG_ZPAGES
: Enable zpages debugging.
--http-addr | $WEBDAV_HTTP_ADDR
: Address to bind http server. Default: `0.0.0.0:9115`.
--http-namespace | $WEBDAV_HTTP_NAMESPACE
: Set the base namespace for service discovery. Default: `com.owncloud.web`.
--service-name | $WEBDAV_SERVICE_NAME
: Service name. Default: `webdav`.
--http-root | $WEBDAV_HTTP_ROOT
: Root path of http server. Default: `/`.
### webdav version
Print the versions of the running instances
Usage: `webdav version [command options] [arguments...]`
--http-namespace | $WEBDAV_HTTP_NAMESPACE
: Set the base namespace for service discovery. Default: `com.owncloud.web`.
--service-name | $WEBDAV_SERVICE_NAME
: Service name. Default: `webdav`.
+269
View File
@@ -0,0 +1,269 @@
---
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.
#### Envrionment 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 >}}
ocis-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 >}}
ocis-webdav 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 `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
+90 -90
View File
@@ -1,6 +1,6 @@
---
title: "Configuration"
date: "2020-09-30T17:35:29+0200"
date: "2020-09-21T13:14:56+0200"
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs
@@ -57,6 +57,15 @@ Usage: `ocis [global options] command [command options] [arguments...]`
## Sub Commands
### ocis health
Check health status
Usage: `ocis health [command options] [arguments...]`
--debug-addr | $OCIS_DEBUG_ADDR
: Address to debug endpoint. Default: `0.0.0.0:9010`.
### ocis server
Start fullstack server
@@ -99,114 +108,69 @@ Usage: `ocis server [command options] [arguments...]`
--grpc-addr | $OCIS_GRPC_ADDR
: Address to bind grpc server. Default: `0.0.0.0:9001`.
### ocis health
Check health status
Usage: `ocis health [command options] [arguments...]`
--debug-addr | $OCIS_DEBUG_ADDR
: Address to debug endpoint. Default: `0.0.0.0:9010`.
### List of available Extension subcommands
There are more subcommands to start the individual extensions. Please check the documentation about their usage and options in the dedicated section of the documentation.
#### ocis list
Lists running ocis extensions
#### ocis phoenix
Start phoenix server
#### ocis reva-gateway
Start reva gateway
#### ocis reva-storage-public-link
Start reva public link storage
#### ocis kill
Kill an extension by name
#### ocis ocs
Start ocs server
#### ocis reva-frontend
Start reva frontend
#### ocis reva-storage-eos-data
Start reva storage data provider for eos mount
#### ocis glauth
Start glauth server
#### ocis reva-storage-eos
Start reva storage service for eos mount
#### ocis reva-users
Start reva users service
#### ocis konnectd
Start konnectd server
#### ocis reva-storage-home-data
Start reva storage data provider for home mount
#### ocis reva-storage-root
Start reva root storage
#### ocis run
Runs an extension
#### ocis settings
Start settings server
#### ocis thumbnails
Start thumbnails server
#### ocis webdav
Start webdav server
#### ocis reva-auth-basic
Start reva auth-basic service
#### ocis accounts
Start accounts server
#### ocis proxy
Start proxy server
#### ocis store
Start a go-micro store
#### ocis glauth
Start glauth server
#### ocis ocs
Start ocs server
#### ocis reva-storage-eos-data
Start reva storage data provider for eos mount
#### ocis reva-storage-home-data
Start reva storage data provider for home mount
#### ocis kill
Kill an extension by name
#### ocis proxy
Start proxy server
#### ocis reva-auth-bearer
Start reva auth-bearer service
#### ocis reva-sharing
#### ocis reva-storage-oc-data
Start reva sharing service
Start reva storage data provider for oc mount
#### ocis settings
Start settings server
#### ocis accounts
Start accounts server
#### ocis phoenix
Start phoenix server
#### ocis reva-storage-eos
Start reva storage service for eos mount
#### ocis reva-storage-home
@@ -216,7 +180,43 @@ Start reva storage service for home mount
Start reva storage service for oc mount
#### ocis reva-storage-oc-data
#### ocis reva-storage-root
Start reva storage data provider for oc mount
Start reva root storage
#### ocis reva-gateway
Start reva gateway
#### ocis reva-sharing
Start reva sharing service
#### ocis reva-users
Start reva users service
#### ocis list
Lists running ocis extensions
#### ocis reva-auth-basic
Start reva auth-basic service
#### ocis reva-frontend
Start reva frontend
#### ocis reva-storage-public-link
Start reva public link storage
#### ocis thumbnails
Start thumbnails server
#### ocis webdav
Start webdav server