Restructure documentation

changelog.d/5-internal/restructure-docs

@@ -0,0 +1 @@
+Restructure docs.wire.com

docs/.gitignore

@@ -6,3 +6,6 @@ build
 
 # direnv - nix derivation
 result
+
+# this is so that the nix build doesn't copy a dangling symlink
+src/changelog/changelog.md

docs/src/changelog/changelog.md

@@ -0,0 +1 @@
+../../../CHANGELOG.md

docs/src/changelog/index.md

@@ -0,0 +1,9 @@
+# Releases
+
+```{toctree}
+:caption: 'Contents:'
+:glob: true
+:maxdepth: 1
+
+Releases <changelog>
+```

docs/src/conf.py

@@ -136,5 +136,6 @@
         "security-responses/log4shell": "2021-12-15_log4shell.html",
         "security-responses/cve-2021-44521": "2022-02-21_cve-2021-44521.html",
         "security-responses/2022-05_website_outage": "2022-05-23_website_outage.html",
+        "how-to/single-sign-on/index": "../../understand/single-sign-on/index.html",
         "how-to/scim/index": "../../understand/single-sign-on/main.html#user-provisioning"
 }

docs/src/developer/reference/config-options.md

@@ -30,8 +30,7 @@ production.
 
 ### MLS private key paths
 
-Note: This developer documentation. Documentation for site operators can be found here:
-[Messaging Layer Security (MLS)](../../how-to/install/mls.md).
+Note: This developer documentation. Documentation for site operators can be found here: {ref}`mls-message-layer-security`
 
 The `mlsPrivateKeyPaths` field should contain a mapping from *purposes* and
 signature schemes to file paths of corresponding x509 private keys in PEM

docs/src/developer/reference/spar-braindump.md

