From 0e41d9015299d20a154415111277ddf6b1495058 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Thu, 10 Sep 2026 15:08:19 +0000 Subject: [PATCH] docs: align self-hosting network guidance --- hub/alby-hub-flavors/README.md | 4 ++++ hub/alby-hub-flavors/docker.md | 23 +++++++++++++-------- hub/alby-hub-flavors/linux.md | 6 +++++- hub/alby-hub-flavors/other-cloud-options.md | 4 ++++ hub/alby-hub-flavors/updating.md | 6 ++++-- 5 files changed, 31 insertions(+), 12 deletions(-) diff --git a/hub/alby-hub-flavors/README.md b/hub/alby-hub-flavors/README.md index 5216004..269a051 100644 --- a/hub/alby-hub-flavors/README.md +++ b/hub/alby-hub-flavors/README.md @@ -6,6 +6,10 @@ description: There are many different ways to run Alby Hub Alby Hub is 100% [open source](https://github.com/getAlby/hub). You can [run Alby Hub](https://getalby.com/alby-hub) on a server in the cloud, on your personal server (e.g. a mini pc) or on your desktop. You can easily migrate your Alby Hub to a different host or machine at any time. +{% hint style="warning" %} +When self-hosting Alby Hub with Docker or Linux, do not expose its HTTP port directly to the public internet. Keep it on a secure private network and restrict access with a firewall. For remote access, use a VPN or a restricted HTTPS reverse proxy. Cloud deployments should use the HTTPS endpoint provided by the platform instead of publishing the raw HTTP port. +{% endhint %} + Here are your options to run your Alby Hub {% content-ref url="other-cloud-options.md" %} diff --git a/hub/alby-hub-flavors/docker.md b/hub/alby-hub-flavors/docker.md index 77c7df9..0d2e1d3 100644 --- a/hub/alby-hub-flavors/docker.md +++ b/hub/alby-hub-flavors/docker.md @@ -12,6 +12,8 @@ This guide walks you through creating persistent storage, starting Alby Hub with {% hint style="warning" %} We recommend having a solid understanding of Docker management before attempting to host your Alby Hub in a Docker container. If you're not experienced with Docker, please avoid this method, as it could lead to potential loss of funds. + +Alby Hub is intended to run on a secure private network. Do not expose its HTTP port directly to the public internet. The examples below bind port `8080` to `127.0.0.1`, making the Hub reachable only from the Docker host by default. {% endhint %} ## Prerequisites @@ -91,7 +93,8 @@ services: volumes: - ./albyhub-data:/data ports: - - "8080:8080" + # Bound to 127.0.0.1 so Alby Hub is reachable only from this machine. + - "127.0.0.1:8080:8080" # Required for Lightning peer communication when using LDK. # - "9735:9735" environment: @@ -153,23 +156,23 @@ If Docker is running on the same computer you are using, open: http://localhost:8080 ``` -If Docker is running on another computer or server, open: +The default configuration does not make Alby Hub reachable from another device. To access it from a device on your trusted local network or VPN, bind the port to the server's private or VPN IP address in `docker-compose.yml`: ``` -http://your-server-ip:8080 +":8080:8080" ``` -For example: +For example, use `"192.168.1.100:8080:8080"` for a server with the private IP address `192.168.1.100`. Then restrict port `8080` with Docker-aware firewall rules or a provider network firewall so that only your local network or VPN can reach it. Open the Hub using the same private IP address: ``` http://192.168.1.100:8080 ``` -If you are running Alby Hub on a remote server, make sure port `8080` is allowed through the server and hosting-provider firewall. +Do not allow access to port `8080` from the public internet in either the host or hosting-provider firewall. On a remote server, either keep the loopback binding and place a restricted HTTPS reverse proxy in front of Alby Hub, or bind the port only to a private or VPN interface. -If you are using LDK, port `9735` must also be reachable from the internet for Lightning peer communication. +The broader `"8080:8080"` mapping also enables access from other devices, but it publishes the port on every host interface. Use it only on a trusted local network with firewall rules that account for Docker-published ports. -For better security, avoid exposing port `8080` publicly unless necessary. Consider restricting access to your own network, VPN, or IP address, or configuring HTTPS through a reverse proxy. +If you are using LDK, port `9735` must be reachable from the internet for Lightning peer communication. This does not require exposing the Alby Hub HTTP port. ### Step 5: Set up Alby Hub @@ -231,7 +234,7 @@ docker run -d \ --name albyhub \ -v ~/albyhub/albyhub-data:/data \ -e WORK_DIR=/data/albyhub \ - -p 8080:8080 \ + -p 127.0.0.1:8080:8080 \ --pull always \ ghcr.io/getalby/hub:latest ``` @@ -243,12 +246,14 @@ docker run -d \ --name albyhub \ -v ~/albyhub/albyhub-data:/data \ -e WORK_DIR=/data/albyhub \ - -p 8080:8080 \ + -p 127.0.0.1:8080:8080 \ -p 9735:9735 \ --pull always \ ghcr.io/getalby/hub:latest ``` +These commands make the Hub interface reachable only from the Docker host. If you intentionally make it available on a trusted local network or VPN, replace the mapping with `-p :8080:8080` and restrict port `8080` with Docker-aware firewall rules or a provider network firewall. Using `-p 8080:8080` instead publishes the port on every host interface. + The `~/albyhub/albyhub-data` folder stores your Hub data outside the container so that it is preserved when the container is stopped, removed, or updated. Docker Compose is generally recommended because it makes the deployment configuration and update process easier to manage. diff --git a/hub/alby-hub-flavors/linux.md b/hub/alby-hub-flavors/linux.md index 881bd46..4864056 100644 --- a/hub/alby-hub-flavors/linux.md +++ b/hub/alby-hub-flavors/linux.md @@ -4,6 +4,10 @@ description: How to run Alby Hub on Linux? # 🐧 Linux -Do you want Want to build and run Alby Hub from source on an Ubuntu VM or other Linux architecture? We've got you covered. +Do you want to build and run Alby Hub from source on an Ubuntu VM or other Linux architecture? We've got you covered. + +{% hint style="warning" %} +The Alby Hub HTTP server listens on all network interfaces by default. Run it only on a secure private network and use a firewall to block its HTTP port from the public internet. For remote access, use a VPN or an HTTPS reverse proxy that restricts who can connect. +{% endhint %} [Click here to get started.](https://github.com/getAlby/hub?tab=readme-ov-file#deploy-it-yourself) diff --git a/hub/alby-hub-flavors/other-cloud-options.md b/hub/alby-hub-flavors/other-cloud-options.md index 4313e6d..c5fbb94 100644 --- a/hub/alby-hub-flavors/other-cloud-options.md +++ b/hub/alby-hub-flavors/other-cloud-options.md @@ -8,6 +8,10 @@ You can find all releases, script binaries and install scripts of Alby Hub on [G \ To make the deployment of Alby Hub in the cloud as easy as possible, find guides and 1-click deploy options below 👇 +{% hint style="warning" %} +Use the HTTPS endpoint provided by the deployment platform. Do not expose Alby Hub's raw HTTP port `8080` directly to the public internet. If you configure a cloud deployment manually, keep the HTTP service behind a restricted HTTPS reverse proxy or access it through a VPN. +{% endhint %} + ## Overview ### Deploy on Fly.io diff --git a/hub/alby-hub-flavors/updating.md b/hub/alby-hub-flavors/updating.md index 195b001..4a7e7d3 100644 --- a/hub/alby-hub-flavors/updating.md +++ b/hub/alby-hub-flavors/updating.md @@ -95,18 +95,20 @@ docker stop albyhub docker rm albyhub ``` -Start Alby Hub again with the same data volume: +Start Alby Hub again with the same data volume and bind the HTTP port to the Docker host: ```bash docker run -d --name albyhub \ -v ~/.local/share/albyhub:/data \ -e WORK_DIR='/data' \ - -p 8080:8080 \ + -p 127.0.0.1:8080:8080 \ ghcr.io/getalby/hub:latest ``` These commands keep your existing data in `~/.local/share/albyhub` and start Alby Hub with the latest image. +If your existing deployment is intentionally reachable from a trusted local network or VPN, bind the port to that interface with `-p :8080:8080` and use Docker-aware firewall rules or a provider network firewall to block access from the public internet. Using `-p 8080:8080` publishes the port on every host interface. + If you use Docker Compose, update by pulling the latest image and recreating the service with your existing compose file. ```bash