From d3ef1c2b20215e905856c7186b3579546ac655cc Mon Sep 17 00:00:00 2001
From: Tomas Kracmar <tomas.kracmar@cqre.net>
Date: Fri, 16 Jan 2026 08:43:00 +0000
Subject: [PATCH] Add README.md

---
 README.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 185 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2044b76
--- /dev/null
+++ b/README.md
@@ -0,0 +1,185 @@
+# Zitadel + Tailscale / Headscale Onboarding Guide
+
+This guide walks a new user through joining the Ocean network using **Zitadel** for identity and **Tailscale** (backed by Headscale / Headplane) for secure network access.
+
+You will receive **a username and a temporary password** from the administrator. Follow the steps carefully for your device.
+
+---
+
+## 1. What You Need Before You Start
+
+* A device running **Windows, macOS, iOS, or Android**
+* Internet connection
+* Username and temporary password provided by the administrator
+
+You do **not** need any networking knowledge. This process is safe and reversible.
+
+---
+
+## 2. Account Activation (Zitadel)
+
+Before installing Tailscale, you must activate your account.
+
+1. Open a browser and go to:
+   **[https://id.cqre.net](https://id.cqre.net)**
+2. Log in using:
+
+   * **Username** (provided by admin)
+   * **Temporary password** (provided by admin)
+3. You will be prompted to:
+
+   * Set a **new personal password**
+   * (Optionally) enroll a **second factor (2FA)** if required
+
+Once completed, your identity is active.
+
+You can close the browser after this step.
+
+---
+
+## 3. Install Tailscale
+
+Tailscale creates a secure, encrypted connection to the Ocean network.
+
+### Download Links
+
+* Windows / macOS: [https://tailscale.com/download](https://tailscale.com/download)
+* iOS (iPhone / iPad): App Store → *Tailscale*
+* Android: Google Play → *Tailscale*
+
+Install the app as you would any other software.
+
+---
+
+## 4. Log In to Tailscale (Important Platform Differences)
+
+The Ocean network uses a **custom Tailscale server (Headscale)** at **[https://vpn.cqre.net](https://vpn.cqre.net)**.
+
+⚠️ **Important:** On **macOS, iOS, and Android**, the default browser-based login flow must be interrupted. This is normal.
+
+---
+
+### macOS / iOS / Android
+
+1. Open **Tailscale**
+2. Tap or click **Log in**
+3. A browser window opens asking you to sign in to Tailscale.com
+4. **Close the browser window** (do not log in)
+5. Return to the **Tailscale app**
+6. Select **Use a custom server** / **Add custom coordination server**
+7. Enter the server URL exactly:
+   **[https://vpn.cqre.net](https://vpn.cqre.net)**
+8. The browser opens again, this time redirecting to **Zitadel**
+9. Log in using:
+
+   * Your Zitadel **username**
+   * Your **personal password**
+
+After successful login, Tailscale connects automatically.
+
+---
+
+### Windows
+
+On Windows, logging in to a **custom Headscale server** requires using the command line.
+
+1. Open **Tailscale** once, then **close the Tailscale window** completely
+2. Open **Command Prompt** or **PowerShell**
+3. Run the following command exactly:
+
+```
+tailscale login --login-server https://vpn.cqre.net
+```
+
+4. A browser window opens showing a **device code**
+5. Confirm the device code and log in via **Zitadel** using:
+
+   * Your Zitadel **username**
+   * Your **personal password**
+6. After successful authentication, return to the Tailscale app
+
+Tailscale will now show the device as **connected**.
+
+---
+
+You may see a message like *“Connected”* or *“VPN enabled”*.
+
+---
+
+## 5. Platform-Specific Notes
+
+### Windows
+
+* You may be asked to approve a **network adapter** or **VPN driver**
+* Accept all system prompts
+* Tailscale runs in the system tray after installation
+
+### macOS
+
+* macOS will ask for permission to add a VPN configuration
+* Approve the request
+* Tailscale icon appears in the menu bar
+
+### iOS (iPhone / iPad)
+
+* iOS will ask to add VPN configurations
+* Face ID / Touch ID may be required
+* Tailscale reconnects automatically in the background
+
+### Android
+
+* Android will ask for VPN permission
+* Always allow Tailscale when prompted
+* Battery optimization may need to be disabled for reliability
+
+---
+
+## 6. Verifying Connection
+
+Once connected:
+
+* You can access internal services (websites ending in `.ocean` or similar)
+* Some services may require you to log in again using Zitadel
+
+If something works only inside the network, that is expected behavior.
+
+---
+
+## 7. Logging Out or Disconnecting
+
+* To temporarily disconnect: open Tailscale and toggle **Off**
+* To log out completely: open Tailscale → Account → **Log out**
+
+You can reconnect anytime by logging in again.
+
+---
+
+## 8. Common Issues
+
+**Browser does not open automatically**
+
+* Copy the login URL shown in Tailscale and open it manually
+
+**Login works but no access**
+
+* Wait 1–2 minutes (access rules may still be propagating)
+
+**Still not working**
+
+* Contact the administrator and mention:
+
+  * Your username
+  * Your device and operating system
+
+---
+
+## 9. Security Notes
+
+* Never share your password
+* The administrator will never ask for your password
+* If you lose your device, report it immediately
+
+---
+
+Welcome aboard 🌊
+You are now part of the Ocean network.