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