From 77dbbfe4ee774174c7d32f90715a1eb5fde43c72 Mon Sep 17 00:00:00 2001
From: allan <allan@xfiles.dk>
Date: Thu, 27 Nov 2025 15:34:39 +0100
Subject: [PATCH] docs: clearer README, more user-friendly

---
 README.md | 80 ++++++++++++++++++++++++++-----------------------------
 1 file changed, 38 insertions(+), 42 deletions(-)

diff --git a/README.md b/README.md
index 9fe0e6c..e00c649 100644
--- a/README.md
+++ b/README.md
@@ -1,78 +1,74 @@
 # MariaDB for Ubuntu 24.04 Server
-[![OS](https://img.shields.io/badge/ubuntu-24.04-E95420)](#)
-[![Shell](https://img.shields.io/badge/shell-bash-121011)](#)
-[![DB](https://img.shields.io/badge/server-mariadb-003545)](#)
-[![Auth](https://img.shields.io/badge/auth-socket-blue)](#)
+[![OS](https://img.shields.io/badge/ubuntu-24.04-E95420)](#)  
+[![Shell](https://img.shields.io/badge/shell-bash-121011)](#)  
+[![DB](https://img.shields.io/badge/server-mariadb-003545)](#)  
+[![Auth](https://img.shields.io/badge/auth-socket-blue)](#)  
 [![License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
 
-Automated Bash installer script for deploying MariaDB on Ubuntu 24.04 Server using **socket authentication** for the root account and creating a dedicated **local-only admin user** supplied at runtime.
+Automated Bash installer for **MariaDB on Ubuntu 24.04**, configured with:
 
-This is a **production-focused installer**, not a demo.
+* **Socket authentication for root** (modern, secure, no passwords lying around)
+* A dedicated **admin user created during install**
+* Full **local-only access** to reduce attack surface
+* Automatic **hardening equivalent to mysql_secure_installation**
 
----
+This is not a tutorial.  
+This is a **deployment tool for production environments** — opinionated, hardened, and designed to "just work".
 
-### Preparing
-Update your package index before running the installer:
+## Why this installer exists
+
+Because installing MariaDB is easy — but installing it *properly* is how future you avoids ulcers.
+
+This script handles:
+
+✔ Installation  
+✔ Service enablement  
+✔ Hardening & security  
+✔ Admin user creation  
+✔ Local-only access  
+✔ Optional password auth if needed
+
+## 1. Prepare the system
 
 ```
 sudo apt update -y
 ```
 
-### Download the Script
-Clone the repository from your Git server:
-```
-git clone https://git.x-files.dk/database/mariadb-ubuntu.git
-```
+## 2. Download the installer
 
 ```
+git clone https://git.x-files.dk/database/mariadb-ubuntu.git
 cd mariadb-ubuntu
 ```
 
-### Usage
-Run the script with your chosen admin username and password:
+## 3. Run the installer
+
 ```
 sudo ./mariadbinstall -u <adminuser> -p <password>
 ```
 
-### Example
+Example:
+
 ```
 sudo ./mariadbinstall -u mydbuser -p "StrongPassword123"
 ```
 
-> **IMPORTANT**
-> Always enclose the password in quotes if it contains special characters such as `$`, `!`, or `&`.
+> **IMPORTANT**  
+> Wrap the password in quotes if it contains special symbols.
 
----
-
-### Notes
-- No `mysql_secure_installation` needed — this scipt is performing the equivalent hardening.  
-- The created admin user is **restricted to localhost only** for security.  
-- Root remains socket-authenticated by default.  
-
-> **On a side note**  
-> I know that on modern Ubuntu systems `mysql_secure_installation` isn’t strictly necessary anymore — but a bit of paranoia helps me sleep at night. That’s why the script still runs through the whole `mysql_secure_installation` ritual. It’s not that it’s required — I just don’t want anyone blaming me because it *wasn’t* done. 
-
-### Optional
-Switching to Password Authentication. If you prefer **traditional password authentication** for the `root` user instead of socket authentication, you can switch manually:
+## Switch to password authentication (optional)
 
 ```
 sudo mariadb
-```
-
-Then run the following commands:
-
-```
 ALTER USER 'root'@'localhost' IDENTIFIED BY 'YourStrongPasswordHere';
 FLUSH PRIVILEGES;
 ```
 
-From now on, `root` will require a password when connecting, and socket authentication will no longer be used.
+## Verification
 
-> **Note:** This change is *optional*.  
-> Socket authentication is faster, safer, and the modern Ubuntu default.  
-> But if you prefer the old-school behavior, this is all it takes.
-
----
+```
+mariadb -u <adminuser> -p -e "SELECT VERSION();"
+```
 
 ### More Information