mirror/opencloud
1
0
Fork 0
mirror of https://github.com/opencloud-eu/opencloud.git synced 2026-01-07 12:50:21 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into fix-simple

Browse Source
This commit is contained in:
Alex Unger
2020-04-17 08:49:27 +02:00
committed by GitHub
parent f584d12934 a139cccecd
commit f099fbd2ae
24 changed files with 1348 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files

282
docs/configuration.md
View File

@@ -1,6 +1,6 @@
---
title: "Configuration"
date: 2020-02-27T20:35:00+01:00
date: "2020-04-14T22:00:52+0200"
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs
@@ -13,6 +13,8 @@ geekdocFilePath: configuration.md
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:
@@ -25,254 +27,172 @@ $HOME/.ocis
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.
#### Global
OCIS_CONFIG_FILE
: Path to config file
OCIS_LOG_LEVEL
: Set logging level, defaults to `info`
OCIS_LOG_COLOR
: Enable colored logging, defaults to `true`
OCIS_LOG_PRETTY
: Enable pretty logging, defaults to `true`
#### Server
OCIS_TRACING_ENABLED
: Enable sending traces
OCIS_TRACING_TYPE
: Tracing backend type,
OCIS_TRACING_ENDPOINT
:Endpoint for the agent
OCIS_TRACING_COLLECTOR
: Endpoint for the collector
OCIS_TRACING_SERVICE
: Service name for tracing"
OCIS_DEBUG_ADDR
: Address to bind debug server, defaults to `0.0.0.0:9010`
OCIS_DEBUG_TOKEN
: Token to grant metrics access, empty default value
OCIS_DEBUG_PPROF
: Enable pprof debugging, defaults to `false`
OCIS_DEBUG_ZPAGES
: Enable zpages debugging, defaults to `false`
OCIS_HTTP_ADDR
: Address to bind http server, defaults to `0.0.0.0:9000`
OCIS_HTTP_ROOT
: Root path for http endpoint, defaults to `/`
OCIS_GRPC_ADDR
: Address to bind grpc server, defaults to `0.0.0.0:9001`
OCIS_SERVICES_ENABLED
: List of enabled services, defaults to `phoenix,konnectd,graph,ocs,webdav,hello`
#### Health
OCIS_DEBUG_ADDR
: Address to debug endpoint, defaults to `0.0.0.0:9010`
### Commandline flags
If you prefer to configure the service with commandline flags you can see the available variables below.
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.
#### Global
## Root Command
--config-file
: Path to config file
ownCloud Infinite Scale Stack
--log-level
: Set logging level, defaults to `info`
Usage: `ocis [global options] command [command options] [arguments...]`
--log-color
: Enable colored logging, defaults to `true`
--config-file | $OCIS_CONFIG_FILE
: Path to config file.
--log-pretty
: Enable pretty logging, defaults to `true`
--log-level | $OCIS_LOG_LEVEL
: Set logging level. Default: `info`.
#### Server
--log-pretty | $OCIS_LOG_PRETTY
: Enable pretty logging. Default: `true`.
--tracing-enabled
: Enable sending traces
--log-color | $OCIS_LOG_COLOR
: Enable colored logging. Default: `true`.
--tracing-type
: Tracing backend type,
## Sub Commands
--tracing-endpoint
:Endpoint for the agent
### ocis health
--tracing-collector
: Endpoint for the collector
Check health status
--tracing-service
: Service name for tracing"
Usage: `ocis health [command options] [arguments...]`
--debug-addr
: Address to bind debug server, defaults to `0.0.0.0:9010`
--debug-addr | $OCIS_DEBUG_ADDR
: Address to debug endpoint. Default: `0.0.0.0:9010`.
--debug-token
: Token to grant metrics access, empty default value
### ocis server
--debug-pprof
: Enable pprof debugging, defaults to `false`
Start fullstack server
--debug-zpages
: Enable zpages debugging, defaults to `false`
Usage: `ocis server [command options] [arguments...]`
--http-addr
: Address to bind http server, defaults to `0.0.0.0:9000`
--tracing-enabled | $OCIS_TRACING_ENABLED
: Enable sending traces.
--http-root
: Root path for http endpoint, defaults to `/`
--tracing-type | $OCIS_TRACING_TYPE
: Tracing backend type. Default: `jaeger`.
--grpc-addr
: Address to bind grpc server, defaults to `0.0.0.0:9001`
--tracing-endpoint | $OCIS_TRACING_ENDPOINT
: Endpoint for the agent.
--services-enabled
: List of enabled services, defaults to `hello,phoenix,graph,graph-explorer,ocs,webdav,reva-frontend,reva-gateway,reva-users,reva-auth-basic,reva-auth-bearer,reva-sharing,reva-storage-root,reva-storage-home,reva-storage-home-data,reva-storage-oc,reva-storage-oc-data,devldap`
--tracing-collector | $OCIS_TRACING_COLLECTOR
: Endpoint for the collector.
#### Health
--tracing-service | $OCIS_TRACING_SERVICE
: Service name for tracing. Default: `ocis`.
--debug-addr
: Address to debug endpoint, defaults to `0.0.0.0:9010`
--debug-addr | $OCIS_DEBUG_ADDR
: Address to bind debug server. Default: `0.0.0.0:9010`.
### Configuration file
--debug-token | $OCIS_DEBUG_TOKEN
: Token to grant metrics access.
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`.
--debug-pprof | $OCIS_DEBUG_PPROF
: Enable pprof debugging.
## Usage
--debug-zpages | $OCIS_DEBUG_ZPAGES
: Enable zpages debugging.
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 --help`.
--http-addr | $OCIS_HTTP_ADDR
: Address to bind http server. Default: `0.0.0.0:9000`.
### Server
--http-root | $OCIS_HTTP_ROOT
: Root path of http server. Default: `/`.
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:
--grpc-addr | $OCIS_GRPC_ADDR
: Address to bind grpc server. Default: `0.0.0.0:9001`.
{{< highlight txt >}}
ocis server --help
{{< / highlight >}}
### List of available Extension subcommands
### Health
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.
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.
#### ocis proxy
{{< highlight txt >}}
ocis health --help
{{< / highlight >}}
Start proxy server
## Metrics
#### ocis reva-storage-oc-data
This service provides some [Prometheus](https://prometheus.io/) metrics through the debug endpoint, you can optionally secure the metrics endpoint by some random token, which got to be configured through one of the flag `--debug-token` or the environment variable `OCIS_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:8001/metrics`.
Start reva oc storage dataprovider
go_gc_duration_seconds
: A summary of the GC invocation durations
#### ocis reva-auth-bearer
go_gc_duration_seconds_sum
: A summary of the GC invocation durations
Start reva auth-bearer service
go_gc_duration_seconds_count
: A summary of the GC invocation durations
#### ocis webdav
go_goroutines
: Number of goroutines that currently exist
Start webdav server
go_info
: Information about the Go environment
#### ocis reva-sharing
go_memstats_alloc_bytes
: Number of bytes allocated and still in use
Start reva sharing service
go_memstats_alloc_bytes_total
: Total number of bytes allocated, even if freed
#### ocis reva-gateway
go_memstats_buck_hash_sys_bytes
: Number of bytes used by the profiling bucket hash table
Start reva gateway
go_memstats_frees_total
: Total number of frees
#### ocis graph-explorer
go_memstats_gc_cpu_fraction
: The fraction of this program's available CPU time used by the GC since the program started
Start graph explorer
go_memstats_gc_sys_bytes
: Number of bytes used for garbage collection system metadata
#### ocis reva-auth-basic
go_memstats_heap_alloc_bytes
: Number of heap bytes allocated and still in use
Start reva auth-basic service
go_memstats_heap_idle_bytes
: Number of heap bytes waiting to be used
#### ocis hello
go_memstats_heap_inuse_bytes
: Number of heap bytes that are in use
Start hello server
go_memstats_heap_objects
: Number of allocated objects
#### ocis reva-storage-home
go_memstats_heap_released_bytes
: Number of heap bytes released to OS
Start reva home storage
go_memstats_heap_sys_bytes
: Number of heap bytes obtained from system
#### ocis reva-storage-oc
go_memstats_last_gc_time_seconds
: Number of seconds since 1970 of last garbage collection
Start reva oc storage
go_memstats_lookups_total
: Total number of pointer lookups
#### ocis reva-frontend
go_memstats_mallocs_total
: Total number of mallocs
Start reva frontend
go_memstats_mcache_inuse_bytes
: Number of bytes in use by mcache structures
#### ocis reva-storage-home-data
go_memstats_mcache_sys_bytes
: Number of bytes used for mcache structures obtained from system
Start reva home storage dataprovider
go_memstats_mspan_inuse_bytes
: Number of bytes in use by mspan structures
#### ocis graph
go_memstats_mspan_sys_bytes
: Number of bytes used for mspan structures obtained from system
Start graph server
go_memstats_next_gc_bytes
: Number of heap bytes when next garbage collection will take place
#### ocis konnectd
go_memstats_other_sys_bytes
: Number of bytes used for other system allocations
Start konnectd server
go_memstats_stack_inuse_bytes
: Number of bytes in use by the stack allocator
#### ocis thumbnails
go_memstats_stack_sys_bytes
: Number of bytes obtained from system for stack allocator
Start thumbnails server
go_memstats_sys_bytes
: Number of bytes obtained from system
#### ocis glauth
go_threads
: Number of OS threads created
Start glauth server
promhttp_metric_handler_requests_in_flight
: Current number of scrapes being served
#### ocis phoenix
Start phoenix server
#### ocis ocs
Start ocs server
#### ocis reva-users
Start reva users service
#### ocis reva-storage-root
Start reva root storage
promhttp_metric_handler_requests_total
: Total number of scrapes by HTTP status code

217
docs/debugging.md Normal file
View File

@@ -0,0 +1,217 @@
---
title: "Debugging"
date: 2020-03-19T08:21:00+01:00
weight: 50
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs
geekdocFilePath: debugging.md
---
## 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.
Ultimately, we want to be able to stop a single service using eg. `ocis kill phoenix` so that you can start the service you want to debug in debug mode. We need to [change the way we fork processes](https://github.com/owncloud/ocis/issues/77) though, otherwise the runtime will automatically restart a service if killed.
### Start ocis
For debugging there are two workflows that work well, depending on your preferences.
#### Use the debug binary and attach to the process as needed
Run the debug binary with `OCIS_LOG_LEVEL=debug bin/ocis-debug server` and then find the service you want to debug using:
```console
# ps ax | grep ocis
12837 pts/1 Sl+ 0:00 bin/ocis-debug server
12845 pts/1 Sl 0:00 bin/ocis-debug graph
12847 pts/1 Sl 0:00 bin/ocis-debug reva-auth-bearer
12848 pts/1 Sl 0:00 bin/ocis-debug graph-explorer
12849 pts/1 Sl 0:00 bin/ocis-debug ocs
12850 pts/1 Sl 0:00 bin/ocis-debug reva-storage-oc-data
12863 pts/1 Sl 0:00 bin/ocis-debug webdav
12874 pts/1 Sl 0:00 bin/ocis-debug reva-frontend
12897 pts/1 Sl 0:00 bin/ocis-debug reva-sharing
12905 pts/1 Sl 0:00 bin/ocis-debug reva-gateway
12912 pts/1 Sl 0:00 bin/ocis-debug reva-storage-home
12920 pts/1 Sl 0:00 bin/ocis-debug reva-users
12929 pts/1 Sl 0:00 bin/ocis-debug glauth
12940 pts/1 Sl 0:00 bin/ocis-debug reva-storage-home-data
12948 pts/1 Sl 0:00 bin/ocis-debug konnectd
12952 pts/1 Sl 0:00 bin/ocis-debug proxy
12961 pts/1 Sl 0:00 bin/ocis-debug thumbnails
12971 pts/1 Sl 0:00 bin/ocis-debug reva-storage-oc
12981 pts/1 Sl 0:00 bin/ocis-debug web
12993 pts/1 Sl 0:00 bin/ocis-debug api
12998 pts/1 Sl 0:00 bin/ocis-debug registry
13004 pts/1 Sl 0:00 bin/ocis-debug phoenix
13015 pts/1 Sl 0:00 bin/ocis-debug reva-auth-basic
```
Then you can set a breakpoint in the service you need and attach to the process via processid. To debug the `reva-sharing` service the VS Code `launch.json` would look like this:
```json
{
"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"
bin/ocis --log-level=$LOG_LEVEL micro &
bin/ocis --log-level=$LOG_LEVEL glauth &
bin/ocis --log-level=$LOG_LEVEL graph-explorer &
bin/ocis --log-level=$LOG_LEVEL graph &
#bin/ocis --log-level=$LOG_LEVEL hello &
bin/ocis --log-level=$LOG_LEVEL konnectd &
#bin/ocis --log-level=$LOG_LEVEL ocs &
bin/ocis --log-level=$LOG_LEVEL phoenix &
bin/ocis --log-level=$LOG_LEVEL reva-auth-basic &
bin/ocis --log-level=$LOG_LEVEL reva-auth-bearer &
bin/ocis --log-level=$LOG_LEVEL reva-frontend &
bin/ocis --log-level=$LOG_LEVEL reva-gateway &
bin/ocis --log-level=$LOG_LEVEL reva-sharing &
bin/ocis --log-level=$LOG_LEVEL reva-storage-home &
bin/ocis --log-level=$LOG_LEVEL reva-storage-home-data &
bin/ocis --log-level=$LOG_LEVEL reva-storage-oc &
bin/ocis --log-level=$LOG_LEVEL reva-storage-oc-data &
bin/ocis --log-level=$LOG_LEVEL reva-storage-root &
bin/ocis --log-level=$LOG_LEVEL reva-users &
#bin/ocis --log-level=$LOG_LEVEL webdav
bin/ocis --log-level=$LOG_LEVEL proxy &
```
2. Get the list of running processes:
```console
# ps ax | grep ocis
12837 pts/1 Sl+ 0:00 bin/ocis-debug server
12845 pts/1 Sl 0:00 bin/ocis-debug graph
12847 pts/1 Sl 0:00 bin/ocis-debug reva-auth-bearer
12848 pts/1 Sl 0:00 bin/ocis-debug graph-explorer
12849 pts/1 Sl 0:00 bin/ocis-debug ocs
12850 pts/1 Sl 0:00 bin/ocis-debug reva-storage-oc-data
12863 pts/1 Sl 0:00 bin/ocis-debug webdav
12874 pts/1 Sl 0:00 bin/ocis-debug reva-frontend
12897 pts/1 Sl 0:00 bin/ocis-debug reva-sharing
12905 pts/1 Sl 0:00 bin/ocis-debug reva-gateway
12912 pts/1 Sl 0:00 bin/ocis-debug reva-storage-home
12920 pts/1 Sl 0:00 bin/ocis-debug reva-users
12929 pts/1 Sl 0:00 bin/ocis-debug glauth
12940 pts/1 Sl 0:00 bin/ocis-debug reva-storage-home-data
12948 pts/1 Sl 0:00 bin/ocis-debug konnectd
12952 pts/1 Sl 0:00 bin/ocis-debug proxy
12961 pts/1 Sl 0:00 bin/ocis-debug thumbnails
12971 pts/1 Sl 0:00 bin/ocis-debug reva-storage-oc
12981 pts/1 Sl 0:00 bin/ocis-debug web
12993 pts/1 Sl 0:00 bin/ocis-debug api
12998 pts/1 Sl 0:00 bin/ocis-debug registry
13004 pts/1 Sl 0:00 bin/ocis-debug phoenix
13015 pts/1 Sl 0:00 bin/ocis-debug reva-auth-basic
```
3. Kill the service you want to start in debug mode:
```console
# kill 17628
```
4. Start the service you are interested in in debug mode. When using make to build the binary there is already a `bin/ocis-debug` binary for you. When running an IDE tell it which service to start by providing the corresponding sub command, eg. `bin\ocis-debug reva-frontend`.
### Gather error messages
We recommend you collect all related information in a single file or in a github issue. Let us start with an error that pops up in the Web UI:
> Error while sharing.
> error sending a grpc stat request
This popped up when I tried to add `marie` as a collaborator in phoenix. That triggers a request to the server which I copied as curl. We can strip a lot of headers and the gist of it is:
```console
# curl 'https://localhost:9200/ocs/v1.php/apps/files_sharing/api/v1/shares' -d 'shareType=0&shareWith=marie&path=%2FNeuer+Ordner&permissions=1' -u einstein:relativity -k -v | xmllint -format -
[... headers ...]
<?xml version="1.0" encoding="UTF-8"?>
<ocs>
<meta>
<status>error</status>
<statuscode>998</statuscode>
<message>error sending a grpc stat request</message>
</meta>
</ocs>
```
{{< 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 >}}
{{< hint danger >}}
TODO add ocis cli tool to obtain a bearer token.
{{< /hint >}}
We also have a few interesting log entries:
```
0:43PM INF home/jfd/go/pkg/mod/github.com/cs3org/reva@v0.0.2-0.20200318111623-a2f97d4aa741/internal/grpc/interceptors/log/log.go:69 > unary code=OK end="18/Mar/2020:22:43:40 +0100" from=tcp://[::1]:44078 pid=17836 pkg=rgrpc start="18/Mar/2020:22:43:40 +0100" time_ns=95841 traceid=b4eb9a9f45921f7d3632523ca32a42b0 uri=/cs3.storage.registry.v1beta1.RegistryAPI/GetStorageProvider user-agent=grpc-go/1.26.0
10:43PM ERR home/jfd/go/pkg/mod/github.com/cs3org/reva@v0.0.2-0.20200318111623-a2f97d4aa741/internal/grpc/interceptors/log/log.go:69 > unary code=Unknown end="18/Mar/2020:22:43:40 +0100" from=tcp://[::1]:43910 pid=17836 pkg=rgrpc start="18/Mar/2020:22:43:40 +0100" time_ns=586115 traceid=b4eb9a9f45921f7d3632523ca32a42b0 uri=/cs3.gateway.v1beta1.GatewayAPI/Stat user-agent=grpc-go/1.26.0
10:43PM ERR home/jfd/go/pkg/mod/github.com/cs3org/reva@v0.0.2-0.20200318111623-a2f97d4aa741/internal/http/services/owncloud/ocs/reqres.go:94 > error sending a grpc stat request error="rpc error: code = Unknown desc = gateway: error calling Stat: rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing dial tcp [::1]:9152: connect: connection refused\"" pid=17832 pkg=rhttp traceid=b4eb9a9f45921f7d3632523ca32a42b0
```
{{< hint danger >}}
TODO return the trace id in the response so we can correlate easier. For reva tracked in https://github.com/cs3org/reva/issues/587
{{< /hint >}}
The last line gives us a hint where the log message originated: `.../github.com/cs3org/reva@v0.0.2-0.20200318111623-a2f97d4aa741/internal/http/services/owncloud/ocs/reqres.go:94`. Which looks like this:
```go
89: // WriteOCSResponse handles writing ocs responses in json and xml
90: func WriteOCSResponse(w http.ResponseWriter, r *http.Request, res *Response, err error) {
91: var encoded []byte
92:
93: if err != nil {
94: appctx.GetLogger(r.Context()).Error().Err(err).Msg(res.OCS.Meta.Message)
95: }
```
Ok, so this seems to be a convenience method that is called from multiple places an also handles errors. Unfortunately, this hides the actual source of the error. We could set a breakpoint in line 94 and reproduce the problem, which can be a lot harder than just clicking the share button or sending a curl request again. So let us see what else the log tells us.
The previous line tells us that a Stat request failed: `uri=/cs3.gateway.v1beta1.GatewayAPI/Stat`. This time the line is written by the grpc log interceptor. What else is there?
The first line tells us that looking up the responsible storage provider seems to have succeeded: `uri=/cs3.storage.registry.v1beta1.RegistryAPI/GetStorageProvider`.
At this point it your familiarity with the codebase starts to become a factor. If you are new you should probably go back to setting a break point on the log line and check the stack trace.
Debug wherever the call trace leads you to ... good luck!
### Managing dependencies and testing changes
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.

73
docs/eos.md Normal file
View File

@@ -0,0 +1,73 @@
---
title: "EOS"
date: 2020-02-27T20:35:00+01:00
weight: 30
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs
geekdocFilePath: eos.md
---
{{< toc >}}
OCIS can be configured to run on top of [eos](https://eos.web.cern.ch/). While the [eos documentation](http://eos-docs.web.cern.ch/) does cover a lot of topics it leaves out some details that you may have to either pull from various [docker containers](https://gitlab.cern.ch/eos/eos-docker), the [forums](https://eos-community.web.cern.ch/) or even the [source](https://github.com/cern-eos/eos) itself.
This document is a work in progress of the current setup.
## Current status
Using ocis and eos it is possible today to manage folders. Sharing is [heavily](https://github.com/cs3org/reva/pull/523) [under](https://github.com/cs3org/reva/pull/585) [development](https://github.com/cs3org/reva/pull/482). FIle up and download needs proper configuration of the dataprovider to also use eos.
## How to do it
### Grab it!
```
$ git clone git@github.com:owncloud/ocis.git
$ cd ocis
```
### Run it!
We poured the nitty gritty details of setting up ocis into Makefile destinations. After running
```
$ make eos-start
```
the eos related docker containers will be created, started and setup to authenticate a gainst the ocis-glauth service.
It will also copy the ocis binary tho the `eos-cli1` container and start `ocis reva-storage-home` with the necessary environment variables to use the eos storage driver.
For details have a look at the `Makefile`.
### Test it!
You should now be able to point your browser to https://localhost:9200 and login using the demo user credentials, eg `einstein:relativity`.
{{< hint info >}}
If you encounter an error when the IdP redirects you back to phoenix, just reload the page and it should be gone ... or debug it. PR welcome!
{{< /hint >}}
Create a folder in the ui. Then check it was created in eos:
```
$ docker exec -it eos-mgm1 eos ls /eos/dockertest/einstein
```
Now create a new folder in eos (using eos-mgm1 you will be logged in as admin, see the `whoami`, which is why we `chown` the folder to the uid and gid of einstein afterwards):
```
$ docker exec -it eos-mgm1 eos whoami
$ docker exec -it eos-mgm1 eos mkdir /eos/dockertest/einstein/rocks
$ docker exec -it eos-mgm1 eos chown 20000:30000 /eos/dockertest/einstein/rocks
```
Check that the folder exists in the web ui.
## Next steps
- configure storage-home-data to enable file upload, PRs against `ocis-reva` welcome
- get sharing implemented, PRs against `reva` welcome
- simplify home logic, see https://github.com/cs3org/reva/issues/601 and https://github.com/cs3org/reva/issues/578

2
docs/extensions.md
View File

@@ -1,5 +1,5 @@
---
title: "Extensions"
title: "Extension"
date: 2020-02-27T20:35:00+01:00
weight: 40
geekdocRepo: https://github.com/owncloud/ocis

119
docs/getting-started.md
View File

@@ -53,6 +53,26 @@ chmod +x ocis
- Running ocis currently needs a working Redis caching server
- The default promary storage location is `/var/tmp/reva/data`. You can change that value by configuration.
## 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 --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 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 health --help
{{< / highlight >}}
## Quickstart for Developers
Following https://github.com/owncloud/ocis#development
@@ -107,3 +127,102 @@ com.owncloud.api.hello
To the list of available services.
## Metrics
This service provides some [Prometheus](https://prometheus.io/) metrics through the debug endpoint, you can optionally secure the metrics endpoint by some random token, which got to be configured through one of the flag `--debug-token` or the environment variable `OCIS_DEBUG_TOKEN` mentioned above. By default the metrics endpoint is bound to `http://0.0.0.0:8001/metrics`.
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