From a27aae5d1c0a9bfa0b76c01317c5a917a57003be Mon Sep 17 00:00:00 2001
From: Erik Kalkoken <erik.kalkoken@gmail.com>
Date: Sun, 11 Sep 2022 13:48:43 +0000
Subject: [PATCH] Add docs for switching to a non-root installation

---
 docs/installation/index.md              |  1 +
 docs/installation/switch_to_non_root.md | 55 +++++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 docs/installation/switch_to_non_root.md

diff --git a/docs/installation/index.md b/docs/installation/index.md
index 8299b115..f9b43ecb 100644
--- a/docs/installation/index.md
+++ b/docs/installation/index.md
@@ -13,4 +13,5 @@ In addition to main guide for installation Alliance Auth you also find guides fo
     apache
     gunicorn
     upgrade_python
+    switch_to_non_root
 ```
diff --git a/docs/installation/switch_to_non_root.md b/docs/installation/switch_to_non_root.md
new file mode 100644
index 00000000..3ed2fc7b
--- /dev/null
+++ b/docs/installation/switch_to_non_root.md
@@ -0,0 +1,55 @@
+# Switch to non-root
+
+If you followed the official installation guide for Alliance Auth (AA) pre AA 3.x you usually ended up with a "root installation". A root installation means that you have installed AA with the root user and now need to log in as root every time to perform maintenance for AA, e.g. updating existing apps.
+
+Since working as root is [generally not recommended](https://askubuntu.com/questions/16178/why-is-it-bad-to-log-in-as-root), this guide explains how you can easily migrate your existing "root installation" to a "non-root installation".
+
+## How to switch to non-root
+
+We will change the setup so that you can use your `allianceserver` user to perform most maintenance operations. In addition, you also need a sudo user for invoking root privileges, e.g. when restarting the AA services.
+
+The migration itself is rather straightforward. The main idea is to change ownership for all relevant directories and files to `allianceserver`.
+
+First, log in as your sudo user and run the following commands in order:
+
+```shell
+sudo chown -R allianceserver: /home/allianceserver
+sudo chown -R allianceserver: /var/www/myauth
+sudo chmod -r 655 /var/www/myauth
+```
+
+That's it. Your AA installation is now configured to be maintained with the `allianceserver` user.
+
+## How to do maintenance with a non-root user
+
+Here is how you can maintain your AA installation in the future:
+
+First, log in with your sudo user.
+
+Then, switch to the `allianceserver` user:
+
+```shell
+sudo su allianceserver
+```
+
+Go to your home folder and activate your venv:
+
+```shell
+cd ~
+source venv/auth/bin/activate
+```
+
+Finally, switch to the main AA folder, from where you can run most commands directly:
+
+```shell
+cd myauth
+```
+
+When you want to restart myauth, you need to switch back to your sudo user, because `allianceserver` does not have sudo privileges:
+
+```shell
+exit
+sudo supervisorctl restart myauth:
+```
+
+Alternatively, you can open another terminal with your sudo user for restarting myauth. That has the added advantage that you can now continue working with both your allianceauth user and your sudo user for restarts at the same time.