From ae5a21eadf56c1930357fdc03ad1168e33f2fa27 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 25 Apr 2026 12:11:56 +0000 Subject: [PATCH] docs: add Pangolin to reverse proxy guide Agent-Logs-Url: https://github.com/nextcloud/all-in-one/sessions/c7f8b130-4edd-4fcc-b218-1522ba88eae8 docs: add Pangolin option to local-instance docs Agent-Logs-Url: https://github.com/nextcloud/all-in-one/sessions/0ad32b82-c0ae-46f4-9849-af64ae130dbd docs: address review feedback on Pangolin section Agent-Logs-Url: https://github.com/nextcloud/all-in-one/sessions/c7f8b130-4edd-4fcc-b218-1522ba88eae8 Co-Authored-By: szaimen <42591237+szaimen@users.noreply.github.com> Signed-off-by: Simon L. --- local-instance.md | 24 +++++++++++++------- reverse-proxy.md | 56 ++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 67 insertions(+), 13 deletions(-) diff --git a/local-instance.md b/local-instance.md index 8abbddb6..4fa42ba8 100644 --- a/local-instance.md +++ b/local-instance.md @@ -3,15 +3,23 @@ It is possible due to several reasons that you do not want or cannot open Nextcl ### Content - [1. Tailscale](#1-tailscale) -- [2. The normal way](#2-the-normal-way) -- [3. Use the ACME DNS-challenge](#3-use-the-acme-dns-challenge) -- [4. Use Cloudflare](#4-use-cloudflare) -- [5. Buy a certificate and use that](#5-buy-a-certificate-and-use-that) +- [2. Pangolin](#2-pangolin) +- [3. The normal way](#3-the-normal-way) +- [4. Use the ACME DNS-challenge](#4-use-the-acme-dns-challenge) +- [5. Use Cloudflare](#5-use-cloudflare) +- [6. Buy a certificate and use that](#6-buy-a-certificate-and-use-that) ## 1. Tailscale This is the recommended way. For a reverse proxy example guide for Tailscale, see this guide by [@Perseus333](https://github.com/Perseus333): https://github.com/nextcloud/all-in-one/discussions/6817 -## 2. The normal way +## 2. Pangolin +[Pangolin](https://pangolin.net/) is an open-source, WireGuard-based remote access platform similar in concept to Tailscale. It uses the **Newt** connector to create outbound-only encrypted tunnels — no inbound ports need to be opened on your firewall. Pangolin handles TLS automatically, providing a valid certificate for your Nextcloud domain. + +You can use either [Pangolin Cloud](https://app.pangolin.net/) (free tier available) or [self-host your own Pangolin server](https://docs.pangolin.net/self-host/quick-install) on a VPS. For private/local-only access, self-hosting Pangolin on a machine within your local network means that Nextcloud never needs to be exposed to the public internet. + +For the reverse proxy configuration details and a step-by-step setup guide, see the [Pangolin section in the reverse proxy documentation](./reverse-proxy.md#pangolin). + +## 3. The normal way The normal way is the following: 1. Set up your domain correctly to point to your home network 1. Set up a reverse proxy by following the [reverse proxy documentation](./reverse-proxy.md) but only open port 80 (which is needed for the ACME challenge to work - however no real traffic will use this port). @@ -21,12 +29,12 @@ The normal way is the following: **Hint:** You may have a look at [this video](https://youtu.be/zk-y2wVkY4c) for a more complete but possibly outdated example. -## 3. Use the ACME DNS-challenge +## 4. Use the ACME DNS-challenge You can alternatively use the ACME DNS-challenge to get a valid certificate for Nextcloud. Here is described how to set it up using an external caddy reverse proxy: https://github.com/nextcloud/all-in-one#how-to-get-nextcloud-running-using-the-acme-dns-challenge -## 4. Use Cloudflare +## 5. Use Cloudflare If you do not have any control over the network, you may think about using Cloudflare Tunnel to get a valid certificate for your Nextcloud. However it will be opened to the public internet then. See https://github.com/nextcloud/all-in-one#how-to-run-nextcloud-behind-a-cloudflare-tunnel how to set this up. -## 5. Buy a certificate and use that +## 6. Buy a certificate and use that If none of the above ways work for you, you may simply buy a certificate from an issuer for your domain. You then download the certificate onto your server, configure AIO in [reverse proxy mode](./reverse-proxy.md) and use the certificate for your domain in your reverse proxy config. diff --git a/reverse-proxy.md b/reverse-proxy.md index 0841b68f..ea81c844 100644 --- a/reverse-proxy.md +++ b/reverse-proxy.md @@ -6,7 +6,7 @@ This guide explains how to connect to Nextcloud AIO securely via HTTPS (TLS) usi - **Integrated**: AIO's built-in reverse proxy with automatic HTTPS - **External**: An external reverse proxy (such as Caddy or Nginx or Cloudflare Proxy) -- **Secure tunnel**: Tunneling services for private network access or public access without port forwarding (such as Tailscale Serve or Cloudflare Tunnel) +- **Secure tunnel**: Tunneling services for private network access or public access without port forwarding (such as Tailscale Serve, Cloudflare Tunnel, or Pangolin) ## Choosing Your Approach @@ -23,6 +23,7 @@ This guide explains how to connect to Nextcloud AIO securely via HTTPS (TLS) usi | **Integrated** | Simple setups, single service on port 443 | Public IP, dedicated port 443 | Yes (443) | | **External Reverse Proxy** (including Cloudflare Proxy) | Multiple services, existing web server, or users wanting DDoS protection | Existing reverse proxy, willingness to set one up, or Cloudflare account | Yes (443) | | **Cloudflare Tunnel** | No port forwarding possible/desired, public access | Cloudflare account | No | +| **Pangolin** | No port forwarding possible/desired, public or private access, self-hostable tunnel | Pangolin Cloud account or self-hosted Pangolin server | No | | **Tailscale Serve** | Private access (tailnet only) | Tailscale account | No | | **Tailscale Funnel** | Public access via Tailscale | Tailscale account | No | @@ -68,29 +69,32 @@ Using an existing external reverse proxy is required in particular if port `443/ > [!NOTE] > An external reverse proxy can also facilitate other routing approaches, but Nextcloud AIO only supports having its own dedicated hostname (e.g., `cloud.example.com`). You cannot run it in a subfolder like `example.com/nextcloud/`.[^shared] -### Secure tunnel: Using AIO with a secure tunneling service (*Tailscale, Cloudflare*) +### Secure tunnel: Using AIO with a secure tunneling service (*Tailscale, Cloudflare, Pangolin*) -Cloudflare and Tailscale offer secure tunneling services that let you access your Nextcloud without opening ports on your firewall. +Cloudflare, Tailscale, and Pangolin offer secure tunneling services that let you access your Nextcloud without opening ports on your firewall. #### Private network access For Nextcloud AIO, you can use: - **Cloudflare Tunnel (`cloudflared`)** - Secure outbound-only tunnels that don't require exposing ports - **Tailscale Serve** - Expose services privately on your Tailscale network (tailnet only) +- **Pangolin** - WireGuard-based outbound tunnels using the Newt connector; can be used for both private and public access -Both options provide private network access to your Nextcloud AIO instance. +All three options provide private network access to your Nextcloud AIO instance. #### Public Internet access (without port forwarding) To make your Nextcloud AIO instance accessible from the public Internet (not just your private network), you can use: - **Cloudflare Tunnel** with public routes enabled (which combines Cloudflare Tunnel with Cloudflare's proxy features) - **Tailscale Funnel** - Expose services to the public Internet via Tailscale's infrastructure +- **Pangolin** - Expose services publicly via Pangolin Cloud or a self-hosted Pangolin server -**Comparison of Cloudflare and Tailscale options:** +**Comparison of Cloudflare, Tailscale, and Pangolin options:** | Feature | Access Scope | Inbound Ports Required | Use Case | |---------|--------------|----------------|----------| | **Cloudflare Tunnel** | Public Internet | None | Public access without port forwarding | +| **Pangolin** | Public Internet or private | None | Public or private access; self-hostable | | **Tailscale Serve** | Your Tailscale network only | None | Private access for you and invited users | | **Tailscale Funnel** | Public Internet | None | Public access through Tailscale | @@ -737,6 +741,48 @@ httpServer.on('upgrade', (req, socket, head) => { +##### Pangolin + +
+ +click here to expand + +[Pangolin](https://pangolin.net/) is an open-source, identity-based remote access platform built on WireGuard that enables secure connectivity to private resources without opening inbound firewall ports. It uses the **Newt** connector as an outbound-only WireGuard tunnel client that runs alongside AIO on your server and connects to a Pangolin server (either Pangolin Cloud or your own self-hosted instance). From AIO's perspective, Pangolin works like a reverse proxy: Pangolin handles TLS and routes public traffic through the tunnel to AIO. + +**Requirements:** +- A [Pangolin Cloud](https://app.pangolin.net/) account **or** a [self-hosted Pangolin server](https://docs.pangolin.net/self-host/quick-install) +- No open inbound ports required + +**Setup:** + +1. **Set up Pangolin**: Either sign up for a free [Pangolin Cloud](https://app.pangolin.net/) account, or [self-host Pangolin](https://docs.pangolin.net/self-host/quick-install) on a VPS with a public IP address. + +1. **Create a site**: In the Pangolin dashboard, create a new site for the machine that will run AIO. Follow the instructions to generate a **Newt ID** and **Newt secret** for the site. + +1. **Deploy Newt on the AIO host**: Run the Newt connector on the same machine as AIO. You can deploy it as a Docker container alongside AIO: + + ```yaml + services: + newt: + image: fosrl/newt + restart: unless-stopped + environment: + - PANGOLIN_ENDPOINT=https://app.pangolin.net # For Pangolin Cloud; replace with your self-hosted server URL if self-hosting + - NEWT_ID= + - NEWT_SECRET= + ``` + + Or as a standalone binary — see the [Newt documentation](https://github.com/fosrl/newt) for details. + +1. **Create a resource**: In the Pangolin dashboard, create a new resource for the site. Set the target to `http://private.ip.address.of.server:11000`.
+ ⚠️ **Please note:** look into [this](#adapting-the-sample-web-server-configurations-below) to adapt the port and address to match your `APACHE_PORT` and `APACHE_IP_BINDING` settings. + +1. **Configure AIO**: When starting AIO, add `--env SKIP_DOMAIN_VALIDATION=true` to disable domain validation (domain validation is known to not work through Pangolin tunnels). Use the domain assigned by Pangolin as your Nextcloud domain when opening the AIO interface. + +1. Now continue with [point 2](#2-use-this-startup-command). + +
+ ##### Synology Reverse Proxy