parse command usage and flagset usage from code

2026-01-07 21:00:30 -06:00 · 2020-04-10 00:29:35 +02:00
parent eb7ed6491c
commit e423b61352
7 changed files with 1585 additions and 14 deletions
--- a/10
+++ b/10
@@ -46,6 +46,8 @@ ifndef DATE
 endif

 LDFLAGS += -s -w -X "$(IMPORT)/pkg/version.String=$(VERSION)" -X "$(IMPORT)/pkg/version.Date=$(DATE)"
+DEBUG_LDFLAGS += -X "$(IMPORT)/pkg/version.String=$(VERSION)" -X "$(IMPORT)/pkg/version.Date=$(DATE)"
+
 GCFLAGS += all=-N -l

 .PHONY: all
@@ -99,7 +101,7 @@ $(BIN)/$(EXECUTABLE): $(SOURCES)
 	$(GOBUILD) -v -tags '$(TAGS)' -ldflags '$(LDFLAGS)' -o $@ ./cmd/$(NAME)

 $(BIN)/$(EXECUTABLE)-debug: $(SOURCES)
-	$(GOBUILD) -v -tags '$(TAGS)' -ldflags '$(LDFLAGS)' -gcflags '$(GCFLAGS)' -o $@ ./cmd/$(NAME)
+	$(GOBUILD) -v -tags '$(TAGS)' -ldflags '$(DEBUG_LDFLAGS)' -gcflags '$(GCFLAGS)' -o $@ ./cmd/$(NAME)

 .PHONY: release
 release: release-dirs release-linux release-windows release-darwin release-copy release-check
@@ -143,12 +145,16 @@ docs-copy:
 	git checkout origin/source -f; \
 	rsync --delete -ax ../docs/ content/extensions/$(NAME)

+.PHONY: config-docs-generate
+config-docs-generate:
+	go run github.com/owncloud/flaex >| docs/configuration.md
+
 .PHONY: docs-build
 docs-build:
 	cd $(HUGO); hugo

 .PHONY: docs
-docs: docs-copy docs-build
+docs: config-docs-generate docs-copy docs-build

 .PHONY: watch
 watch:
--- a/docs/configuration.md
+++ b/docs/configuration.md
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,27 +1,56 @@
 ---
 title: "Getting Started"
 date: 2018-05-02T00:00:00+00:00
-weight: 20
+weight: 15
 geekdocRepo: https://github.com/owncloud/ocis-reva
 geekdocEditPath: edit/master/docs
 geekdocFilePath: getting-started.md
 ---

