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

---
 README.md | 159 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 151 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index dd196cb..9e1c4b5 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
-# Zabbix 7.0 LTS on Ubuntu 24.04 Server  
-[![OS](https://img.shields.io/badge/ubuntu-24.04-E95420)](#)  
-[![Shell](https://img.shields.io/badge/shell-bash-121011)](#)  
-[![WebServer](https://img.shields.io/badge/server-nginx-009639)](#)  
-[![PHP](https://img.shields.io/badge/php-fpm-777BB4)](#)  
-[![MariaDB](https://img.shields.io/badge/db-mariadb-003545)](#)  
-[![MySQL](https://img.shields.io/badge/db-mysql-4479A1)](#)  
-[![Zabbix](https://img.shields.io/badge/app-zabbix_7.0_LTS-DC382D)](#)  
+# Zabbix 7.0 LTS on Ubuntu 24.04 Server
+[![OS](https://img.shields.io/badge/ubuntu-24.04-E95420)](#)
+[![Shell](https://img.shields.io/badge/shell-bash-121011)](#)
+[![WebServer](https://img.shields.io/badge/server-nginx-009639)](#)
+[![PHP](https://img.shields.io/badge/php-fpm-777BB4)](#)
+[![MariaDB](https://img.shields.io/badge/db-mariadb-003545)](#)
+[![MySQL](https://img.shields.io/badge/db-mysql-4479A1)](#)
+[![Zabbix](https://img.shields.io/badge/app-zabbix_7.0_LTS-DC382D)](#)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 
 Automated installer for **Zabbix 7.0 LTS (Server + Web UI + Agent)** on Ubuntu 24.04.
@@ -14,3 +14,146 @@ This is not a demo stack — it deploys a **production monitoring platform** wit
 Socket authentication is detected automatically. No manual SQL typing. No UI-wizard guesswork.
 
 Set your domain → run the installer → log into Zabbix.
+
+---
+
+## Requirements
+
+You must already have:
+
+✔ Nginx running  
+✔ PHP-FPM running  
+✔ MariaDB/MySQL installed  
+✔ Root access (script checks and exits if missing)
+
+If you’re missing components:
+
+| Component | Installer |
+|---|---|
+| Nginx + PHP-FPM | https://git.x-files.dk/webserver/nginx-ubuntu |
+| MariaDB | https://git.x-files.dk/database/mariadb-ubuntu |
+
+---
+
+## Download
+
+```
+git clone https://git.x-files.dk/network/zabbix-ubuntu.git
+cd zabbix-ubuntu
+```
+
+---
+
+## Install
+
+```
+sudo ./zabbixinstall -n <domain> -p <zabbixdbpassword>
+```
+
+Socket auth (default Ubuntu) — simplest mode:
+```
+sudo ./zabbixinstall -n zabbix.example.com -p ZabbixPass123
+```
+
+Password authentication:
+```
+sudo ./zabbixinstall -n zabbix.example.com -p ZabbixPass123 -a root -m rootpwd
+sudo ./zabbixinstall -n zabbix.example.com -p ZabbixPass123 -a admin -m adminpwd
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `-n` domain | Required — hostname used for nginx + UI access |
+| `-p` password | Required — DB password for Zabbix user |
+| `-a` username | DB admin (default `root`) |
+| `-m` password | Required only without socket auth |
+| `-h`, `--help` | Displays mode-aware help screen |
+
+---
+
+## What the Installer Does
+
+✔ Installs Zabbix 7.0 LTS packages  
+✔ Creates DB + user securely with utf8mb4  
+✔ Detects socket vs password auth automatically  
+✔ Imports schema — no UI import required  
+✔ Generates nginx host config in `/etc/nginx/conf.d/`  
+✔ Pulls **nginx-snippets** repo for TLS & caching support  
+✔ Enables + starts Zabbix server + agent  
+✔ Can be safely re-run — existing DB intact
+
+---
+
+## First Login
+
+Open:
+
+```
+http://<domain>
+```
+
+Default admin access:
+
+| User | Password |
+|---|---|
+| Admin | zabbix |
+
+If **socket auth NOT detected**, UI login must use:
+
+```
+DB Host = 127.0.0.1
+```
+
+Entering `localhost` will fail.
+
+---
+
+## File Paths
+
+| Path | Purpose |
+|---|---|
+| `/etc/zabbix/zabbix_server.conf` | Main server configuration |
+| `/usr/share/zabbix-sql-scripts/mysql/server.sql.gz` | Schema imported automatically |
+| `/etc/nginx/conf.d/<domain>.conf` | Web server config |
+| `/etc/nginx/nginx-snippets/` | Shared reusable config modules |
+
+---
+
+## HTTPS + TLS
+
+443 host file available:
+
+```
+https://git.x-files.dk/webserver/nginx-snippets/src/branch/main/hostfiles/zabbix.443.conf
+```
+
+Caching options included but disabled until uncommented:
+
+```
+# include cache-open-files.conf;
+# include cache-js-css.conf;
+# include cache-statics.conf;
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|---|---|---|
+| UI install fails | Socket disabled + used localhost | Replace with `127.0.0.1` |
+| DB creation denied | No socket auth detected | Re-run with `-m` (and `-a` optional) |
+| PHP errors | Wrong PHP-FPM version | `systemctl status php*-fpm` |
+| Nginx restart fails | Config syntax error | Run `nginx -t` |
+
+---
+### More Information
+
+More guides and documentation can be found on [wiki.x-files.dk](https://wiki.x-files.dk)
+
+---
+
+### License
+Licensed under the [MIT License](./LICENSE).