From 45319b24cd4ae148de4cba55725a5a74501ecfb7 Mon Sep 17 00:00:00 2001
From: lonix1 <40320097+lonix1@users.noreply.github.com>
Date: Fri, 7 Jul 2023 05:31:19 +0200
Subject: [PATCH] docs: user registration (#1925)

Further to discussion on [discord](https://discord.com/channels/838698813463724034/838698813463724037/1125412378125803612).

The docs should be clearer about:
- user registration in general, and
- preventing registration of random users but allowing specific ones.

---------

Co-authored-by: 6543 <6543@obermui.de>
---
 .../30-administration/10-server-config.md     | 42 +++++++++++++++++--
 1 file changed, 38 insertions(+), 4 deletions(-)

diff --git a/docs/docs/30-administration/10-server-config.md b/docs/docs/30-administration/10-server-config.md
index 78099caa9..40586a95c 100644
--- a/docs/docs/30-administration/10-server-config.md
+++ b/docs/docs/30-administration/10-server-config.md
@@ -2,10 +2,45 @@
 
 ## User registration
 
-Registration is closed by default. While disabled an administrator needs to add new users manually (exp. `woodpecker-cli user add`).
+Woodpecker does not have its own user registry; users are provided from your [forge](./11-forges/10-overview.md) (using OAuth2).
 
-If registration is open every user with an account at the configured [forges](./11-forges/10-overview.md) can login to Woodpecker.
-This example enables open registration for users that are members of approved organizations:
+Registration is closed by default (`WOODPECKER_OPEN=false`). If registration is open (`WOODPECKER_OPEN=true`) then every user with an account at the configured forge can login to Woodpecker.
+
+To open registration:
+
+```diff
+# docker-compose.yml
+version: '3'
+
+services:
+  woodpecker-server:
+    [...]
+    environment:
+      - [...]
++     - WOODPECKER_OPEN=true
+```
+
+You can **also restrict** registration, by keep registration closed and ...  
+... **adding** new **users manually** via the CLI: `woodpecker-cli user add`, or  
+... allowing specific **admin users** via the `WOODPECKER_ADMIN` setting, or  
+by open registration and **filter by organization** membership through the `WOODPECKER_ORGS` setting.
+
+### To close registration, but allow specific admin users
+
+```diff
+# docker-compose.yml
+version: '3'
+
+services:
+  woodpecker-server:
+    [...]
+    environment:
+      - [...]
++     - WOODPECKER_OPEN=false
++     - WOODPECKER_ADMIN=johnsmith,janedoe
+```
+
+### To only allow registration of users, who are members of approved organizations
 
 ```diff
 # docker-compose.yml
@@ -18,7 +53,6 @@ services:
       - [...]
 +     - WOODPECKER_OPEN=true
 +     - WOODPECKER_ORGS=dolores,dogpatch
-
 ```
 
 ## Administrators