Add README.md
This commit is contained in:
185
README.md
Normal file
185
README.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user