[+] add support for reverse proxies on a different path, closes #1049 (#1063)

* add support for reverse proxies on a different path, closes #1049

Users can now configure pgwatch to run under a custom path
(e.g., http::/example.com/pgwatch) when behind a reverse proxy like
Apache or Nginx.

- add `--web-base-path` flag to specify custom path prefix
- all API endpoints and static assets respect the configured base path
- inject `<base>` tag and React Router `basename` dynamically at runtime
- set `homepage: "."` in `package.json` for relative asset paths

Example usage:
  pgwatch --web-base-path=pgwatch --web-addr=:8080

Then configure reverse proxy to forward `/pgwatch/*` to
`localhost:8080/pgwatch/*`

* Put the WebSocket config into the example config

The WebSocket proxy needs to come before the general proxy.

* The config is no longer "above"

* Build frontend to `/webserver/build` and use `//go:embed` directly
in `webserver.go`

* make linter happy and remove webui go package

* fix "Download webui artifact" step

---------

Co-authored-by: Christoph Berg <myon@debian.org>
Co-authored-by: Denys Holub <holub.denys20@gmail.com>

Author: 3 people

.github/workflows/build.yml

@@ -61,7 +61,7 @@ jobs:
       uses: actions/upload-artifact@v5
       with:
         name: webui-build
-        path: internal/webui/build
+        path: internal/webserver/build
 
     - name: GolangCI-Lint
       uses: golangci/golangci-lint-action@v9
@@ -88,7 +88,7 @@ jobs:
       uses: actions/download-artifact@v6
       with:
         name: webui-build
-        path: internal/webui/build        
+        path: internal/webserver/build        
 
     - name: Setup Protobuf
       uses: ./.github/actions/setup-protobuf

.gitignore

@@ -19,6 +19,7 @@
 dist
 docs/godoc
 site
+build
 
 # Generated protobuf files
 *.pb.go

cmd/pgwatch/main.go

@@ -14,7 +14,6 @@ import (
 	"github.com/cybertec-postgresql/pgwatch/v3/internal/log"
 	"github.com/cybertec-postgresql/pgwatch/v3/internal/reaper"
 	"github.com/cybertec-postgresql/pgwatch/v3/internal/webserver"
-	"github.com/cybertec-postgresql/pgwatch/v3/internal/webui"
 )
 
 // setupCloseHandler creates a 'listener' on a new goroutine which will notify the
