CloudGateway

About

• Live at: gocloudlaunch.com

• Shared regional WireGuard VPN platform. Each OCI region runs one long-lived WireGuard server.

• Users can use the dashboard to add and remove WireGuard clients on the deployed regional servers and view stored configs from Firebase.

• View, copy, download, or QR-code your client config straight from the dashboard. The native iOS app can sign in, list active Firebase-backed configs, and install a selected config without the separate WireGuard app.

• Admins can also sync region clients, if needed, and grant users accounts.

• Built from CloudLaunch, a multi-region cloud deployment platform for deploying servers on AWS. CloudLaunch used mini VPN servers as its proof-of-concept project. CloudGateway builds that idea into a full shared regional WireGuard VPN platform using the same deployment-focused architecture.

Screenshots

iOS App

Website

Architecture

React dashboard
  -> Firebase Auth
  -> Firebase reads for dashboard data/config display
  -> https://<region>.<origin>/api/*
      -> Cloudflare proxied DNS
      -> Caddy on regional OCI server
      -> FastAPI on 127.0.0.1
      -> Firebase Admin SDK
      -> WireGuard host commands

WireGuard client
  -> wg.<regionId>.<origin>:51820 (non-proxied DNS -> server public IPv4)
  -> wg0 on regional OCI server

Cloudflare fronts the regional API only. It is not part of the VPN data path; WireGuard clients resolve the non-proxied (grey-cloud) wg.<regionId>.<origin> record and connect directly to the server's public IPv4.

Components

• React dashboard (Frontend/Web/): region tabs, client create/remove, config display with QR/download/copy. Reads regions and client docs from Firebase.
• CloudGatewayKit (Frontend/Apple/CloudGatewayKit/): shared Apple VPN wrapper around WireGuardKit for iOS and future macOS apps.
• iOS app (Frontend/Apple/iOS/): CloudGateway app and packet tunnel extension. It uses Firebase Auth/Firestore to list owned configs and installs the user-selected config internally.
• Firebase: Auth plus Firestore. Product source of truth for users, regions, clients, roles, limits, and stored WireGuard configs.
• Regional API (Backend/API/): FastAPI control plane on each regional server. Runs as root via cloudgateway-api.service, binds only to 127.0.0.1, verifies Firebase ID tokens, writes product state through the Firebase Admin SDK, and mutates host WireGuard under a local lock.
• Caddy: prebuilt CloudGateway binary with github.com/mholt/caddy-ratelimit. Automatic HTTPS, Cloudflare Authenticated Origin Pulls, exact regional Host/SNI allowlist, rate limiting (including /api/health), strips /api/*, and proxies only to 127.0.0.1:<fastapi_port>. Host firewall accepts public 80/443 only from Cloudflare IP ranges.
• WireGuard: bare metal on the regional host. /etc/wireguard/wg0.conf is interface-only; peers live in Firebase and on the live interface, applied by the API with wg set and rebuilt at boot by cloudgateway-sync-peers.
• DNS filtering: AdGuard Home listens only on the WireGuard tunnel DNS IPs and forwards allowed VPN client queries to local Unbound, a forward-only resolver that forwards over DNS-over-TLS to Quad9, Mullvad, and DNS.SB and validates DNSSEC locally. The cloud provider sees only encrypted DNS and never the domains clients resolve. Only the AdGuard DNS filter is enabled, and DNS query logs/statistics are disabled.
• AWS: SES email only. Lambda, DynamoDB, Secrets Manager VPN configs, and the Cloudflare Worker are not part of the platform.

Regional API URLs

• Each region serves its API at https://<regionId>.<origin>/api/*, where <origin> is the frontend origin host, for example gocloudlaunch.com.
• In production the frontend derives the URL from the selected region's regionId plus the current window.location.origin. There is no global API router and no base-domain config.
• REACT_APP_API_ORIGIN is a local/dev override only. When set, API helpers call ${REACT_APP_API_ORIGIN}/api/*. Production builds leave it unset.

Source of Truth

• Firebase is the single source of truth: users, regions, clients, roles, limits, stored configs, and the WireGuard peer set.
• Peers are never saved to wg0.conf or any other host state file. Client create/delete updates Firebase and applies the live wg0 change in one locked operation.
• On reboot, wg-quick brings up the interface from the static config and cloudgateway-sync-peers rebuilds the peer set from Firebase. The same command repairs drift on demand; see docs/wireguard-drift-repair.md.

Privacy and Logging

• API logs are required and are structured JSON. They may include request IDs, routes, operation status, and user emails, because those are needed to operate the control plane.
• VPN traffic logs are forbidden. Never log DNS queries, domains or destination IPs requested by VPN users, browsing/app traffic metadata, packet metadata, or per-user connection history.
• Never log WireGuard private keys, full WireGuard configs, Firebase service account secrets, or auth tokens.
• Account-scoped ACL policy logs are aggregate-only: row counts, skipped-row counts, booleans, and region IDs. Never a uid, email, tunnel address, account slot, client name, or key.
• The Policy/{regionId} status document is deliberately opaque: a region ID, two hashes, a row count, and a timestamp. The hashes are non-reversible digests of live nftables objects, not a client list, and reveal nothing about who is on the map.

Languages and Frameworks

• React with TypeScript and TailwindCSS for the frontend
• Python with FastAPI for the regional control plane
• Firebase for Authentication and Database
• Caddy (prebuilt CloudGateway binary with rate limiting) for the regional API edge
• OCI Compute and Terraform for regional servers
• AWS SES for email

Tool Versions

See docs/tool-versions.md for expected local and deployed tooling versions, including Python, Node.js, npm, Terraform, Caddy, and AdGuard Home.

Usage

• Email me or message me on LinkedIn if you want to try it.

• Desktop clients still use the WireGuard app or wg-quick.

• The native iOS app is replacing the iPhone QR/config-file flow by installing the selected config through its packet tunnel extension.

On Phone

• Build and install the CloudGateway iOS app from Xcode.
• Sign in with your Firebase email/password account.
• Choose one active config by client display name and region.
• Install the VPN profile, then start or stop the tunnel from the app.

On Mac

• It's much easier to use the WireGuard Desktop app, but you can follow these steps instead:

• Start WireGuard manually:

  wg-quick up wg-client

• Check status:

  sudo wg

• To stop it:

  wg-quick down wg-client

More Docs

• Quick Deployment: docs/quick-deployment.md
• Frontend: Frontend/Web/README.md
• Regional API: Backend/API/README.md
• Regional API contract: docs/api-contract.md
• API deployment handoff: docs/deployment-handoff.md
• Regional server / Terraform: Infrastructure/OCI/README.md
• Caddy binary build: Infrastructure/OCI/caddy/README.md
• Firebase / Firestore: Backend/Firebase/README.md
• Cloudflare: Infrastructure/CloudFlare/README.md
• Tool versions: docs/tool-versions.md
• Operations runbooks: docs/