docs: Add section on recovery and reorganize

docs/blueql/4.dcl.md

@@ -38,7 +38,7 @@ SYSCTL ALTER USER 'username' WITH { password: 'new password' }
 
 :::warning
 Trying to change the `root` account password will throw an error. You can only change the root by
-[following the procedure here](/system/administration#resetting-the-root-password)
+[following the procedure here](../system/user-management#resetting-the-root-password)
 :::
 
 ## SYSCTL DROP USER

docs/blueql/index.md

@@ -1,5 +1,5 @@
 ---
-title: BlueQL Guide
+title: BlueQL
 ---
 
 import DocCardList from '@theme/DocCardList';
@@ -12,6 +12,8 @@ If you've used SQL before you should find BlueQL very easy to learn. There are s
 
 ## Guides
 
+Here's an overview of the different BlueQL guides in this section:
+
 - **[Overview](overview)**: Understand BlueQL's design and language items such as parameters, literals, expressions and so forth
 - **[DDL](ddl)**: Understand data definition with BlueQL in Skytable
 - **[DML](dml)**: Understand data manipulation with BlueQL in Skytable

docs/index.md

@@ -19,10 +19,14 @@ We recommend you to follow the guide in this sequence (but feel free to skip any
       - [**DDL**](blueql/ddl): Data definition with BlueQL
       - [**DML**](blueql/dml): Data manipulation with BlueQL
       - [**DCL**](blueql/dcl): Data control with BlueQL
-    - [**Configuration**](system/configuration): Information to help you configure Skytable with custom settings such as custom ports, hosts, TLS, and etc.
-    - [**Administration**](system/administration): Information on access control, user and other administration features
-    - [**Resources**](resources/overview): Helpful resources
-    - [**A guide to the new Skytable**](resources/migration): For old our returning Skytable users who are coming from older versions
+    - [**System administration**](system):
+      - [**Configuration**](system/configuration): Information to help you configure Skytable with custom settings such as custom ports, hosts, TLS, and etc.
+      - [**User management**](system/user-management): Information on access control, user and other administration features
+      - [**Global management**](system/global-management): Global settings management
+      - [**Data recovery**](system/recovery): Database recovery
+    - **Resources**:
+      - [**Useful links**](resources/useful-links): Links to helpful resources
+      - [**Migration**](resources/migration): For old our returning Skytable users who are coming from older versions
     - [**Benchmarking**](benchmarking): A guide for load testing Skytable
     - [**Deployment**](deployment): An useful guide for deploying
     - [**Limits**](limits): An useful guide on system limits
@@ -33,7 +37,7 @@ Looking to integrate Skytable in your application? Great! [Find a driver for you
 
 ## Getting help
 
-We have a collection of resources [on this page](resources/overview). If you need in help in real-time, we recommend that you join our [Discord Community](https://discord.gg/QptWFdx) where you can get help directly from the developers and our community members. 
+We have a collection of resources [on this page](resources/useful-links). If you need in help in real-time, we recommend that you join our [Discord Community](https://discord.gg/QptWFdx) where you can get help directly from the developers and our community members. 
 Most queries are usually answered there in a few hours!
 
 ## Contributing

docs/protocol/1.overview.md → docs/protocol/index.md

@@ -1,6 +1,5 @@
 ---
-id: overview
-title: Skyhash 2 — Protocol Overview
+title: 'Skyhash 2: Overview'
 ---
 
 Skyhash is the protocol used for communication between Skytable clients (client drivers or libraries) and the Skytable server, written on top of TCP. If you're building an application that needs to *talk to* Skytable, you'll usually choose a [client library](/libraries) that works with your programming language and then start building your application.

docs/resources/1.overview.md → docs/resources/1.useful-links.md

@@ -1,6 +1,6 @@
 ---
-id: overview
-title: Resources
+id: useful-links
+title: Useful links
 ---
 
 ## Community and chat

docs/system/2.administration.md → docs/system/2.user-management.md

@@ -1,6 +1,6 @@
 ---
-id: administration
-title: Administration
+id: user-management
+title: User management
 ---
 
 Skytable's access control is very simple:
@@ -48,22 +48,3 @@ Standard users can access the following query types:
 - `UPDATE`
 - `DELETE`
 - `INSPECT`
-
-### Global management
-
-The single DDL query that lets you do a "sneak peek" into the status of the entire system is the `INSPECT GLOBAL` query. It 
-returns a JSON string like this:
-```json
-{
-    "spaces:"["space1", "space2"],
-    "users":["root", "staging_server"],
-    "settings:{},
-}
-```
-
-- `spaces`: lists all the spaces in the system
-- `users`: lists all users
-  :::info Access control note
-  This is only returned if you are the `root` user. Standard users cannot see the other users in the system
-  :::
-- `settings`: returns system settings (currently an empty dictionary is returned)

docs/system/3.global-management.md

@@ -0,0 +1,33 @@
+---
+id: global-management
+title: Global management
+---
+
+## Checking system health
+
+The following query returns an `Empty` response or an error code depending on the status of the database:
+
+```sql
+SYSCTL REPORT STATUS
+```
+
+If you receive an error code, we recommend you to connect to the host and check logs. If the server has crashed, you may need to [recover the database](recovery).
+
+## Inspecting all spaces
+
+The single DDL query that lets you do a "sneak peek" into the status of the entire system is the `INSPECT GLOBAL` query. It 
+returns a JSON string like this:
+```json
+{
+    "spaces:"["space1", "space2"],
+    "users":["root", "staging_server"],
+    "settings:{},
+}
+```
+
+- `spaces`: lists all the spaces in the system
+- `users`: lists all users
+  :::info Access control note
+  This is only returned if you are the `root` user. Standard users cannot see the other users in the system
+  :::
+- `settings`: returns system settings (currently an empty dictionary is returned)

docs/system/4.recovery.md

@@ -0,0 +1,25 @@
+---
+id: recovery
+title: Recovery
+---
+
+In the unforeseen event that a power failure or other catastrophic system failure causes the database to crash, the Skytable server will fail to start normally. Usually it will exit with a nonzero code and an error message such as "journal-corrupted." In such cases, you will need to recover the journal(s) and/or any other corrupted file(s).
+
+## Recovering database files
+
+To repair the database, simply run this on the command line **in the working directory of the database**:
+
+```sh
+skyd repair
+```
+The recovery system will first create a full backup of the current data files in a subdirectory in the `backups/` directory. It will then go over each database file, try to detect any errors and make any approriate repairs.
+
+## Important notes
+
+- The recovery system is *very conservative* and will attempt to restore the database to the most recent working state. Any remaining data is deemed unreliable and not loaded
+- Please ensure that you have sufficient disk space before attempting a repair
+- The earlier in the file the corruption happens, the greater the amount of data lost
+
+## Post recovery
+
+After running a repair operation, if a signficant amount of data loss has occurred (as reported by `skyd`) then we strongly recommend you to manually look through your datasets. The recovery process guarantees that the *restored data* is intact. If this failure resulted from power loss, in the future you may consider installing power backup systems if self-hosting or choosing a reliable cloud provider.

docs/system/index.md

@@ -0,0 +1,14 @@
+---
+title: System administration
+---
+
+In the following sections, we explore general system administration options with Skytable such as configuration, user management, system health and others. Please note that to use some of these guides you may need direct access to the host on which the database server is running; operations such as recovery and changing the root password require host access.
+
+## Guides
+
+Here's an overview of the different administration guides:
+
+- [**Configuration**](configuration): Understand how Skytable can be configured using command-line arguments, environment variables or a configuration file and what all configuration options are available
+- [**User management**](user-management): Learn about account types, permissions and how you can manage multiple users
+- [**Global management**](global-management): Learn how to check system health and manage the global state of your database instances
+- [**Data recovery**](recovery): Understand what to do after a system crash and how to recover data if needed

docusaurus.config.js

@@ -152,7 +152,11 @@ module.exports = {
           },
           {
             from: '/protocol/skyhash',
-            to: '/protocol/overview'
+            to: '/protocol'
+          },
+          {
+            from: '/protocol/overview',
+            to: '/protocol'
           }
         ]
       }]

sidebars.ts

@@ -21,34 +21,33 @@ module.exports = {
     },
     {
       type: 'category',
-      label: 'System Management',
+      label: 'System Administration',
       items: [
         "system/configuration",
-        "system/administration",
+        "system/user-management",
+        "system/global-management",
+        "system/recovery",
       ],
-      collapsed: false,
       link: {
-        type: 'generated-index',
-        title: 'System Management',
-        description: 'Learn how to configure Skytable for your needs and perform administrative tasks. We take a look at \
-        the different modes of configuration (CLI, ENV, configuration files), settings, access control, managing the root account and global management.',
+        type: 'doc',
+        id: 'system/index'
       }
     },
     "libraries",
     {
       type: 'category',
       label: 'Resources',
       items: [
-        "resources/overview",
+        "resources/useful-links",
         "resources/migration",
       ],
-      collapsed: false,
+      collapsed: true,
     },
     {
       type: 'category',
       label: 'Protocol',
       items: [
-        "protocol/overview",
+        "protocol/index",
         "protocol/networking",
         "protocol/errors"
       ],

versioned_docs/version-0.8.0/blueql/4.dcl.md

@@ -38,7 +38,7 @@ SYSCTL ALTER USER 'username' WITH { password: 'new password' }
 
 :::warning
 Trying to change the `root` account password will throw an error. You can only change the root by
-[following the procedure here](/system/administration#resetting-the-root-password)
+[following the procedure here](../system/administration#resetting-the-root-password)
 :::
 
 ## SYSCTL DROP USER