@@ -1,7 +1,12 @@
 # Spar braindump
 
 Reference: {#SparBrainDump}
-
+/home/stefan/repos/wire-server/docs/src/how-to/install/includes/helm_dns-ingress-troubleshooting.inc.rst:147: WARNING: duplicate label trying things out, other instance in /home/stefan/repos/wire-server/docs/src/how-to/install/helm.md
+/home/stefan/repos/wire-server/docs/src/how-to/install/includes/helm_dns-ingress-troubleshooting.inc.rst:170: WARNING: duplicate label troubleshooting, other instance in /home/stefan/repos/wire-server/docs/src/how-to/install/helm.md
+/home/stefan/repos/wire-server/docs/src/developer/reference/config-options.md:33: WARNING: 'myst' reference target not found: ../../how-to/install/mls.md
+/home/stefan/repos/wire-server/docs/src/developer/reference/spar-braindump.md:116: WARNING: 'myst' reference target not found: ../../how-to/single-sign-on/understand/main.rst
+/home/stefan/repos/wire-server/docs/src/how-to/install/ansible-VMs.md:97: WARNING: undefined label: 'checks'
+/home/stefan/repos/wire-server/docs/src/understand/federation/api.md:162: WARNING: 'myst' reference target not found: ../../how-to/install/mls
 _Author: Matthias Fischmann_
 
 ---
@@ -113,7 +118,8 @@ export IDP_ID=...
 
 Copy the new metadata file to one of your spar instances.
 
-Ssh into it.  If you can't, [the sso docs](../../how-to/single-sign-on/understand/main.rst) explain how you can create a
+
+Ssh into it.  If you can't, {ref}`the sso docs <sso-main-documentation>` explain how you can create a
 bearer token if you have the admin's login credentials.  If you follow
 that approach, you need to replace all mentions of `-H'Z-User ...'`
 with `-H'Authorization: Bearer ...'` in the following, and you won't need

docs/src/how-to/install/index.md

@@ -7,22 +7,22 @@
 How to plan an installation <planning>
 Version requirements <version-requirements>
 dependencies
-(demo) How to install kubernetes <kubernetes>
-(demo) How to install wire-server using Helm <helm>
-(production) Introduction <prod-intro>
-(production) How to install kubernetes and databases <ansible-VMs>
-(production) How to configure AWS services <aws-prod>
-(production) How to install wire-server using Helm <helm-prod>
-(production) How to monitor wire-server <monitoring>
-(production) How to see centralized logs for wire-server <logging>
-Server and team feature settings <team-feature-settings>
-Messaging Layer Security (MLS) <mls>
+
+How to install kubernetes (Demo) <kubernetes>
+How to install wire-server using Helm (Demo) <helm>
+
+Introduction <prod-intro>
+How to install kubernetes and databases <ansible-VMs>
+How to configure AWS services <aws-prod>
+How to install wire-server using Helm <helm-prod>
+Infrastructure configuration <infrastructure-configuration>
+How to monitor wire-server <monitoring>
+How to see centralized logs for wire-server <logging>
+
 Web app settings <web-app-settings>
 sft
 restund
-configure-federation
 tls
-How to install and set up Legal Hold <legalhold>
 Managing authentication with ansible <ansible-authentication>
 Using tinc <ansible-tinc>
 Troubleshooting during installation <troubleshooting>

docs/src/index.md

@@ -15,24 +15,19 @@ The targeted audience of this documentation is:
 
 If you are a developer, you may want to check out the "Notes for developers" first.
 
-This documentation may be expanded in the future to cover other aspects of Wire.
+Release notes of `wire-server` can be found [here](https://github.com/wireapp/wire-server/releases).
 
 ```{toctree}
 :caption: 'Contents:'
 :glob: true
 :maxdepth: 1
 
-Release notes <release-notes>
-
+Security responses <security-responses/index>
+Release Notes <changelog/index>
 Installation <how-to/install/index>
 Administration <how-to/administrate/index>
-Connecting Wire Clients <how-to/associate/index>
-Optional Configuration <configuration-options>
-Understanding wire-server components <understand/index>
-Single-Sign-On and user provisioning <how-to/single-sign-on/index.rst>
-API documentation <understand/api-client-perspective/index>
-Security responses <security-responses/index>
-Notes for developers <developer/index>
+Reference <understand/index>
+Developers Notes <developer/index>
 ```
 
 % Overview <understand/overview>

docs/src/understand/block-user-creation.md

@@ -0,0 +1,34 @@
+# Block personal user creation
+
+## In Brig
+
+There are some unauthenticated end-points that allow arbitrary users on the open internet to do things like create a new team.  This is desired in the cloud, but if you run an on-prem setup that is open to the world, you may want to block this.
+
+Brig has a server option for this:
+
+```yaml
+optSettings:
+  setRestrictUserCreation: true
+```
+
+If `setRestrictUserCreation` is `true`, creating new personal users or new teams on your instance from outside your backend installation is impossible.  (If you want to be more technical: requests to `/register` that create a new personal account or a new team are answered with `403 forbidden`.)
+
+On instances with restricted user creation, the site operator with access to the internal REST API can still circumvent the restriction: just log into a brig service pod via ssh and follow the steps in `hack/bin/create_test_team_admins.sh.`
+
+```{note}
+Once the creation of new users and teams has been disabled, it will still be possible to use the [team creation process](https://support.wire.com/hc/en-us/articles/115003858905-Create-a-team) (enter the new team name, email, password, etc), but it will fail/refuse creation late in the creation process (after the «Create team» button is clicked).
+```
+
+## In the WebApp
+
+Another way of disabling user registration is by this webapp setting, in `values.yaml`, changing this value from `true` to `false`:
+
+```yaml
+FEATURE_ENABLE_ACCOUNT_REGISTRATION: "false"
+```
+
+```{note}
+If you only disable the creation of users in the webapp, but do not do so in Brig/the backend, a malicious user would be able to use the API to create users, so make sure to disable both.
+```
+
+

docs/src/understand/classified-domains.md

@@ -0,0 +1,40 @@
+# Classified Domains
+
+As a backend administrator, if you want to control which other backends (identified by their domain) are "classified",
+
+change the following `galley` configuration in the `value.yaml.gotmpl` file of the wire-server chart:
+
+```yaml
+galley:
+  replicaCount: 1
+  config:
+  ...
+    featureFlags:
+    ...
+      classifiedDomains:
+        status: enabled
+        config:
+          domains: ["domain-that-is-classified.link"]
+          ...
+```
+
+This is not only a `backend` configuration, but also a `team` configuration/feature.
+
+This means that different combinations of configurations will have different results.
+
+Here is a table to navigate the possible configurations:
+
+| Backend Config enabled/disabled | Backend Config Domains                         | Team Config enabled/disabled | Team Config Domains     | User's view                      |
+| ------------------------------- | ---------------------------------------------- | ---------------------------- | ----------------------- | -------------------------------- |
+| Enabled                         | \[domain1.example.com\]                        | Not configured               | Not configured          | Enabled, \[domain1.example.com\] |
+| Enabled                         | \[domain1.example.com\]\[domain1.example.com\] | Enabled                      | Not configured          | Enabled, \[domain1.example.com\] |
+| Enabled                         | \[domain1.example.com\]                        | Enabled                      | \[domain2.example.com\] | Enabled, Undefined               |
+| Enabled                         | \[domain1.example.com\]                        | Disabled                     | Anything                | Undefined                        |
+| Disabled                        | Anything                                       | Not configured               | Not configured          | Disabled, no domains             |
+| Disabled                        | Anything                                       | Enabled                      | \[domain2.example.com\] | Undefined                        |
+
+The table assumes the following:
+
+- When backend level config says that this feature is enabled, it is illegal to not specify domains at the backend level.
+- When backend level config says that this feature is disabled, the list of domains is ignored.
+- When team level feature is disabled, the accompanying domains are ignored.

docs/src/how-to/install/configure-federation.md → docs/src/understand/configure-federation.md

@@ -1,5 +1,5 @@
 (configure-federation)=
-# Configure Wire-Server for Federation
+# Federation
 
 See also {ref}`federation-understand`, which explains the architecture and concepts.
 

docs/src/understand/federation/api.md

@@ -159,7 +159,7 @@ the backend.
 -   `get-user-clients`: Given a list of user ids, return a list of all their clients with public information
 -   `send-connection-action`: Make and also respond to user connection requests
 -   `on-user-deleted-connections`: Notify users that are connected to remote user about that user's deletion
--   `get-mls-clients`: Request all [MLS](../../how-to/install/mls)-capable clients for a given user
+-   `get-mls-clients`: Request all {ref}`MLS <mls-message-layer-security>`-capable clients for a given user
 -   `claim-key-packages`: Claim a previously-uploaded KeyPackage of a remote user. User for adding users to MLS conversations.
 
 See [the brig source

docs/src/understand/index.md

@@ -1,17 +1,19 @@
 (understand)=
 
-# Understanding wire-server components
-
-This section is almost empty, more documentation will come soon...
+# Reference
 
 ```{toctree}
 :glob: true
-:maxdepth: 1
+:maxdepth: 2
 
-Overview </understand/overview.rst>
+Architecture Overview </understand/overview.rst>
+Single Sign-On and User Provisioning <single-sign-on/index>
 Audio/video calling, restund servers (TURN/STUN) </understand/restund.rst>
 Conference Calling 2.0 (SFT) </understand/sft.rst>
 Minio </understand/minio.rst>
 Helm </understand/helm.rst>
 Federation </understand/federation/index.rst>
+Connecting Wire Clients <associate/index>
+Client API documentation <api-client-perspective/index>
+*
 ```

docs/src/how-to/install/mls.md → docs/src/understand/mls.md

@@ -1,3 +1,5 @@
+(mls-message-layer-security)=
+
 # Messaging Layer Security (MLS)
 
 To enable support for [MLS](https://datatracker.ietf.org/wg/mls/documents/)

docs/src/understand/overview.md

@@ -1,6 +1,6 @@
 (overview)=
 
-# Overview
+# Architecture Overview
 
 ## Introduction