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

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

⚠️ 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

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.