Remote Access Outside Your Home Network

When self-hosting StudySync on a home server, NAS, mini-PC, or Raspberry Pi, you need a secure way to access the web application, add assignments from your phone, and let Apple Calendar sync when you are away from home Wi-Fi.

StudySync contains dynamic host detection:

const reqHost = req.headers['x-forwarded-host'] || req.get('host');

Because the server dynamically generates all calendar subscription URLs (webcal://<host>/api/calendar/feed.ics) and webhook capture endpoints based on the incoming request, it works transparently over any private overlay network or VPN without reconfiguring the application.

---

Comparison of Remote Access Options

Feature	Tailscale	WireGuard	NetBird	ZeroTier
Protocol	WireGuard	WireGuard	WireGuard	Custom Ethernet (L2)
NAT Traversal (CGNAT)	Automatic (DERP)	Manual (Port Forward)	Automatic (STUN/TURN)	Automatic (Relay)
Port Forwarding Required	No	Yes (UDP 51820)	No	No
Self-Hosted Control Plane	Yes (via Headscale)	100% self-hosted	Yes (open source)	Yes (open source)
DNS / Hostnames	MagicDNS (*.ts.net)	Manual / Local DNS	NetBird DNS (*.netbird.cloud)	ZeroTier IP / DNS
Automatic HTTPS	Yes (tailscale serve)	Via Reverse Proxy	Via Reverse Proxy	Via Reverse Proxy
iOS On-Demand VPN	Yes	Yes	Yes	Yes

---

Option 1: Tailscale (Recommended for Zero Configuration)

Tailscale is a zero-config mesh VPN built on WireGuard. It connects your devices into a private encrypted network (a tailnet) without requiring port forwarding on your home router, making it ideal if your ISP uses CGNAT.

Setup

1. Install Tailscale on your host server:

   # On macOS
   brew install tailscale
   sudo tailscale up
   
   # On Ubuntu/Debian Linux
   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up

2. Install Tailscale on your mobile devices:
   • Download the Tailscale app from the iOS App Store or Google Play Store.
   • Log into the same account and connect.
3. Connect to StudySync:
   • Find your host's MagicDNS name in the Tailscale admin console (e.g. my-mac.tailnet-xyz.ts.net).
   • Open Safari on your iPhone and navigate to:

     http://my-mac.tailnet-xyz.ts.net:3000

4. Subscribe to Apple Calendar:
   • In StudySync, open Sync → Apple Calendar & iCloud.
   • Notice that the webcal link has automatically formatted with your MagicDNS address:

     webcal://my-mac.tailnet-xyz.ts.net:3000/api/calendar/feed.ics

   • Subscribe on your Mac or iPhone. Calendar updates will sync across campus Wi-Fi and cellular data.

Automatic HTTPS with tailscale serve

To run StudySync over encrypted HTTPS with a valid Let's Encrypt certificate generated by Tailscale:

sudo tailscale serve --https=443 localhost:3000

Now you can access StudySync at https://my-mac.tailnet-xyz.ts.net with native TLS.

---

Option 2: WireGuard (Sovereign Point-to-Point Tunnel)

If you want complete control without using third-party coordination servers, a direct WireGuard road-warrior tunnel is the most efficient and lightweight option.

Requirements

• A public IPv4 address or dynamic DNS hostname (e.g. DuckDNS, Cloudflare DDNS).
• One port forwarded on your home router (default: UDP 51820).

Quick Setup with Docker (wg-easy)

The easiest way to manage a self-hosted WireGuard server with client QR codes is using wg-easy:

# docker-compose.wireguard.yml
services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy
    container_name: wg-easy
    environment:
      - WG_HOST=your-home-ip-or-ddns.duckdns.org
      - PASSWORD=choose-an-admin-password
    volumes:
      - ~/.wg-easy:/etc/wireguard
    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv4.ip_forward=1

1. Run docker compose -f docker-compose.wireguard.yml up -d.
2. Open http://localhost:51821 and click New Client (e.g. iPhone).
3. Open the WireGuard app on your phone and scan the displayed QR code.
4. Enable the tunnel. Access StudySync using your server's local LAN IP (e.g. http://192.168.1.100:3000) or WireGuard gateway IP (e.g. http://10.8.0.1:3000).

iOS On-Demand Activation

In the WireGuard iOS app, open your tunnel profile, tap Edit, and scroll to On-Demand:

• Enable Cellular.
• Enable Wi-Fi → Select Except these SSIDs and enter your home Wi-Fi network name.

Your iPhone will automatically connect to WireGuard whenever you leave home Wi-Fi and disconnect when you return, ensuring continuous background calendar synchronization.

---

Option 3: NetBird (Open-Source Zero-Trust Mesh)

NetBird is an open-source alternative to Tailscale based on WireGuard and kernel-space routing. It features automatic NAT traversal, an open-source management plane that you can self-host, and built-in SSO integration.

Setup

1. Sign up for a free NetBird account (or self-host the NetBird dashboard).
2. Install the NetBird CLI on your host server:

   # Linux / macOS
   curl -fsSL https://pkgs.netbird.io/install.sh | sh
   netbird up

3. Install NetBird on your phone from the App Store or Google Play and log in.
4. In the NetBird admin dashboard, note your host's peer domain or IP (e.g. studysync.netbird.selfhosted or 100.64.0.5).
5. Access StudySync from your phone at:

   http://studysync.netbird.selfhosted:3000

All calendar feeds and shortcut capture webhooks will automatically output URLs using your NetBird hostname.

---

Option 4: ZeroTier (Virtual Ethernet Switch)

ZeroTier creates a global Layer-2 virtual Ethernet network. Devices joined to the same ZeroTier network appear as if they are plugged into the same physical network switch.

Setup

1. Create a free account at my.zerotier.com and create a network (note the 16-character Network ID).
2. Install ZeroTier on your server:

   # On macOS
   brew install zerotier-one
   sudo zerotier-cli join <your-network-id>
   
   # On Linux
   curl -s https://install.zerotier.com | bash
   sudo zerotier-cli join <your-network-id>

3. Install ZeroTier on your phone:
   • Install the ZeroTier One app on iOS or Android.
   • Enter your Network ID and tap Join.
4. Authorize both devices:
   • In the ZeroTier web console, check the Auth checkbox next to both your server and phone.
   • Assign a managed IP (e.g. 10.147.17.10 for your server).
5. Open your mobile browser and navigate to http://10.147.17.10:3000.

---

Production Tip: Reverse Proxy & HTTPS

While calendar feeds over HTTP (webcal://) work across private VPN tunnels, Progressive Web Apps (PWAs) and Service Workers require HTTPS on non-localhost origins to enable offline caching and home screen installation.

You can put a reverse proxy in front of StudySync to terminate TLS:

Caddy Example (Caddyfile)

# For Tailscale MagicDNS or custom domain
my-server.tailnet-xyz.ts.net {
    reverse_proxy localhost:3000
}

Caddy will automatically request and renew a trusted TLS certificate, allowing you to access StudySync over pure HTTPS across your VPN.