Super user documentation (#286)

* Super user documentation * Added guide for creating super user * Minor changes * Add reference in index file * Apply suggestions from code review Formating changes, Co-authored-by: Jeremy-Prior <[email protected]> --------- Co-authored-by: Jeremy-Prior <[email protected]>
kartoza · Jan 24, 2024 · fbd99cf · fbd99cf
1 parent 6afafb4
commit fbd99cf
Show file tree

Hide file tree

Showing 15 changed files with 92 additions and 1 deletion.
diff --git a/docs/src/administrator/guide/img/superuser-1.png b/docs/src/administrator/guide/img/superuser-1.png
diff --git a/docs/src/administrator/guide/img/superuser-2.png b/docs/src/administrator/guide/img/superuser-2.png
diff --git a/docs/src/administrator/guide/img/superuser-3.png b/docs/src/administrator/guide/img/superuser-3.png
diff --git a/docs/src/administrator/guide/img/superuser-4.png b/docs/src/administrator/guide/img/superuser-4.png
diff --git a/docs/src/administrator/guide/img/superuser-5.png b/docs/src/administrator/guide/img/superuser-5.png
diff --git a/docs/src/administrator/guide/img/superuser-6.png b/docs/src/administrator/guide/img/superuser-6.png
diff --git a/docs/src/administrator/guide/index.md b/docs/src/administrator/guide/index.md
@@ -134,4 +134,42 @@ To access the `Usage Statistics`, click on the profile icon in the top navigatio
 
 **Navigation Tip:**
 
-Users can easily access detailed information by clicking on the name of the respective table in the `Usage Statistics` section. Additionally, they can scroll through the tables to explore the variety of insights available at a glance.
+Users can easily access detailed information by clicking on the name of the respective table in the `Usage Statistics` section. Additionally, they can scroll through the tables to explore the variety of insights available at a glance.
+
+## Creating a SuperUser
+
+- Open the terminal.
+
+Run ```docker exec -ti saeoss_ckan-web_1 poetry run ckan sysadmin add admin```
+
+![create superuser command](./img/superuser-1.png)
+
+The user is expected to input either `Y` for Yes or `n` for No based on their intention to create a superuser.
+
+![confirmation](./img/superuser-2.png)
+
+Enter the required information for creating the superuser account
+
+![enter information](./img/superuser-3.png)
+
+## Converting a Normal User to a SuperUser
+
+```bash
+docker exec -ti saeoss_ckan-web_1 poetry run ckan sysadmin add <username>
+```
+Replace the `username` with the desired user's username.
+
+![convert the normal user to a super user](./img/superuser-4.png)
+
+Before the superuser privileges
+
+![Bob002 as a normal user](./img/superuser-5.png)
+
+After the superuser privileges
+
+![Bob002 as a superuser](./img/superuser-6.png)
+
+**Security Tips:**
+
+- Keep SuperUser credentials secure.
+- Regularly update SuperUser credentials for enhanced security.
diff --git a/docs/src/administrator/manual/img/super-user-1.png b/docs/src/administrator/manual/img/super-user-1.png
diff --git a/docs/src/administrator/manual/img/super-user-2.png b/docs/src/administrator/manual/img/super-user-2.png
diff --git a/docs/src/administrator/manual/img/super-user-3.png b/docs/src/administrator/manual/img/super-user-3.png
diff --git a/docs/src/administrator/manual/img/super-user-4.png b/docs/src/administrator/manual/img/super-user-4.png
diff --git a/docs/src/administrator/manual/img/super-user-5.png b/docs/src/administrator/manual/img/super-user-5.png
diff --git a/docs/src/administrator/manual/img/super-user-6.png b/docs/src/administrator/manual/img/super-user-6.png
diff --git a/docs/src/administrator/manual/index.md b/docs/src/administrator/manual/index.md
@@ -20,6 +20,7 @@ The administrator manual aims to assist user in learning the fundamentals of usi
 - [**About**]()
 - [**Help**]()
 - [**Usage Statistics**](./usage-statistics.md)
+- [**Create SuperUser**](./super-user.md)
 
 ### Error reporting
 

diff --git a/docs/src/administrator/manual/super-user.md b/docs/src/administrator/manual/super-user.md
@@ -0,0 +1,52 @@
+# Documentation: Creating SuperUser
+
+## Creating SuperUser from Terminal
+
+To create a superuser, open the terminal.
+Use the following command to add a superuser with the username `admin`:
+
+```bash
+docker exec -ti saeoss_ckan-web_1 poetry run ckan sysadmin add admin
+```
+- Replace `admin` with the desired username for the superuser.
+
+![command](./img/super-user-1.png)
+
+After running the command to add a superuser, the system typically asks for confirmation. Users are prompted to confirm whether they indeed want to create a superuser. The user is expected to input either `Y` for Yes or `n` for No based on their intention to create a superuser.
+
+![confirmation](./img/super-user-2.png)
+
+If the user chooses `Y` then they need to provide the email and password for the administrator account.
+
+![required information](./img/super-user-3.png)
+
+## Converting Normal User to SuperUser
+
+Existing users can be elevated to superuser status through the terminal.
+Use the following command, replacing <username> with the username of the registered user:
+
+```bash
+docker exec -ti saeoss_ckan-web_1 poetry run ckan sysadmin add <username>
+```
+
+![convert the normal user to a superuser](./img/super-user-4.png)
+
+This command promotes the specified user to superuser status.
+
+Before the superuser privileges
+
+![Bob002 as a normal user](./img/super-user-5.png)
+
+After the superuser privileges
+
+![Bob002 as a superuser](./img/super-user-6.png)
+
+**Important Notes:**
+
+- Superusers have elevated privileges and can access and modify system-wide settings.
+- Superusers can only be created via the terminal and not through the CKAN site.
+
+**Important Security Considerations:**
+
+- Superuser and super admin credentials should be kept secure.
+- Regularly review and update superuser/admin credentials to enhance system security.