Skip to content

Commit bd6437b

Browse files
mmattelmmattel
authored
Merge pull request #11824 from owncloud/dev_docs_add_new_sections
[docs-only] Add new sections to dev-docs
2 parents 2c2e868 + eac0d5d commit bd6437b

File tree

9 files changed

+355
-36
lines changed

9 files changed

+355
-36
lines changed

‎docs/cli-commands/_index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: oCIS CLI Commands
3+
date: 2025-11-13T00:00:00+00:00
4+
geekdocRepo: https://github.com/owncloud/ocis
5+
geekdocEditPath: edit/master/docs/cli-commands/
6+
geekdocFilePath: _index.md
7+
geekdocCollapseSection: true
8+
weight: 20
9+
---
10+
11+
{{< toc-tree >}}
12+
13+
CLI commands can either be embedded in a service or operate independently.
14+

‎docs/cli-commands/create-new-cli-command.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: Create a New CLI Command
3+
date: 2025-11-13T00:00:00+00:00
4+
geekdocRepo: https://github.com/owncloud/ocis
5+
geekdocEditPath: edit/master/docs/cli-commands/
6+
geekdocFilePath: create-new-cli-command.md
7+
weight: 20
8+
---
9+
10+
{{< toc >}}
11+
12+
{{< hint info >}}
13+
Existing commands should be checked for commonly used options whenever a new CLI command is created, regardless of whether it is embedded in a service or not. For an example you can see the [Service Independent CLI]({{< ref "./service_independent_cli.md" >}}) documentation.
14+
{{< /hint >}}
15+
16+
## CLI Embedded in a Service
17+
18+
These commands are usually located in the `<service-name>/pkg/command` subfolder.
19+
20+
## CLI Independent of a Service
21+
22+
These commands are located in the `ocis/pkg/command` subfolder.

