# 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.