mmattel · Oct 27, 2026 · Oct 26, 2026 · Oct 27, 2026
@@ -148,6 +148,23 @@ Some text:
 
 This applies to all list types: unordered (`*`), ordered (`.`), and description lists.
 
+## AsciiDoc Section Heading Spacing
+
+Every section heading (lines starting with one or more `=` followed by a space and text) must be followed by a blank line before its content. This has no effect on rendering but is required for readability of the source file.
+
+Exception: the document title at line 1 followed by document attributes (`:attr: value`) is the AsciiDoc header section — no blank line is needed or wanted there.
+
+```asciidoc
+// Wrong — heading immediately followed by content
+== My Section
+Some text here.
+
+// Correct
+== My Section
+
+Some text here.
+```
+
 ## AsciiDoc Section Heading Capitalisation
 
 All section headings (lines starting with one or more `=` followed by a space) must use **Associated Press (AP) title case**. Use https://headlinecapitalization.com/ (select "AP" style) as the reference tool when writing or reviewing headings.

@@ -9,6 +9,19 @@ nav:
 
 asciidoc:
   attributes:
+    # Audit-tracking attributes: every page that was reviewed or updated for this
+    # version carries `:lastUpdatedVersion: {ocis-audit-version}` and
+    # `:lastUpdatedDate: {ocis-audit-date}` in its header. Centralising the values
+    # here means a single edit covers all pages at once.
+    #
+    # Update these values when you have verified that ALL content that requires a
+    # review has been checked or updated — for example, that Mermaid diagrams,
+    # architecture descriptions and configuration examples are still accurate for
+    # the new version. Do NOT bump these values for purely mechanical edits
+    # (formatting, typo fixes) that do not involve a content review.
+    ocis-audit-version: '9.0.0-rc.1'
+    ocis-audit-date: '2026-10-25'
+
     # used to define the include path for services without trailing /
     # note that any changes of this path also need adjustment in
     # https://github.com/owncloud/ocis-charts/tree/master/charts/ocis/docs

@@ -1,10 +1,18 @@
 = The Infinite Scale Documentation
 :toc: right
 :toclevels: 2
-:description: Welcome to the Infinite Scale documentation. Infinite Scale is a data platform providing tools to integrate, organize, share and govern data and metadata.
+:description: Welcome to the ownCloud Infinite Scale (oCIS) 9.0 documentation: admin setup, configuration, services and developer guides.
+:readingTime: 2
+:level: beginner
+:lastUpdatedVersion: {ocis-audit-version}
+:lastUpdatedDate: {ocis-audit-date}
 
 include::admin:partial$multi-location/compose-version.adoc[]
 
+ownCloud Infinite Scale (oCIS) is a data platform for integrating, organizing, sharing and governing data and metadata. This documentation covers administration, deployment and configuration as well as developer resources for the 9.0 release. Choose the xref:admin:index.adoc[admin] or xref:developer:index.adoc[developer] section to get started.
+
+{readingTime} min read · Level: {level} · Last updated for oCIS {lastUpdatedVersion} on 25.10.2026
+
 == Introduction
 
 {description}
@@ -22,3 +30,17 @@ IMPORTANT: Rolling releases are published in a cycle of 3 weeks. Due to this rel
 == End-User License Agreement (EULA)
 
 ownCloud provides an EULA to clarify, among various topics, who can use this software and which conditions apply to the groups of users defined. See the actual {compose_raw_url}{compose_version}/assets/End-User-License-Agreement-for-ownCloud-Infinite-Scale.pdf[EULA] for details.