‎docs/cli-commands/document-cli-commands.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Document CLI Commands
3+
date: 2025-11-13T00:00:00+00:00
4+
geekdocRepo: https://github.com/owncloud/ocis
5+
geekdocEditPath: edit/master/docs/cli-commands/
6+
geekdocFilePath: document-cli-commands.md
7+
weight: 20
8+
---
9+
10+
{{< toc >}}
11+
12+
Any CLI command that is added to Infinite Scale must be documented here in the dev docs and the [admin docs](https://doc.owncloud.com/ocis/latest/maintenance/commands/commands.html). Note that the admin docs primarily distinguish between online and offline commands because the structure of the documentation is different. Typically, any command documented in the developer documentation is integrated into the admin documentation and adapted according to the target audience. The description here is for developers; the admin docs are derived from it.
13+
14+
{{< hint info >}}
15+
Note that any CLI command requires documentation. However, it may be decided that a CLI command will not be included in the admin documentation. In such a case, the reasons should be valid.
16+
{{< /hint >}}
17+
18+
## Type of CLI Commands
19+
20+
There are three types of CLI commands that require different documentation locations:
21+
22+
1. Commands that are embedded in a service such as:\
23+
`ocis storage-users uploads`
24+
2. Commands that are service independent such as:\
25+
`ocis trash purge-empty-dirs` or `ocis revisions purge`
26+
3. `curl` commands that can be one of the above.
27+
28+
## Rules
29+
30+
* **Service dependent** CLI commands:\
31+
Add any CLI command into the repsective `README.md` **of the service**. Use as "template" an existing one such as in `services/storage-users/README.md` or `services/auth-app/README.md`. The content created will be transferred automatically to the service in the [Services]({{< ref "../services/" >}}) section.
32+
* **Service independent** CLI commands:\
33+
Add any CLI command into the [Service Independent CLI]({{< ref "./service_independent_cli.md" >}}) documentation. See the link for an example how to do so.

‎docs/cli-commands/service_dependent_cli.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Service Dependent CLI
3+
date: 2025-11-13T00:00:00+00:00
4+
geekdocRepo: https://github.com/owncloud/ocis
5+
geekdocEditPath: edit/master/docs/cli-commands/
6+
geekdocFilePath: service_dependent_cli.md
7+
---
8+
9+
This document describes ocis CLI commands that are **embedded in a service**.
10+
11+
{{< toc >}}
12+
13+
## Common Parameters
14+
15+
The ocis package offers a variety of CLI commands for monitoring or repairing ocis installations. Most of these commands have common parameters such as:
16+
17+
* `--help` (or `-h`)\
18+
Use to print all available options.
19+
20+
* `--basePath` (or `-p`)\
21+
Needs to point to a storage provider, paths can vary depending on your ocis installation. Example paths are:
22+
```bash
23+
.ocis/storage/users # bare metal installation
24+
/var/tmp/ocis/storage/users # docker installation
25+
...
26+
```
27+
28+
* `--dry-run`\
29+
This parameter, when available, defaults to `true` and must explicitly set to `false`.
30+
31+
* `--verbose` (or `-v`)\
32+
Get a more verbose output.
33+
34+
## List of CLI Commands
35+
36+
For CLI commands that are **embedded in a service**, see the following services:
37+
38+
* [Auth-App]({{< ref "../services/auth-app/" >}})
39+
* [Graph]({{< ref "../services/graph/" >}})
40+
* [Postprocessing]({{< ref "../services/postprocessing/" >}})
41+
* [Storage-Users]({{< ref "../services/storage-users/" >}})

‎docs/cli-commands/service_independent_cli.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Service Independent CLI
3+
date: 2025-11-13T00:00:00+00:00
4+
geekdocRepo: https://github.com/owncloud/ocis
5+
geekdocEditPath: edit/master/docs/cli-commands/
6+
geekdocFilePath: service_independent_cli.md
7+
---
8+
9+
This document describes ocis CLI commands that are **service independent**.
10+
11+
{{< toc >}}
12+
13+
For **service dependent** CLI commands, see the following services:
14+
15+
* [Auth-App]({{< ref "../services/auth-app/" >}})
16+
* [Graph]({{< ref "../services/graph/" >}})
17+
* [Postprocessing]({{< ref "../services/postprocessing/" >}})
18+
* [Storage-Users]({{< ref "../services/storage-users/" >}})
19+
20+
## Common Parameters
21+
22+
The ocis package offers a variety of CLI commands for monitoring or repairing ocis installations. Most of these commands have common parameters such as:
23+
24+
* `--help` (or `-h`)\
25+
Use to print all available options.
26+
27+
* `--basePath` (or `-p`)\
28+
Needs to point to a storage provider, paths can vary depending on your ocis installation. Example paths are:
29+
```bash
30+
.ocis/storage/users # bare metal installation
31+
/var/tmp/ocis/storage/users # docker installation
32+
...
33+
```
34+
35+
* `--dry-run`\
36+
This parameter, when available, defaults to `true` and must explicitly set to `false`.
37+
38+
* `--verbose` (or `-v`)\
39+
Get a more verbose output.
40+
41+
## List of CLI Commands
42+
43+
### Backup CLI
44+
45+
The backup command allows inspecting the consistency of an ocis storage:
46+
47+
```bash
48+
ocis backup consistency -p /base/path/storage/users
49+
```
50+
51+
This will check the consistency of the storage and output a list of inconsistencies. Inconsistencies can be:
52+
53+
* **Orphaned Blobs**\
54+
A blob in the blobstore that is not referenced by any file metadata.
55+
* **Missing Blobs**\
56+
A blob referenced by file metadata that is not present in the blobstore.
57+
* **Missing Nodes**\
58+
A node that is referenced by a symlink but doesn't exist.
59+
* **Missing Link**\
60+
A node that is not referenced by any symlink but should be.
61+
* **Missing Files**\
62+
A node that is missing essential files (such as the `.mpk` metadata file).
63+
* **Missing/Malformed Metadata**\
64+
A node that doesn't have any (or malformed) metadata.
65+
66+
This command provides additional options:
67+
68+
* `-b` / `--blobstore`\
69+
Allows specifying the blobstore to use. Defaults to `ocis`. Empty blobs will not be checked. Can also be switched to `s3ng`, but needs addtional envvar configuration (see the `storage-users` service for more details).
70+
* `--fail`\
71+
Exits with non-zero exit code if inconsistencies are found. Useful for automation.
72+
73+
### Cleanup Orphaned Shares
74+
75+
When a shared space or directory got deleted, use the `shares cleanup` command to remove those share orphans. This can't be done automatically at the moment.
76+
77+
```bash
78+
ocis shares cleanup
79+
```
80+
81+
### List Unified Roles
82+
83+
This command simplifies the process of finding out which UID belongs to which role. The command using markdown as output format is:
84+
85+
```bash
86+
ocis graph list-unified-roles --output-format md
87+
```
88+
89+
The output of this command includes the following information for each role:
90+
91+
* `Name`\
92+
The human readable name of the role.
93+
* `UID`\
94+
The unique identifier of the role.
95+
* `Enabled`\
96+
Whether the role is enabled or not.
97+
* `Description`\
98+
A short description of the role.
99+
* `Condition`
100+
* `Allowed Resource Actions`
101+
102+
**Example output (shortned)**
103+
104+
| # | LABEL | UID | ENABLED | DESCRIPTION | CONDITION | ALLOWED RESOURCE ACTIONS |
105+
|:--:|:--------------------------------:|:------------------------------------:|:--------:|:------------------------------------------------------------------------------------:|:---------------------------------------------------------:|:----------------------------------------:|
106+
| 1 | Viewer | b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 | enabled | View and download. | exists @Resource.File | libre.graph/driveItem/path/read |
107+
| | | | | | exists @Resource.Folder | libre.graph/driveItem/quota/read |
108+
| | | | | | exists @Resource.File && @Subject.UserType=="Federated" | libre.graph/driveItem/content/read |
109+
| | | | | | exists @Resource.Folder && @Subject.UserType=="Federated" | libre.graph/driveItem/children/read |
110+
| | | | | | | libre.graph/driveItem/deleted/read |
111+
| | | | | | | libre.graph/driveItem/basic/read |
112+
| 2 | ViewerListGrants | d5041006-ebb3-4b4a-b6a4-7c180ecfb17d | disabled | View, download and show all invite
113+
114+
<!--
115+
### Move Stuck Uploads
116+
117+
In some cases of saturated disk usage, Infinite Scale metadata may become stuck. This can occur when file metadata is being moved to its final destination after file operations. This issue was primarily seen with shares, where uploaded files could not be accessed. The required filename parameter aligns with Infinite Scale's internal processes and is used to complete the formerly stuck move action.
118+
119+
```bash
120+
ocis shares move-stuck-upload-blobs [--dry-run=false] -p /base/path/storage/users
121+
```
122+
123+
This command provides additional options:
124+
125+
* `--dry-run` (default: `true`)\
126+
Only print found files stuck in transition.\
127+
Note: This is a safety measure. You must specify `--dry-run=false` for the command to be effective.
128+
129+
* `--filename` value (default: "received.json")\
130+
File to move from `uploads/` to share manager metadata `blobs/`
131+
-->
132+
133+
### Revisions CLI
134+
135+
The revisions command allows removing the revisions of files in the storage.
136+
137+
```bash
138+
ocis revisions purge -p /base/path/storage/users
139+
```
140+
141+
It takes the `--resource-id` (or `--r`) parameter which specify the scope of the command:
142+
143+
* An empty string (default) removes all revisions from all spaces.
144+
* A spaceID (like `d419032c-65b9-4f4e-b1e4-0c69a946181d\$44b5a63b-540c-4002-a674-0e9c833bbe49`) removes all revisions in that space.
145+
* A resourceID (e.g. `d419032c-65b9-4f4e-b1e4-0c69a946181d\$44b5a63b-540c-4002-a674-0e9c833bbe49\!e8a73d49-2e00-4322-9f34-9d7f178577b2`) removes all revisions from that specific file.
146+
147+
This command provides additional options:
148+
149+
* `--dry-run` (default: `true`)\
150+
Do not remove any revisions but print the revisions that would be removed.
151+
* `-b` / `--blobstore`\
152+
Allows specifying the blobstore to use. Defaults to `ocis`. Can be switched to `s3ng` but needs addtional envvar configuration (see the `storage-users` service for more details).
153+
* `-v` / `--verbose`\
154+
Prints additional information about the revisions that are removed.
155+
* `--glob-mechanism` (default: `glob`\
156+
(advanced) Allows specifying the mechanism to use for globbing. Can be `glob`, `list` or `workers`. In most cases the default `glob` does not need to be changed. If large spaces need to be purged, `list` or `workers` can be used to improve performance at the cost of higher cpu and ram usage. `list` will spawn 10 threads that list folder contents in parallel. `workers` will use a special globbing mechanism and multiple threads to achieve the best performance for the highest cost.
157+
158+
### Service Health
159+
160+
The service health CLI command allows checking the health status of a service. If there are no issues found, nothing health related will get printed.
161+
162+
```bash
163+
ocis <service-name> health
164+
```
165+
166+
**Examples**
167+
168+
* The `collaboration` service has been started but not configured and is therefore not in a healthy state:
169+
```bash
170+
ocis collaboration health
171+
172+
The WOPI secret has not been set properly in your config for collaboration. Make sure your /root/.ocis/config config contains the proper values (e.g. by using 'ocis init --diff' and applying the patch or setting a value manually in the config/corresponding environment variable).
173+
```
174+
175+
* The `antivirus` service has not been started, the health check responds accordingly:
176+
```bash
177+
ocis antivirus health
178+
179+
{"level":"fatal","service":"antivirus","error":"Get \"http://127.0.0.1:9277/healthz\": dial tcp 127.0.0.1:9277: connect: connection refused","time":"2024-10-28T17:47:54+01:00","message":"Failed to request health check"}
180+
```
181+
182+
### Trash CLI
183+
184+
The trash cli allows removing empty folders from the trashbin. This should be used to speed up trash bin operations.
185+
186+
```bash
187+
ocis trash purge-empty-dirs -p /base/path/storage/users
188+
```
189+
190+
This command provides additional options:
191+
192+
* `--dry-run` (default: `true`)\
193+
Do not remove any empty folders but print the empty folders that would be removed.

‎docs/service-independent/_index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: Service Independent Settings
3+
date: 2025-11-13T00:00:00+00:00
4+
geekdocRepo: https://github.com/owncloud/ocis
5+
geekdocEditPath: edit/master/docs/service-independent/
6+
geekdocFilePath: _index.md
7+
geekdocCollapseSection: true
8+
weight: 15
9+
---
10+
11+
{{< toc-tree >}}
12+
13+
Some components programmed are not bound to a service but are valid for all of ocis. These are for example environment variables that are used before any service gets started. For ocis CLI commands that are service independent, see the [Service Independent CLI]({{< ref "../cli-commands/service_independent_cli.md" >}}) documentation.

‎docs/service-independent/service_independent_envvars.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Service Independent Envvars
3+
date: 2025-11-13T00:00:00+00:00
4+
geekdocRepo: https://github.com/owncloud/ocis
5+
geekdocEditPath: edit/master/docs/service-independent/
6+
geekdocFilePath: service_independent_envvars.md
7+
---
8+
9+
The following environment variables are service independent. You will find the respective code in the `ocis-pkg/` directory. See the [Admin Documentation - Environment Variables with Special Scopes](https://doc.owncloud.com/ocis/7.3/deployment/services/env-vars-special-scope.html) for a comprehensive list and explanation.
10+
11+
{{< toc >}}
12+
13+
{{< hint info >}}
14+
See the [Environment Variables]({{< ref "../services/general-info/envvars/" >}}) documentation for common and important details on envvars.
15+
{{< /hint >}}
16+
17+
## Service Registry
18+
19+
This package configures the service registry which will be used to look up for example the service addresses.
20+
21+
Available registries are:
22+
23+
- nats-js-kv (default)
24+
- memory
25+
26+
To configure which registry to use, you have to set the environment variable `MICRO_REGISTRY`, and for all except `memory` you also have to set the registry address via `MICRO_REGISTRY_ADDRESS` and other envvars.
27+
28+
## Startup Related Envvars
29+
30+
These envvars define the startup of ocis and can for example add or remove services from the startup process such as `OCIS_ADD_RUN_SERVICES`.
31+
32+
## Memory Limits
33+
34+
{{< hint info >}}
35+
Note that this envvar is for development purposes only and not described in the admin docs.
36+
{{< /hint >}}
37+
38+
oCIS will automatically set the go native `GOMEMLIMIT` to `0.9`. To disable the limit set `AUTOMEMLIMIT=off`. For more information take a look at the official [Guide to the Go Garbage Collector](https://go.dev/doc/gc-guide).

‎docs/services/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
22
title: Services
33
date: 2023-12-06T13:00:00+01:00
4-
weight: 10
54
geekdocRepo: https://github.com/owncloud/ocis
65
geekdocEditPath: edit/master/docs/services/
76
geekdocFilePath: _index.md
87
geekdocCollapseSection: true
8+
weight: 10
99
---
1010

1111
The documentation of services is intended for developers and only reflects the state of the master branch of the ocis repo.

0 commit comments

Comments
 (0)