Merge pull request #103 from butonic/update-docs

update docs

README.md

@@ -26,6 +26,29 @@ make generate build
 ./bin/ocis -h
 ```
 
+## Quickstart
+After building the binary with the above steps run all services
+
+```console
+./bin/ocis 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.
+
+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}
+```
+
+Open [http://localhost:9100](http://localhost:9100) and login using one of the demo accounts:
+
+```console
+einstein:relativity
+marie:radioactivty
+richard:superfluidity
+```
+
 ## Security
 
 If you find a security issue please contact security@owncloud.com first.

docs/content/extensions.md

@@ -0,0 +1,231 @@
+---
+title: "Extensions"
+date: 2020-01-31T17:20:00+00:00
+anchor: "extensions"
+weight: 25
+---
+
+## How to build and run ocis-simple
+
+ocis uses build tags to build different flavors of the binary. In order to work on a new extension we are going to reduce the scope a little and use the `simple` tag. Let us begin by creating a dedicated folder:
+
+```console
+mkdir ocis-extension-workshop && ocis-extension-workshop
+```
+
+Following https://github.com/owncloud/ocis
+
+```console
+git clone https://github.com/owncloud/ocis.git
+cd ocis
+
+TAGS=simple make generate build
+```
+
+*Q: Can you specify which version of phoenix to use?*
+*A: No, the phoenix that is used is compiled into the [assets of ocis-phoenix](https://github.com/owncloud/ocis-phoenix/blob/master/pkg/assets/embed.go) which is currently not automatically updated. We'll see how to use a custom phoenix later.*
+
+`bin/ocis server`
+
+Open the browser at http://localhost:9100
+
+1. You land on the login screen. click login
+2. You are redirected to an idp at http://localhost:9140/oauth2/auth with a login mask. Use `einstein:relativity`to login (one of the three demo users)
+3. You are redirected to http://localhost:9100/#/hello the ocis-hello app
+4. Replace `World` with something else and submit. You should see `Hello %something else%`
+
+*Q: One of the required ports is already in use. Ocis seems to be trying to restart the service over and over. What gives?*
+*A: Using the ocis binary to start the server will case ocis to keep track of the different services and restart them in case they crash.*
+
+## Hacking ocis-hello
+
+go back to the ocis-extension-workshop folder
+
+```console
+cd ..
+```
+
+Following https://github.com/owncloud/ocis-hello
+
+```
+git clone https://github.com/owncloud/ocis-hello.git
+cd ocis-hello
+
+yarn install
+# this actually creates the assets
+yarn build
+
+# this will compile the assets into the binary
+make generate build
+```
+
+Two options:
+1. run only the necessery services from ocis and ocis-hello independently
+2. compile ocis with the updated ocis-hello
+
+### Option 1:
+get a list of ocis services:
+
+```console
+ps ax | grep ocis
+```
+
+Try to kill `ocis hello`
+
+Remember: for now, killing a service will cause ocis to restart it. This is subject to change.
+
+In order to be able to manage the processes ourselves we need to start them independently:
+
+`bin/ocis server` starts the same services as:
+
+```
+bin/ocis micro &
+bin/ocis phoenix &
+bin/ocis hello &
+bin/ocis reva &
+```
+
+Now we can kill the `ocis hello` and use our custom built ocis-hello binary:
+
+```console
+cd ../ocis-hello
+bin/ocis-hello server
+```
+
+## Hacking phoenix (and ocis-phoenix)
+
+Following https://github.com/owncloud/phoenix we are going to build the current phoenix
+
+```
+git clone https://github.com/owncloud/phoenix.git
+cd phoenix
+
+yarn install
+yarn dist
+```
+
+We can tell ocis to use the compiled assets:
+
+Kill `ocis phoenix`, then use the compiled assets when starting phoenix.
+
+```console
+cd ../ocis
+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
+
+## External phoenix apps
+
+This is what hello is: copy and extend!
+
+1. Phoenix is configured using the config.json which is served by the phoenix service (either `bin/ocis phoenix` or `bin/ocis-phoenix server`)
+
+2. point ocis phoenix to the web config which you extended with an external app:
+`PHOENIX_WEB_CONFIG="`pwd`/../phoenix/config.json" PHOENIX_ASSET_PATH="`pwd`/../phoenix/dist" bin/ocis phoenix`
+
+```json
+{
+  "server": "http://localhost:9140",
+  "theme": "owncloud",
+  "version": "0.1.0",
+  "openIdConnect": {
+    "metadata_url": "http://localhost:9140/.well-known/openid-configuration",
+    "authority": "http://localhost:9140",
+    "client_id": "phoenix",
+    "response_type": "code",
+    "scope": "openid profile email"
+  },
+  "apps": [],
+  "external_apps": [
+    {
+      "id": "hello",
+      "path": "http://localhost:9105/hello.js",
+      "config": {
+        "url": "http://localhost:9105"
+      }
+    },
+    {
+      "id": "myapp",
+      "path": "http://localhost:6789/superapp.js",
+      "config": {
+        "backend": "http://someserver:1234",
+        "myconfig": "is awesome"
+      }
+    }
+  ]
+}
+```
+
+## Phoenix extension points
+
+> Note: For an up to date list check out [the phoenix documentation](https://github.com/owncloud/phoenix/issues/2423). 
+
+Several ones available:
+
+### Phoenix core
+- App switcher (defined in config.json)
+- App container (loads UI of your extension)
+
+### Files app
+- File action
+- Create new file action
+- Sidebar
+- Quick access for sidebar inside of file actions (in the file row)
+
+Example of a file action in the `app.js`:
+```js
+const appInfo = {
+  name: 'MarkdownEditor',
+  id: 'markdown-editor',
+  icon: 'text',
+  isFileEditor: true,
+  extensions: [{
+    extension: 'txt',
+    newFileMenu: {
+      menuTitle ($gettext) {
+        return $gettext('Create new plain text file…')
+      }
+    }
+  },
+  {
+    extension: 'md',
+    newFileMenu: {
+      menuTitle ($gettext) {
+        return $gettext('Create new mark-down file…')
+      }
+    }
+  }]
+}
+```
+
+For the side bar have a look at the files app, `defaults.js` & `fileSideBars`
+
+## API driven development
+
+Until now we only had a look at the ui and how the extensions are managed on the cli. But how do apps actually talk to the server?
+
+Short answer: any way you like
+
+Long answer: micro and ocis-hello follow a protocol driven development:
+
+- specify the API using protobuf
+- generate client and server code
+- evolve based on the protocol
+
+- CS3 api uses protobuf as well and uses GRPC
+
+- ocis uses go-micro, which provides http and grpc gateways
+- the gateways and protocols are optional
+
+- owncloud and kopano are looking into a [MS graph](https://developer.microsoft.com/de-de/graph) like api to handle phoenix requests.
+  - they might be about user, contacrs, calendars ... which is covered by the graph api
+  - we want to integrate with eg. kopano and provide a commen api (file sync and share is covered as well)
+
+- as an example for protobuf take a look at [ocis-hello](https://github.com/owncloud/ocis-hello/tree/master/pkg/proto/v0)

docs/content/getting-started.md

@@ -17,6 +17,25 @@ TBD
 
 TBD
 
+## Quickstart
+
+Following https://github.com/owncloud/ocis#development
+
+```console
+git clone https://github.com/owncloud/ocis.git
+cd ocis
+make build
+mkdir /var/tmp/reva/root/{home,oc}
+```
+
+Open http://localhost:9100 and login using one of the demo accounts:
+
+```console
+einstein:relativity
+marie:radioactivty
+richard:superfluidity
+```
+
 ## Runtime
 
 Included with the ocis binary is embedded a go-micro runtime that is in charge of starting services as a fork of the master process. This provides complete control over the services. Ocis extensions can be added as part of this runtime.
@@ -28,21 +47,14 @@ Included with the ocis binary is embedded a go-micro runtime that is in charge o
 This will currently boot:
 
 ```console
-go.micro
-go.micro.api
-go.micro.bot
-go.micro.broker
-go.micro.debug
+com.owncloud.api
+com.owncloud.http.broker
+com.owncloud.proxy
+com.owncloud.registry
+com.owncloud.router
+com.owncloud.runtime
+com.owncloud.web
 go.micro.http.broker
-go.micro.monitor
-go.micro.network
-go.micro.proxy
-go.micro.registry
-go.micro.router
-go.micro.runtime
-go.micro.store
-go.micro.tunnel
-go.micro.web
 ```
 
 Further ocis extensions can be added to the runtime via the ocis command like:
@@ -51,11 +63,11 @@ Further ocis extensions can be added to the runtime via the ocis command like:
 ./bin/ocis hello
 ```
 
-Which whill register:
+Which will register:
 
 ```console
-go.micro.web.hello
-go.micro.api.hello
+com.owncloud.web.hello
+com.owncloud.api.hello
 ```
 
 To the list of available services.
@@ -143,7 +155,7 @@ If you prefer to configure the service with commandline flags you can see the av
 : Address to bind grpc server, defaults to `0.0.0.0:9001`
 
 --services-enabled
-: List of enabled services, defaults to `phoenix,konnectd,graph,ocs,webdav,hello`
+: 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`
 
 #### Health