+
+== FAQ
+
+=== What Is the Difference Between the Admin and Developer Documentation?
+
+The xref:admin:index.adoc[admin] documentation covers installing, configuring and operating Infinite Scale. The xref:developer:index.adoc[developer] documentation covers building, extending and contributing to oCIS.
+
+=== Where Do I Start as a New Administrator?
+
+Start with the xref:admin:prerequisites/prerequisites.adoc[prerequisites] and the xref:admin:deployment/general/general-info.adoc[general deployment information], then follow the xref:admin:deployment/index.adoc[deployment] guide for your chosen deployment type.
+
+=== Which oCIS Version Is This Documentation For?
+
+This documentation is verified against oCIS `9.0.0-rc.1`. See the xref:admin:deployment/services/env-var-changes.adoc[environment variable changes] page for differences from earlier versions.
@@ -3,6 +3,10 @@
 :toclevels: 4
 :description: This page gives you an overview of the architecture and the concepts behind Infinite Scale. Infinite Scale was designed from the beginning as a data platform providing tools to integrate, organize, share and govern data and metadata.
 :page-aliases: ROOT:architecture/architecture.adoc
+:readingTime: 11
+:level: intermediate
+:lastUpdatedVersion: {ocis-audit-version}
+:lastUpdatedDate: {ocis-audit-date}
 
 :c4-model-url: https://en.wikipedia.org/wiki/C4_model
 :suture-url: https://github.com/thejerf/suture
@@ -16,6 +20,10 @@
 :ocis-pkg-url: https://github.com/owncloud/ocis/tree/master/ocis-pkg
 :go-micro-url: https://github.com/asim/go-micro
 
+This page explains the architecture and core concepts of Infinite Scale, including spaces, the microservice runtime and the request flow. It is for administrators and operators who want to understand how oCIS components interact before deploying or scaling an instance. You should be familiar with microservices and basic networking.
+
+{readingTime} min read · Level: {level} · Last updated for oCIS {lastUpdatedVersion} on 25.10.2026
+
 == Introduction
 
 {description}
