From 154c223d8c2cab066f071c5d364a5466c19bec45 Mon Sep 17 00:00:00 2001
From: riyadhafraa <49757212-riyadhafraa@users.noreply.replit.com>
Date: Thu, 14 May 2026 10:16:55 +0000
Subject: [PATCH] Update documentation to include setup scripts and remove
 server type references

Refactors the README.md file to detail installation scripts and replace "VPS" with more general server terminology.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 77cfe984-2c65-4152-bb7a-0df28274fe66
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: a4f33306-93f4-413c-b24b-58e08633a127
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/c3c252e4-c83d-40ca-9fff-99a3ea60701e/77cfe984-2c65-4152-bb7a-0df28274fe66/FvHcc7z
Replit-Helium-Checkpoint-Created: true
---
 README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 57 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index af15b1c0..2817b322 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
 # Tx OS
 
 A bilingual (Arabic / English) internal "office OS" web platform. Single-tenant,
-self-hosted, designed to live behind a TLS-terminating reverse proxy on a
-private VPS or on-prem host.
+self-hosted, designed to run on any Linux server (cloud or on-prem) behind a
+TLS-terminating reverse proxy.
 
 The repo is a pnpm monorepo containing:
 
@@ -33,16 +33,68 @@ The repo is a pnpm monorepo containing:
 
 ---
 
-## Quick start (Docker)
+## Quick start
 
-The fastest path to a running stack on a Linux VPS with Docker installed.
+Two ready-made install scripts cover the common cases — pick the one that
+matches your machine. Both are idempotent (safe to re-run) and never delete
+existing data.
+
+### Option A — One-shot Docker install (recommended)
+
+For any Linux server with Docker + Docker Compose. Boots the full stack
+(Postgres, MinIO, API, SPA, Caddy edge) with a single command:
+
+```bash
+git clone <this-repo>
+cd tx-os
+./start.sh
+```
+
+`start.sh` will:
+
+1. Copy `.env.docker.example` → `.env` on first run (and pause so you can
+   edit secrets — at minimum `SESSION_SECRET`, `POSTGRES_PASSWORD`).
+2. Build the images, bring up the database + object storage, run migrations,
+   then start the API and web containers behind Caddy.
+3. Print the URLs you can reach the system on.
+
+After install, open the printed URL and the **first-time setup wizard** will
+let you create the admin account in the browser. (You can also pre-seed an
+admin by setting `SEED_ADMIN_PASSWORD` in `.env` before running.)
+
+### Option B — Local development with HTTPS (`mkcert`)
+
+For developers running the stack on their own laptop with trusted local
+certificates (so the SPA can talk to a real `https://tx.local`):
+
+```bash
+git clone <this-repo>
+cd tx-os
+./scripts/local-setup.sh
+```
+
+`local-setup.sh` will:
+
+1. Detect your OS / package manager and tell you how to install
+   [`mkcert`](https://github.com/FiloSottile/mkcert) if it's missing.
+2. Prompt for a local domain (default `tx.local`) and detect your LAN IP
+   (so phones / tablets on the same Wi-Fi can reach the system too).
+3. Generate a trusted local TLS certificate covering `localhost`, the
+   chosen domain, and the LAN IP.
+4. Bootstrap `.env` from `.env.example` (preserving any keys you've already
+   set), then bring the Docker stack up.
+
+### Manual Docker install (advanced)
+
+If you'd rather drive `docker compose` yourself:
 
 ```bash
 git clone <this-repo>
 cd tx-os
 cp .env.example .env
 # Edit .env — at minimum change SESSION_SECRET, POSTGRES_PASSWORD,
-# S3_SECRET_ACCESS_KEY, SEED_ADMIN_PASSWORD, SEED_USER_PASSWORD.
+# S3_SECRET_ACCESS_KEY. SEED_ADMIN_PASSWORD / SEED_USER_PASSWORD are
+# OPTIONAL — leave them blank to use the in-browser setup wizard.
 $EDITOR .env
 
 docker compose build