Fix docs typos
This commit is contained in:
Phil Davis
@@ -7,6 +7,6 @@ geekdocEditPath: edit/master/docs/architecture
|
||||
geekdocFilePath: _index.md
|
||||
---
|
||||
|
||||
In the architecture part of the documentation we collect useful developer documentation on different aspects of the architecture. We are using mermaid.js to collaborate on the necessardy diagrams.
|
||||
In the architecture part of the documentation we collect useful developer documentation on different aspects of the architecture. We are using mermaid.js to collaborate on the necessary diagrams.
|
||||
|
||||
*Pictures tell more than a thousand words.*
|
||||
|
||||
@@ -132,7 +132,7 @@ It would require client changes that depend on the server side actually having a
|
||||
But having to list n storages might become a bottleneck anyway, so we are going to have the gateway calculate a virtual root ETag for all entry points a user has access to and cache that.
|
||||
|
||||
## Server Side Stat Polling
|
||||
Every client polls the virtual root ETag (every 30 sec). The gateway will cache the virutal root ETag of every storage for 30 sec as well. That way every storage provider is only stated once every 30 sec (can be throttled dynamically to adapt to storage io load).
|
||||
Every client polls the virtual root ETag (every 30 sec). The gateway will cache the virtual root ETag of every storage for 30 sec as well. That way every storage provider is only stated once every 30 sec (can be throttled dynamically to adapt to storage io load).
|
||||
|
||||
|
||||
{{<mermaid class="text-center">}}
|
||||
@@ -182,9 +182,9 @@ Since the active clients will poll the etag for all active users the gateway wil
|
||||
|
||||
For a single machine using a local posix storage the linux kernel already caches the inodes that contain the metadata that is necessary to calculate the ETag (even extended attributes are supported). With 4k inodes 256 nodes take 1Mb of RAM, 1k inodes take 4Mb and 1M inodes take 4Gb to completely cache the file metadata. For distributed filesystems a dedicated cache might make sense to prevent hammering it with stat like requests to calculate ETags.
|
||||
|
||||
### Bandwith considerations
|
||||
### Bandwidth considerations
|
||||
|
||||
The bandwith for a single machine might be another bottleneck. Consider a propfind request with roughly 500 bytes and a response with roughly 800 bytes in size:
|
||||
The bandwidth for a single machine might be another bottleneck. Consider a propfind request with roughly 500 bytes and a response with roughly 800 bytes in size:
|
||||
- At 100Mbit (~10Mb/s) you can receive 20 000 PROPFIND requests
|
||||
- At 1000Mbit (~100Mb/s) you can receive 200 000 PROPFIND requests
|
||||
- At 10Gbit (~1Gb/s) you can receive 2 000 000 PROPFIND requests
|
||||
|
||||
@@ -35,9 +35,9 @@ oidc-gen \
|
||||
|
||||
If you have dynamic client registration enabled on your OpenID Connect identity provider, you can skip the `--client-id`, `--client-secret` and `--pub` options.
|
||||
|
||||
If your're using a dedicated OpenID Connect client for the OIDC-agent, we recommend a public one with the following two redirect URIs: `http://127.0.0.1:*` and `http://localhost:*`. Alternatively you also may use the already existing OIDC client of the ownCloud Desktop Client (`--client-id=xdXOt13JKxym1B1QcEncf2XDkLAexMBFwiT9j6EfhhHFJhs2KM9jbjTmf8JBXE69` and `--client-secret=UBntmLjC2yYCeHwsyj73Uwo9TAaecAetRwMw0xYcvNL9yRdLSUi0hUAHfvCHFeFh`, no `--pub` set)
|
||||
If you're using a dedicated OpenID Connect client for the OIDC-agent, we recommend a public one with the following two redirect URIs: `http://127.0.0.1:*` and `http://localhost:*`. Alternatively you also may use the already existing OIDC client of the ownCloud Desktop Client (`--client-id=xdXOt13JKxym1B1QcEncf2XDkLAexMBFwiT9j6EfhhHFJhs2KM9jbjTmf8JBXE69` and `--client-secret=UBntmLjC2yYCeHwsyj73Uwo9TAaecAetRwMw0xYcvNL9yRdLSUi0hUAHfvCHFeFh`, no `--pub` set)
|
||||
|
||||
Please also note that the OIDC-agent will listen on your localhost interface on port 12345 for the time of the intial authentication. If that port is already occupied on your machine, you can easily change that by setting the `--redirect-uri` parameter to a different value.
|
||||
Please also note that the OIDC-agent will listen on your localhost interface on port 12345 for the time of the initial authentication. If that port is already occupied on your machine, you can easily change that by setting the `--redirect-uri` parameter to a different value.
|
||||
|
||||
After a successful login or an already existing session you will be redirected to success page of the OIDC-agent.
|
||||
You will now be asked for a password for your account configuration, so that your OIDC session is secured and cannot be used by other people with access to your computer.
|
||||
|
||||
@@ -21,7 +21,7 @@ The JSON representation of a Group as handled by the Groups API looks like this:
|
||||
}
|
||||
```
|
||||
|
||||
Our implemenation currently support two Attributes for a Group:
|
||||
Our implementation currently supports two Attributes for a Group:
|
||||
|
||||
| Attribute | Description |
|
||||
|---------------|-------------|
|
||||
@@ -33,7 +33,7 @@ Our implemenation currently support two Attributes for a Group:
|
||||
|
||||
#### `GET /groups`
|
||||
|
||||
Returns a list of all groups
|
||||
Returns a list of all groups
|
||||
|
||||
Example:
|
||||
|
||||
@@ -125,7 +125,7 @@ Note the missing `"id"` Attribute. It will be generated by the server:
|
||||
|
||||
##### Response
|
||||
|
||||
When successful, the Reponse will return the new group including the newly allocated `"id"`:
|
||||
When successful, the response will return the new group including the newly allocated `"id"`:
|
||||
|
||||
```
|
||||
{
|
||||
@@ -146,7 +146,7 @@ When successful the API returns no response body and the HTTP status code 204 (N
|
||||
|
||||
#### `PATCH /groups/{id}`
|
||||
|
||||
Updating attributes of a single group is supposed to be done with a patch request. This is however currently not fully
|
||||
Updating attributes of a single group is supposed to be done with a patch request. This is however currently not fully
|
||||
implemented for our write-enabled backends. The PATCH request can however be used to add multiple members to a group at once.
|
||||
See below.
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ The JSON representation of a User handled by the Users API looks like this:
|
||||
}
|
||||
```
|
||||
|
||||
Our implemenation currently supports only a limited set of Attributes of Users:
|
||||
Our implementation currently supports only a limited set of Attributes of Users:
|
||||
|
||||
| Attribute | Description |
|
||||
|---------------|-------------|
|
||||
@@ -57,7 +57,7 @@ Response:
|
||||
|
||||
#### `GET /users`
|
||||
|
||||
Returns a list of all users
|
||||
Returns a list of all users
|
||||
|
||||
Example:
|
||||
|
||||
@@ -129,7 +129,7 @@ Note the missing `"id"` Attribute. It will be generated by the server:
|
||||
|
||||
##### Response
|
||||
|
||||
When successful, the Reponse will return the new user, without the password, but including the newly allocated `"id"`:
|
||||
When successful, the response will return the new user, without the password, but including the newly allocated `"id"`:
|
||||
|
||||
```
|
||||
{
|
||||
|
||||
@@ -54,7 +54,7 @@ In order to modify the mime type config you need to set `STORAGE_APP_REGISTRY_MI
|
||||
```json
|
||||
[
|
||||
{
|
||||
"mime_type": "applition/vnd.oasis.opendocument.text",
|
||||
"mime_type": "application/vnd.oasis.opendocument.text",
|
||||
"extension": "odt",
|
||||
"name": "OpenDocument",
|
||||
"description": "OpenDocument text document",
|
||||
@@ -82,7 +82,7 @@ Fields:
|
||||
- `description` is a human readable description of the file / mime type
|
||||
- `icon` URL to an icon which should be used for that mime type
|
||||
- `default_app` name of the default app which opens this mime type when the user doesn't specify one
|
||||
- `allow_creation` is wether a user should be able to create new file from that mime type (`true` or `false`)
|
||||
- `allow_creation` is whether a user should be able to create new file from that mime type (`true` or `false`)
|
||||
|
||||
### Listing available apps / mime types
|
||||
|
||||
|
||||
@@ -69,7 +69,7 @@ In ownCloud 10 you can not only create *public links* but also *private links*.
|
||||
|-|-|
|
||||
| https://demo.owncloud.com/apps/files/?dir=/Photos/Vacation&fileid=24 | The normal browser URL |
|
||||
| https://demo.owncloud.com/apps/files/?fileid=24 | the `dir` is actually not used to find the directory and will be filled when pasting this URL |
|
||||
| https://demo.owncloud.com/f/24 | *private links* are the shortened version of this and workh in the same way |
|
||||
| https://demo.owncloud.com/f/24 | *private links* are the shortened version of this and work in the same way |
|
||||
| https://demo.owncloud.com/s/piLdAAt1m3Bg0Fk | public link |
|
||||
|
||||
{{< hint >}}
|
||||
|
||||
@@ -193,7 +193,7 @@ Examples would be every user's personal storage *space*, project storage *spaces
|
||||
Finally, a logical `storage space id` is not tied to a specific [*spaces provider*]({{< ref "./spacesprovider.md" >}}). If the [*storage driver*]({{< ref "./storagedrivers.md" >}}) supports it, we can import existing files including their `file id`, which makes it possible to move storage *spaces* between [*spaces providers*]({{< ref "./spacesprovider.md" >}}) to implement storage classes, e.g. with or without archival, workflows, on SSDs or HDDs.
|
||||
|
||||
## Shares
|
||||
*To be clarified: we are aware that [*storage spaces*]({{< ref "#storage-spaces" >}}) may be too 'heavywheight' for ad hoc sharing with groups. That being said, there is no technical reason why group shares should not be treated like storage [*spaces*]({{< ref "#storage-spaces" >}}) that users can provision themselves. They would share the quota with the users home or personal storage [*space*]({{< ref "#storage-spaces" >}}) and the share initiator would be the sole owner. Technically, the mechanism of treating a share like a new storage [*space*]({{< ref "#storage-spaces" >}}) would be the same. This obviously also extends to user shares and even file individual shares that would be wrapped in a virtual collection. It would also become possible to share collections of arbitrary files in a single storage space, e.g. the ten best pictures from a large album.*
|
||||
*To be clarified: we are aware that [*storage spaces*]({{< ref "#storage-spaces" >}}) may be too 'heavyweight' for ad hoc sharing with groups. That being said, there is no technical reason why group shares should not be treated like storage [*spaces*]({{< ref "#storage-spaces" >}}) that users can provision themselves. They would share the quota with the users home or personal storage [*space*]({{< ref "#storage-spaces" >}}) and the share initiator would be the sole owner. Technically, the mechanism of treating a share like a new storage [*space*]({{< ref "#storage-spaces" >}}) would be the same. This obviously also extends to user shares and even file individual shares that would be wrapped in a virtual collection. It would also become possible to share collections of arbitrary files in a single storage space, e.g. the ten best pictures from a large album.*
|
||||
|
||||
## Notes
|
||||
|
||||
|
||||
@@ -88,7 +88,7 @@ Examples would be every user's home storage space, project storage spaces or gro
|
||||
Finally, a logical `storage space id` is not tied to a specific [*storage provider*]({{< ref "#storage-providers" >}}). If the [*storage driver*]({{< ref "#storage-drivers" >}}) supports it, we can import existing files including their `file id`, which makes it possible to move [*storage spaces*]({{< ref "#storage-spaces" >}}) between [*storage providers*]({{< ref "#storage-providers" >}}) to implement storage classes, e.g. with or without archival, workflows, on SSDs or HDDs.
|
||||
|
||||
## Shares
|
||||
*To be clarified: we are aware that [*storage spaces*]({{< ref "#storage-spaces" >}}) may be too 'heavyweight' for ad hoc sharEsing with groups. That being said, there is no technical reason why group shares should not be treated like [*storage spaces*]({{< ref "#storage-spaces" >}}) that users can provision themselves. They would share the quota with the users home [*storage space*]({{< ref "#storage-spaces" >}}) and the share initiator would be the sole owner. Technically, the mechanism of treating a share like a new [*storage space*]({{< ref "#storage-spaces" >}}) would be the same. This obviously also extends to user shares and even file individual shares that would be wrapped in a virtual collection. It would also become possible to share collections of arbitrary files in a single storage space, e.g. the ten best pictures from a large album.*
|
||||
*To be clarified: we are aware that [*storage spaces*]({{< ref "#storage-spaces" >}}) may be too 'heavyweight' for ad hoc sharing with groups. That being said, there is no technical reason why group shares should not be treated like [*storage spaces*]({{< ref "#storage-spaces" >}}) that users can provision themselves. They would share the quota with the users home [*storage space*]({{< ref "#storage-spaces" >}}) and the share initiator would be the sole owner. Technically, the mechanism of treating a share like a new [*storage space*]({{< ref "#storage-spaces" >}}) would be the same. This obviously also extends to user shares and even file individual shares that would be wrapped in a virtual collection. It would also become possible to share collections of arbitrary files in a single storage space, e.g. the ten best pictures from a large album.*
|
||||
|
||||
|
||||
## Storage Systems
|
||||
|
||||
@@ -55,7 +55,7 @@ Chosen option: "\[option 1\]", because \[justification. e.g., only option, which
|
||||
|
||||
### Cold Migration
|
||||
|
||||
The migration happens while the service is offline. File metadata, blobs and share data is exported from ownCloud 10 and imported in oCIS. This can happen user by user, where every user export would contain the file blobs, their metadata, trash, versions, shares and all metadata that belongs to the users storage. To prevent group shares from breaking, users in the same groups must be migrated in batch. Depending on the actual group shares in an instance this may effectively require a complete migration in a single batch.
|
||||
The migration happens while the service is offline. File metadata, blobs and share data is exported from ownCloud 10 and imported in oCIS. This can happen user by user, where every user export would contain the file blobs, their metadata, trash, versions, shares and all metadata that belongs to the user's storage. To prevent group shares from breaking, users in the same groups must be migrated in batch. Depending on the actual group shares in an instance this may effectively require a complete migration in a single batch.
|
||||
|
||||
- Good, because oCIS can be tested in a staging system without writing to the production system.
|
||||
- Good, because file layout on disk can be changed to support new storage driver capabilities.
|
||||
@@ -69,7 +69,7 @@ The migration happens in subsequent stages while the service is online.
|
||||
|
||||
- Good, because the admin can migrate users from old to new backend in a controlled way.
|
||||
- Good, because users and admins can learn to trust the new system.
|
||||
- Good, because there can be preparations even long before the migrations happens in parallel on the oC10 codebase, ie. addition of metadata that is needed while the system operates.
|
||||
- Good, because there can be preparations even long before the migrations happens in parallel on the oC10 codebase, i.e. addition of metadata that is needed while the system operates.
|
||||
- Good, because the downtime of the system can be fairly small.
|
||||
- Bad, because it is more complex and might drag on for a long time.
|
||||
|
||||
|
||||
@@ -31,7 +31,7 @@ This API would even allow to provide (WebDAV-) endpoints depending on the kind a
|
||||
- No longer the need to make assumptions about WebDAV- and other routes in clients.
|
||||
- More meta data available about spaces for a better user experience.
|
||||
- Part of the bigger spaces plan.
|
||||
- Important to consider in client migration scenarios, ie. in CERN.
|
||||
- Important to consider in client migration scenarios, i.e. in CERN.
|
||||
|
||||
## Considered Options
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ A simple example is the notification feature for oCIS: Users should receive an e
|
||||
|
||||
* Events are supposed to decouple services and raise flexibility, also considering extensions that are not directly controlled by the ownCloud project.
|
||||
* Events should bring flexibility in the implementation of sending and receiving services.
|
||||
* Events should not obsolete other mechanisms to communicate, ie. grpc calls.
|
||||
* Events should not obsolete other mechanisms to communicate, i.e. grpc calls.
|
||||
* Sending an event has to be as little resource consuming for the sender as possible.
|
||||
* Events are never user visible.
|
||||
|
||||
|
||||
@@ -35,7 +35,7 @@ The `docs` folder contains the source for the [oCIS documentation]({{< ref "../"
|
||||
|
||||
The `deployments` folder contains documented deployment configurations and templates. On a single node, running a single ocis runtime is a resource efficient way to deploy ocis. For multiple nodes docker compose or helm charts for kubernetes examples can be found here.
|
||||
|
||||
The `scripts` folder contains scripts to perform various build, install, analysis, etc operations.
|
||||
The `scripts` folder contains scripts to perform various build, install, analysis, etc. operations.
|
||||
|
||||
## Starting points
|
||||
|
||||
|
||||
Reference in New Issue
Block a user