-### Installation
+{{< 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

-TBD
+Docker images for ocis-reva are hosted on https://hub.docker.com/r/owncloud/ocis-reva.

-#### Binaries
+The `latest` tag always reflects the current master branch.

-TBD
+```console
+docker pull owncloud/ocis-reva
+```

-### Configuration
+#### Dependencies

-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.
+- Running ocis-reva currently needs a working Redis caching server
+- The default storage location in the container is `/var/tmp/reva/data`. You may want to create a volume to persist the files in the primary storage

-The configuration tries to map different configuration options from reva into dedicated services. For now please run `bin/ocis-reva {command} -h` to see the list of available options or have a look at [the flagsets](https://github.com/owncloud/ocis-reva/tree/master/pkg/flagset) and the mapping to a reva config in the corresponding [commands](https://github.com/owncloud/ocis-reva/tree/master/pkg/command).
+### Binaries

+The pre-built binaries for different platforms are downloadable at https://download.owncloud.com/ocis/ocis-reva/ . 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-reva/testing/
+
+```console
+curl https://download.owncloud.com/ocis/ocis/1.0.0-beta1/ocis-reva-1.0.0-beta1-darwin-amd64 --output ocis-reva
+chmod +x ocis
+./ocis-reva sharing
+```
+
+#### Dependencies
+
+- 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-reva --help`.
+
+### 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-reva health --help
+{{< / highlight >}}
--- a/go.mod
+++ b/go.mod
@@ -11,6 +11,7 @@ require (
 	github.com/micro/go-micro v1.18.0
 	github.com/micro/go-micro/v2 v2.0.0
 	github.com/oklog/run v1.0.0
+	github.com/owncloud/flaex v0.0.0-20200411150708-dce59891a203
 	github.com/owncloud/ocis-pkg/v2 v2.0.1
 	github.com/pelletier/go-toml v1.6.0 // indirect
 	github.com/prometheus/client_model v0.0.0-20191202183732-d1d2010b5bee // indirect
@@ -23,7 +24,6 @@ require (
 	github.com/uber/jaeger-client-go v2.20.1+incompatible // indirect
 	golang.org/x/sys v0.0.0-20200103143344-a1369afcdac7 // indirect
 	gopkg.in/ini.v1 v1.51.1 // indirect
-	gopkg.in/yaml.v2 v2.2.7 // indirect
 )

 replace google.golang.org/grpc => google.golang.org/grpc v1.26.0
--- a/go.sum
+++ b/go.sum
@@ -444,6 +444,8 @@ github.com/ory/fosite v0.31.0/go.mod h1:lSSqjo8Kr/U1P3kJWxsNGHmq7TnH/7pS1ijvQRT7
 github.com/ory/go-convenience v0.1.0 h1:zouLKfF2GoSGnJwGq+PE/nJAE6dj2Zj5QlTgmMTsTS8=
 github.com/ory/go-convenience v0.1.0/go.mod h1:uEY/a60PL5c12nYz4V5cHY03IBmwIAEm8TWB0yn9KNs=
 github.com/ovh/go-ovh v0.0.0-20181109152953-ba5adb4cf014/go.mod h1:joRatxRJaZBsY3JAOEMcoOp05CnZzsx4scTxi95DHyQ=
+github.com/owncloud/flaex v0.0.0-20200411150708-dce59891a203 h1:sXVTQ94GWeiBhlgN0kSbcyXQNmwzPuuhWyObxgTu/xE=
+github.com/owncloud/flaex v0.0.0-20200411150708-dce59891a203/go.mod h1:jip86t4OVURJTf8CM/0e2qcji/Y4NG3l2lR8kex4JWw=
 github.com/owncloud/ocis-pkg/v2 v2.0.1 h1:3ISEtfjAz4pDFczTggIJwKuft3bVsAp1C7dFY9BBPEs=
 github.com/owncloud/ocis-pkg/v2 v2.0.1/go.mod h1:7bVnn3VUaqdmvpMkXF0QVEF1fRugs35hSkuVTAq9yjk=
 github.com/oxtoacart/bpool v0.0.0-20190530202638-03653db5a59c h1:rp5dCmg/yLR3mgFuSOe4oEnDDmGLROTvMragMUXpTQw=
@@ -644,6 +646,8 @@ golang.org/x/crypto v0.0.0-20191108234033-bd318be0434a h1:R/qVym5WAxsZWQqZCwDY/8
 golang.org/x/crypto v0.0.0-20191108234033-bd318be0434a/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/crypto v0.0.0-20200117160349-530e935923ad h1:Jh8cai0fqIK+f6nG0UgPW5wFk8wmiMhM3AyciDBdtQg=
 golang.org/x/crypto v0.0.0-20200117160349-530e935923ad/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.0.0-20200320181102-891825fb96df h1:lDWgvUvNnaTnNBc/dwOty86cFeKoKWbwy2wQj0gIxbU=
+golang.org/x/crypto v0.0.0-20200320181102-891825fb96df/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
 golang.org/x/exp v0.0.0-20190306152737-a1d7652674e8/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
 golang.org/x/exp v0.0.0-20190510132918-efd6b22b2522/go.mod h1:ZjyILWgesfNpC6sMxTJOJm9Kp84zZh5NQWvqDGG3Qr8=
@@ -771,6 +775,7 @@ golang.org/x/tools v0.0.0-20191029041327-9cc4af7d6b2c/go.mod h1:b+2E5dAYhXwXZwtn
 golang.org/x/tools v0.0.0-20191029190741-b9c20aec41a5 h1:hKsoRgsbwY1NafxrwTs+k64bikrLBkAgPir1TNCj3Zs=
 golang.org/x/tools v0.0.0-20191029190741-b9c20aec41a5/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20191125144606-a911d9008d1f/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20191130070609-6e064ea0cf2d/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20191216052735-49a3e744a425/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
 golang.org/x/tools v0.0.0-20191216173652-a0e659d51361 h1:RIIXAeV6GvDBuADKumTODatUqANFZ+5BPMnzsy4hulY=
 golang.org/x/tools v0.0.0-20191216173652-a0e659d51361/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
@@ -846,14 +851,15 @@ gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.4 h1:/eiJrUcujPVeJ3xlSWaiNi3uSVmDGBK1pDHUHAnao1I=
 gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
-gopkg.in/yaml.v2 v2.2.7 h1:VUgggvou5XRW9mHwD/yXxIYSMtY0zoKQf/v226p2nyo=
-gopkg.in/yaml.v2 v2.2.7/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.8 h1:obN1ZagJSUGI0Ek/LBmuj4SNLPfIny3KsKFopxRdj10=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gotest.tools v2.2.0+incompatible/go.mod h1:DsYFclhRJ6vuDpmuTbkuFWG+y2sxOXAzmJt81HFBacw=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190106161140-3f1c8253044a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190418001031-e561f6794a2a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.1-2019.2.3 h1:3JgtbtFHMiCmsznwGVTUWbgGov+pVqnlf1dEJTNAXeM=
 honnef.co/go/tools v0.0.1-2019.2.3/go.mod h1:a3bituU0lyd329TUQxRnasdCoJDkEUEAqEt0JzvZhAg=
+honnef.co/go/tools v0.0.1-2020.1.3/go.mod h1:X/FiERA/W4tHapMX5mGpAtMSVEeEUOyHaw9vFzvIQ3k=
 k8s.io/kubernetes v1.13.0/go.mod h1:ocZa8+6APFNC2tX1DZASIbocyYT5jHzqFVsY5aoB7Jk=
 rsc.io/binaryregexp v0.2.0/go.mod h1:qTv7/COck+e2FymRvadv62gMdZztPaShugOCi3I+8D8=
 rsc.io/quote/v3 v3.1.0/go.mod h1:yEA65RcK8LyAZtP9Kv3t0HmxON59tX3rD+tICJqUlj0=
--- a/templates/CONFIGURATION.tmpl
+++ b/templates/CONFIGURATION.tmpl
@@ -0,0 +1,78 @@
+---
+title: "Configuration"
+date: "{{ date "2006-01-02T15:04:05-0700" now }}"
+weight: 20
+geekdocRepo: https://github.com/owncloud/ocis-reva
+geekdocEditPath: edit/master/docs
+geekdocFilePath: configuration.md
+---
+{{- define "options"}}
+{{ $fnName := (last . ).Flags -}}
+{{ range $opt := first . }}{{ with list $fnName $opt -}}
+{{ $o := last . -}}
+{{ if eq $o.FnName $fnName -}}
+--{{ $o.Name }} | ${{ index $o.Env 0 }}  
+: {{ $o.Usage }}. {{- if $o.Default }} Default: `{{ $o.Default }}`.{{ end }}
+
+{{ end -}}
+{{ end -}}
+{{ end -}}
+{{ end }}
+
+{{`{{< 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.
+
+{{ $options := .Options -}}
+{{ range $com := .Commands }}{{ with (list $options $com) -}}
+{{ $c := last . -}}
+{{ if eq $c.Name "ocis-reva" -}}
+## Root Command
+
+{{ $c.Usage }}
+
+Usage: `ocis-reva [global options] command [command options] [arguments...]`
+{{ template "options" . -}}
+## Sub Commands
+
+{{ end -}}
+{{ end -}}
+{{ end -}}
+{{- range $com := .Commands }}{{ with (list $options $com) -}}
+{{- $c := last . }}
+{{- if ne $c.Name "ocis-reva" -}}
+### ocis-reva {{ $c.Name }}
+
+{{ $c.Usage }}
+
+Usage: `ocis-reva {{ $c.Name }} [command options] [arguments...]`
+{{ template "options" . }}
+{{- end -}}
+{{- end -}}
+{{- end -}}
--- a/tools.go
+++ b/tools.go
@@ -3,5 +3,6 @@
 package main

 import (
+	_ "github.com/owncloud/flaex"
 	_ "github.com/restic/calens"
 )