@@ -104,7 +103,7 @@ func main() {
 
 	reaper := reaper.NewReaper(mainCtx, opts)
 
-	if _, err = webserver.Init(mainCtx, opts.WebUI, webui.WebUIFs, opts.MetricsReaderWriter,
+	if _, err = webserver.Init(mainCtx, opts.WebUI, opts.MetricsReaderWriter,
 		opts.SourcesReaderWriter, reaper); err != nil {
 		exitCode.Store(cmdopts.ExitCodeWebUIError)
 		logger.Error("failed to initialize web UI: ", err)

docker/Dockerfile

@@ -45,8 +45,8 @@ ARG GIT_TIME
 
 # Copy source code
 COPY . .
-# Copy built WebUI from previous stage
-COPY --from=webui-builder /webui/build ./internal/webui/build
+# Copy built WebUI from previous stage to webserver package
+COPY --from=webui-builder /webserver/build ./internal/webserver/build
 
 # Generate protobuf and build the application
 RUN go generate ./api/pb/ && \

docker/compose.pgwatch.yml

@@ -13,6 +13,7 @@ services:
     command:
       - "--sink=postgresql://pgwatch@postgres:5432/pgwatch_metrics"
       - "--sink=prometheus://pgwatch:9187/pgwatch"
+      # - "--web-base-path=pgwatch"
     ports:
       - "8080:8080"
       - "9187:9187"

docker/demo/Dockerfile

@@ -45,8 +45,8 @@ ARG GIT_TIME
 
 # Copy source code
 COPY . .
-# Copy built WebUI from previous stage
-COPY --from=webui-builder /webui/build ./internal/webui/build
+# Copy built WebUI from previous stage to webserver package
+COPY --from=webui-builder /webserver/build ./internal/webserver/build
 
 # Generate protobuf and build the application
 RUN go generate ./api/pb/ && \

docs/howto/reverse_proxy.md

@@ -0,0 +1,115 @@
+---
+title: Running Behind a Reverse Proxy
+---
+
+When running pgwatch in production environments, you may want to expose it through a reverse proxy (like Apache, Nginx, or Traefik) on a different path instead of exposing its port directly. This guide shows you how to configure pgwatch for such setups.
+
+## Configuration
+
+### pgwatch Configuration
+
+Use the `--web-base-path` option to specify the base path under which pgwatch should serve its content:
+
+```bash
+pgwatch --web-base-path=pgwatch --web-addr=:8432
+```
+
+Or using environment variables:
+
+```bash
+export PW_WEBBASEPATH=pgwatch
+export PW_WEBADDR=:8432
+pgwatch
+```
+
+The web UI automatically adapts to the configured base path without requiring a rebuild.
+
+WebSockets are used for live log streaming. Make sure your reverse proxy is configured to support WebSocket connections.
+
+### Apache
+
+The `mod_proxy_wstunnel` module is required for the WebSocket proxy.
+
+```apache
+<VirtualHost *:443>
+    ServerName example.com
+
+    # Other SSL and domain configuration...
+
+    ProxyPass /pgwatch/log ws://localhost:8432/pgwatch/log
+    ProxyPassReverse /pgwatch/log ws://localhost:8432/pgwatch/log
+
+    ProxyPass /pgwatch/ http://localhost:8432/pgwatch/
+    ProxyPassReverse /pgwatch/ http://localhost:8432/pgwatch/
+    ProxyPreserveHost On
+
+    <Location /pgwatch/>
+        # Optional: Add authentication
+        AuthUserFile /etc/apache2/admpasswd
+        AuthType Basic
+        AuthName "pgwatch Administration"
+        <RequireAll>
+            Require valid-user
+        </RequireAll>
+    </Location>
+</VirtualHost>
+```
+
+### Nginx
+
+WebSocket support is automatic with the proxy configuration shown here. Nginx will upgrade the connection when needed.
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name example.com;
+
+    # Other SSL and domain configuration...
+
+    location /pgwatch/ {
+        proxy_pass http://localhost:8432/pgwatch/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Optional: Add authentication
+        auth_basic "pgwatch Administration";
+        auth_basic_user_file /etc/nginx/.htpasswd;
+    }
+}
+```
+
+## Testing the Configuration
+
+After configuring your reverse proxy and starting pgwatch:
+
+1. Verify the web UI loads: `https://example.com/pgwatch/`
+2. Check that API endpoints work: `https://example.com/pgwatch/readiness`
+3. Test WebSocket log streaming in the UI's Logs page
+4. Verify that navigation between pages works correctly
+
+## Common Issues
+
+### Static Assets Not Loading
+
+Make sure:
+
+- The reverse proxy's `ProxyPass` directive includes the base path
+- Both backend (`--web-base-path`) and frontend use the same path (frontend reads it dynamically from backend)
+
+### WebSocket Connection Failures
+
+Ensure:
+
+- Your reverse proxy supports WebSocket upgrades
+- The `/log` endpoint is properly proxied
+- No firewall rules are blocking WebSocket connections
+
+### Authentication Issues
+
+If using both reverse proxy authentication and pgwatch's built-in authentication:
+
+- The reverse proxy authentication happens first
+- Users must authenticate twice (proxy, then pgwatch login)
+- Consider disabling pgwatch authentication if using proxy-level auth

docs/reference/cli_env.md

@@ -162,6 +162,13 @@ It reads the configuration from the specified sources and metrics, then begins c
     TCP address in the form 'host:port' to listen on (default: :8080).  
     ENV: `$PW_WEBADDR`
 
+- `--web-base-path=`
+
+    Base path for web UI and API endpoints (e.g., 'pgwatch' for reverse proxy setups). When set, all web endpoints will be served under this path.  
+    ENV: `$PW_WEBBASEPATH`
+
+    Example: `--web-base-path=/pgwatch`
+
 - `--web-user=`
 
     Admin username.  

internal/webserver/cmdopts.go

@@ -9,6 +9,7 @@ const (
 type CmdOpts struct {
 	WebDisable  string `long:"web-disable" mapstructure:"web-disable" description:"Disable REST API and/or web UI" env:"PW_WEBDISABLE" optional:"true" optional-value:"all" choice:"all" choice:"ui"`
 	WebAddr     string `long:"web-addr" mapstructure:"web-addr" description:"TCP address in the form 'host:port' to listen on" default:":8080" env:"PW_WEBADDR"`
+	WebBasePath string `long:"web-base-path" mapstructure:"web-base-path" description:"Base path for web UI and API endpoints (e.g., 'pgwatch' for reverse proxy setups)" env:"PW_WEBBASEPATH"`
 	WebUser     string `long:"web-user" mapstructure:"web-user" description:"Admin username" env:"PW_WEBUSER"`
 	WebPassword string `long:"web-password" mapstructure:"web-password" description:"Admin password" env:"PW_WEBPASSWORD"`
 }

internal/webserver/jwt.go

@@ -16,12 +16,12 @@ type loginReq struct {
 	Password string `json:"password"`
 }
 
-func (Server *WebUIServer) IsCorrectPassword(lr loginReq) bool {
-	return (Server.WebUser+Server.WebPassword == "") ||
-		(Server.WebUser == lr.Username && Server.WebPassword == lr.Password)
+func (s *WebUIServer) IsCorrectPassword(lr loginReq) bool {
+	return (s.WebUser+s.WebPassword == "") ||
+		(s.WebUser == lr.Username && s.WebPassword == lr.Password)
 }
 
-func (Server *WebUIServer) handleLogin(w http.ResponseWriter, r *http.Request) {
+func (s *WebUIServer) handleLogin(w http.ResponseWriter, r *http.Request) {
 	var (
 		err   error
 		lr    loginReq
@@ -39,7 +39,7 @@ func (Server *WebUIServer) handleLogin(w http.ResponseWriter, r *http.Request) {
 		if err = jsoniter.ConfigFastest.NewDecoder(r.Body).Decode(&lr); err != nil {
 			return
 		}
-		if !Server.IsCorrectPassword(lr) {
+		if !s.IsCorrectPassword(lr) {
 			http.Error(w, "can not authenticate this user", http.StatusUnauthorized)
 			return
 		}