@@ -48,6 +56,37 @@ image::architecture/c4-ocis-system-context.svg[Infinite Scale System Context,wid
 
 image::architecture/c4-ocis-system-container.svg[Infinite Scale Container View,width=400]
 
+== Request Flow
+
+The diagram below shows the default request flow for a file access request, verified against a running `v9.0.0-rc.1` instance. The xref:{s-path}/proxy.adoc[proxy] is the single entry point on port `9200`. It authenticates the request and routes it to the service responsible for the request path.
+
+[mermaid, width=600]
+-----
+sequenceDiagram
+    autonumber
+    participant C as Client (Web / Desktop / Mobile)
+    participant P as proxy (:9200)
+    participant A as auth-bearer + idp
+    participant D as ocdav (:9163)
+    participant G as gateway (:9142)
+    participant S as storage-users (:9157, driver ocis)
+    participant F as POSIX filesystem
+    C->>P: HTTPS WebDAV request (/dav/...)
+    P->>A: validate bearer token
+    A-->>P: authenticated user
+    P->>D: forward to ocdav (/dav/, /webdav/, /remote.php/)
+    D->>G: CS3 request (Stat / List / Read)
+    G->>S: CS3 storage call
+    S->>F: read metadata + blob
+    F-->>S: data
+    S-->>G: CS3 response
+    G-->>D: CS3 response
+    D-->>P: WebDAV response
+    P-->>C: HTTPS response
+-----
+
+NOTE: The proxy also routes the Libre Graph API (`/graph`), OCS (`/ocs`), and the Web UI (`/`) to their respective services. Authentication is always performed by the xref:{s-path}/auth-bearer.adoc[auth-bearer] service together with the xref:{s-path}/idp.adoc[idp] service (or an external Identity Provider).
+
 == Concepts
 
 // from https://owncloud.dev/ocis/
@@ -128,4 +167,135 @@ CS3 (Cloud Storage Services for Synchronization and Sharing) is based on {grpc-u
 
 ==== Protocol-Driven Development
 
-Interacting with Infinite Scale involves a multitude af APIs. The server and all clients rely on {oidc-url}[OpenID Connect] for authentication. The embedded LibreGraph Connect can be replaced with any other OpenID Connect Identity Provider. Clients use the {webdav-url}[WebDAV]-based https://github.com/cernbox/smashbox/blob/master/protocol/protocol.md[ownCloud sync protocol] to manage files and folders, Open Collaboration Services (OCS) to manage shares and https://tus.io/protocols/resumable-upload.html[TUS] to upload files in a resumable way. On the server side, REVA is the reference implementation of the https://github.com/cs3org/cs3apis[CS3APIS], which are defined using protocol buffers. By embedding Go-lang LDAP Authentication (GLAuth), Infinite Scale provides a read-only LDAP interface to make accounts, including guests, available to firewalls and other systems.
+Interacting with Infinite Scale involves a multitude of APIs. The server and all clients rely on {oidc-url}[OpenID Connect] for authentication. The embedded LibreGraph Connect can be replaced with any other OpenID Connect Identity Provider. Clients use the {webdav-url}[WebDAV]-based https://github.com/cernbox/smashbox/blob/master/protocol/protocol.md[ownCloud sync protocol] to manage files and folders, Open Collaboration Services (OCS) to manage shares and https://tus.io/protocols/resumable-upload.html[TUS] to upload files in a resumable way. On the server side, REVA is the reference implementation of the https://github.com/cs3org/cs3apis[CS3APIS], which are defined using protocol buffers. By embedding the xref:{s-path}/idm.adoc[IDM service] (based on LibreGraph Identity Management), Infinite Scale provides an LDAP interface to make accounts, including guests, available to firewalls and other systems.
+
+== Deployment Models
+
+Infinite Scale can be deployed as a **single binary** (`ocis server`), with **Docker Compose**, or on **Kubernetes** using the oCIS Helm chart. Because every option is an environment variable, the configuration is identical across deployment types. The deployment type mainly determines whether services can be scaled out and how they discover each other and exchange events.
+
+=== Service Discovery and Events
+
+By default, services register in a NATS JetStream key-value store (registry type `nats-js-kv`, set via `MICRO_REGISTRY`) and exchange events over the same NATS server (`OCIS_EVENTS_ENDPOINT`, default `127.0.0.1:9233`). In a single binary the embedded NATS server provides both. In a Compose or Helm deployment a shared NATS server provides both across all replicas.
+
+[mermaid, width=700]
+-----
+flowchart TB
+    subgraph SB["Single binary (ocis server)"]
+        direction TB
+        N1["embedded NATS (:9233)<br/>registry: nats-js-kv - events"]
+        P1["proxy"] --- N1
+        D1["ocdav"] --- N1
+        G1["gateway"] --- N1
+        S1["storage-users"] --- N1
+    end
+
+    subgraph DC["Docker Compose / Helm (Kubernetes)"]
+        direction TB
+        N2["shared NATS JetStream<br/>registry: nats-js-kv - events"]
+        P2["proxy (replicas)"] --- N2
+        D2["ocdav (replicas)"] --- N2
+        G2["gateway (replicas)"] --- N2
+        S2["storage-users (replicas)"] --- N2
+    end
+-----
+
+NOTE: The in-memory registry (`MICRO_REGISTRY=memory`) only works inside a single process and is intended for development, not for production or scale-out deployments.
+
+=== Storage Drivers
+
+The `storage-users` service supports different storage drivers, selected with `STORAGE_USERS_DRIVER`:
+
+[mermaid, width=600]
+-----
+flowchart LR
+    G["gateway"] --> SU["storage-users"]
+    SU -->|"driver: ocis (default)"| POSIX[("POSIX volume<br/>metadata + blobs")]
+    SU -->|"driver: s3ng"| S3[("S3 bucket (blobs)")]
+    SU -->|"driver: s3ng"| POSIX2[("POSIX volume (metadata)")]
+-----
+
+=== Configurable Components: Pro and Cons per Deployment Type
+
+The defaults below are identical for the single binary, Docker Compose and Helm deployments because configuration is environment-variable based. The deployment type only changes whether a component can scale out: a single binary cannot scale individual services, while Compose and Helm can scale replicas that share a registry and event bus.
+
+[width="100%",cols="~,~,~,~",options="header"]
+|===
+| Component / Option
+| Good for
+| Drawbacks
+| Default and when to use
+
+| Service registry: `nats-js-kv` (NATS JetStream key-value)
+| Distributed service discovery across replicas and nodes.
+| Needs a reachable NATS server; adds a lookup hop.
+| Default in all deployment types. Use everywhere except single-process development.
+
+| Service registry: `memory` (in-memory)
+| Zero configuration, no external dependency.
+| Only works within one process; no discovery across replicas.
+| Not a production default. Development and testing only.
+
+| Storage driver: `ocis` (POSIX / decomposedfs)
+| Simple, no external object store; metadata and blobs on a POSIX volume.
+| Scales with the filesystem; no native object-store redundancy.
+| Default in all deployment types. Use for small to medium deployments on POSIX storage.
+
+| Storage driver: `s3ng` (S3 blobs + POSIX metadata)
+| Blobs on scalable, redundant S3-compatible object storage.
+| Needs an S3 endpoint and credentials; metadata stays on POSIX.
+| Not a default. Use when S3 storage is configured, for large or geo-distributed deployments.
+
+| Storage driver: `owncloudsql`
+| Legacy ownCloud SQL storage.
+| Deprecated; not for new deployments.
+| Deprecated. Do not use for new deployments.
+
+| Cache store: `memory`
+| Best performance, no external dependency.
+| No persistence; lost on restart; per-instance only.
+| Default for caches. Use only where persistence and scale-out are not required.
+
+| Cache store: `nats-js-kv`
+| Shared, persistent cache across replicas.
+| Needs a reachable NATS server.
+| Default for persistent stores. Use for scale-out deployments.
+
+| Cache store: `redis-sentinel`
+| Shared, persistent, HA cache on Redis.
+| Extra Redis Sentinel infrastructure to operate.
+| Not a default. Use when a Redis Sentinel cluster is already available.
+
+| Cache store: `noop`
+| Disables caching entirely.
+| No caching benefit; higher load on backends.
+| Not a default. Use only for debugging.
+
+| Identity: embedded `idp` + `idm`
+| Zero-configuration OIDC and LDAP out of the box.
+| Limited functionality; for small installations and testing.
+| Default in all deployment types. Use for small environments.
+
+| Identity: external IdP (e.g. Keycloak) + LDAP
+| Enterprise features: 2FA, federation, user provisioning.
+| Additional components to operate and secure.
+| Not a default. Use for production and enterprise environments.
+
+|===
+
+== FAQ
+
+=== What Is the Single Entry Point for Client Requests?
+
+The xref:{s-path}/proxy.adoc[proxy] service on port `9200` is the single entry point. It terminates TLS, authenticates requests and routes them to the responsible backend service.
+
+=== How Do Services Find Each Other?
+
+Services register in a NATS JetStream key-value store (registry type `nats-js-kv`). See the xref:deployment/services/registry.adoc[Registry] page for details and the available registry types.
+
+=== Can I Scale Individual Services?
+
+Yes, in a Docker Compose or Kubernetes deployment you can run multiple replicas of a service. A single binary runs all services in one process and cannot scale individual services. See the xref:availability_scaling/availability_scaling.adoc[availability and scaling] page.
+
+=== Which Storage Driver Should I Use?
+
+Use the default `ocis` driver (POSIX / decomposedfs) for small to medium deployments. Use the `s3ng` driver when you want blobs on S3-compatible object storage. See the xref:deployment/storage/general-considerations.adoc[storage considerations] page.
@@ -1,7 +1,15 @@
 = General Information
 :toc: right
-:description: This document covers general aspects of Infinite Scale like start modes, services, important minimum configuration etc. for a common understanding.
+:description: General Infinite Scale concepts: start modes, the embedded supervisor, managing and configuring services, and the base data directory.
 :page-aliases: ROOT:deployment/general/general-info.adoc
+:readingTime: 19
+:level: beginner
+:lastUpdatedVersion: {ocis-audit-version}
+:lastUpdatedDate: {ocis-audit-date}
+
+This page covers the general concepts of Infinite Scale that apply regardless of how you deploy it: start modes, the embedded supervisor, how to manage and configure services, and where data is stored. It is for administrators setting up or operating an instance. We recommend reading it before you start a deployment.
+
+{readingTime} min read · Level: {level} · Last updated for oCIS {lastUpdatedVersion} on 25.10.2026
 
 == Introduction
 
@@ -721,3 +729,21 @@ include::partial$multi-location/idm-https-reverse-proxy.adoc[]
 == Maintenance Commands
 
 There are multiple commands available to maintain the Infinite Scale instance. See the xref:maintenance/commands/commands.adoc[Maintenance Commands] document for more details.
+
+== FAQ
+
+=== What Is the Difference Between Supervised and Unsupervised Services?
+
+Supervised services are started together by the embedded runtime with `ocis server` and share one process. Unsupervised services are started individually with `ocis <service-name> server` and run as separate processes that you manage yourself.
+
+=== How Do I Start Only a Subset of Services?
+
+Use the `OCIS_ADD_RUN_SERVICES` environment variable (to add services) or `OCIS_EXCLUDE_RUN_SERVICES` (to exclude services) when starting `ocis server`. See the xref:{s-path}/services_rules.adoc[Services Rules] page.
+
+=== Where Is the Infinite Scale Data Stored?
+
+In the base data directory, which defaults to `~/.ocis` (single binary) or `/var/lib/ocis` (container). See the Base Data Directory section above. Note that Infinite Scale does not use a database.
+
+=== Which Command Lists the Running Services?
+
+Run `ocis list` to list the services running in supervised mode. See the xref:maintenance/commands/commands.adoc[Maintenance Commands] page for all maintenance commands.
@@ -1,12 +1,32 @@
 = Deployment
 :toc: right
-:description: There are several deployment options for Infinite Scale available. Consider which one serves your purposes best. Generally speaking, you can decide between using containers or manually set up a regular server.
+:description: Overview of the Infinite Scale deployment options: single binary, Docker Compose and Kubernetes with the oCIS Helm chart.
 :page-aliases: ROOT:deployment/index.adoc
+:readingTime: 2
+:level: beginner
+:lastUpdatedVersion: {ocis-audit-version}
+:lastUpdatedDate: {ocis-audit-date}
 
-{description}
+Infinite Scale can be deployed as a single binary, with Docker Compose, or on Kubernetes using the oCIS Helm chart. This page helps you choose the deployment option that fits your environment and points you to the right setup guides. No prior oCIS experience is required.
+
+{readingTime} min read · Level: {level} · Last updated for oCIS {lastUpdatedVersion} on 25.10.2026
 
 * The xref:deployment/general/general-info.adoc[General Info] section summarizes general and important information which is not dependent on the way that you install Infinite Scale. Any setup refers to this general information as prerequisite knowledge.
 
 * The next steps will likely be mounting a xref:deployment/storage/nfs.adoc[Network File System] and managing xref:deployment/services/services.adoc[Services].
 
 * xref:deployment/security/security.adoc[Securing Infinite Scale] should be a primary concern after you've set up your server.
+
+== FAQ
+
+=== Which Deployment Option Should I Choose?
+
+Use the **single binary** for a quick start or small installation. Use **Docker Compose** for a containerized single-node setup. Use **Kubernetes with the oCIS Helm chart** when you need to scale services across multiple nodes.
+
+=== Do the Configuration Options Differ Between Deployment Types?
+
+No. Infinite Scale is configured entirely through environment variables, so the same options apply to the single binary, Docker Compose and Helm deployments. The deployment type only changes how services are run and scaled. See xref:deployment/services/env-var-note.adoc[Notes for Environment Variables].
+
+=== Where Can I Find the List of Default Ports?
+
+See the xref:deployment/services/ports-used.adoc[Ports Used] page for the default port ranges of every service.