forked from cqrenet/ocean
186 lines
4.7 KiB
Markdown
186 lines
4.7 KiB
Markdown
# 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.
|