feat(config): add Local Gateway URL for reverse proxy and Docker (#2486)

* feat: add Local Gateway URL setting for reverse proxy support

Adds a new 'Local Gateway URL' setting that allows users to override
the gateway address from Kubo config. This is useful when:
- Running Kubo in Docker
- Accessing WebUI through a reverse proxy
- Accessing from a different host than where Kubo runs

The setting takes priority over the Kubo config gateway address.
When empty, the behavior falls back to the existing logic.

Fixes #2458

* fix: normalize gateway URLs by stripping trailing slashes

Ensures URLs like 'https://example.com/' and 'https://example.com'
are handled the same way, avoiding double slashes when constructing
paths like /ipfs/CID.

* fix: sync local gateway setting to kuboGateway for Helia/Explore

The ipld-explorer-components (Explore page) uses localStorage key
'kuboGateway' with {host, port, protocol} format. This change syncs
our 'ipfsLocalGateway' setting to that format so the Explore page
also uses the correct gateway URL.

Fixes Explore page using 127.0.0.1:8080 instead of custom gateway.

* fix: avoid 'address' in localGatewayForm description to prevent test flakiness

The e2e test uses getByText('Addresses') which matches any element
containing 'address' (case-insensitive). Changed 'gateway address' to
'gateway URL' in the description to avoid matching this query.

* fix: apply local gateway override everywhere

The Local Gateway URL only reached download links, so previews,
thumbnails and IPNS links still used the public gateway behind a
reverse proxy. Make the override apply to every gateway link the
WebUI builds.

- config: when an override is set, use it as the reachable gateway
  too, so previews, thumbnails, Explore and IPNS links honor it
- ipns-manager: use the available gateway URL, which also fixes a
  broken link before the gateway check has run
- gateway/ipfs-provider: one shared helper builds the Explore (Helia)
  gateway config from the override, and clearing the override resets it
- local-gateway-form: check the URL loads before saving so a typo
  cannot silently break links; the check now keeps the port
- settings: show the description above the input like the other
  gateway fields, link the gateway address to its Kubo docs, and use
  `http://localhost:8080` in the example
- tests: unit coverage for the override selection and the Helia config
  helper, plus an e2e that sets a Local Gateway URL and confirms it on
  the Status page

Closes #2383

---------

Co-authored-by: Marcin Rataj <lidel@lidel.org>

Author: NiltonVolpato

public/locales/en/app.json

@@ -48,6 +48,9 @@
   "publicGatewayForm": {
     "placeholder": "Enter a URL (https://ipfs.io)"
   },
+  "localGatewayForm": {
+    "placeholder": "Enter a URL (http://localhost:8080)"
+  },
   "publicSubdomainGatewayForm": {
     "placeholder": "Enter a URL (https://dweb.link)"
   },
@@ -87,6 +90,7 @@
     "pinStatus": "Pin Status",
     "publicKey": "Public key",
     "publicGateway": "Public Gateway",
+    "localGateway": "Local Gateway",
     "rateIn": "Rate in",
     "rateOut": "Rate out",
     "repo": "Repo",

public/locales/en/settings.json

@@ -23,6 +23,7 @@
     "translationProjectLink": "Join the IPFS Translation Project"
   },
   "apiDescription": "<0>If your node is configured with a <1>custom Kubo RPC API address</1>, including a port other than the default 5001, enter it here.</0>",
+  "localGatewayDescription": "<0>If you access the WebUI through a reverse proxy, Docker, or a different host, enter the gateway URL your browser can reach. Leave empty to use the first <1>gateway address</1> from your Kubo config.</0>",
   "publicSubdomainGatewayDescription": "<0>Select a default <1>Subdomain Gateway</1> for generating shareable links.</0>",
   "publicPathGatewayDescription": "<0>Select a fallback <1>Path Gateway</1> for generating shareable links for CIDs that exceed the 63-character DNS limit.</0>",
   "retrievalDiagnosticService": {

src/bundles/config.js

@@ -23,6 +23,18 @@ const bundle = createAsyncResourceBundle({
 
     const config = JSON.parse(conf)
 
+    // An explicit Local Gateway URL is the gateway the browser is meant to reach
+    // for everything (reverse proxy, Docker, non-default host or port), so trust
+    // it for the reachability-probed availableGateway too. Without this, the
+    // 127.0.0.1 probe below fails for remote users and previews, thumbnails and
+    // IPNS links fall back to the public gateway instead of the user's own node.
+    // https://github.com/ipfs/ipfs-webui/issues/2458
+    const localGateway = store.selectLocalGateway()
+    if (localGateway) {
+      store.doSetAvailableGateway(localGateway)
+      return conf
+    }
+
     const publicGateway = store.selectPublicGateway()
     const url = getURLFromAddress('Gateway', config) || publicGateway
 
@@ -66,7 +78,13 @@ bundle.reactIsSameOriginToBridge = createSelector(
 bundle.selectGatewayUrl = createSelector(
   'selectConfigObject',
   'selectPublicGateway',
-  (config, publicGateway) => getURLFromAddress('Gateway', config) || publicGateway
+  'selectLocalGateway',
+  (config, publicGateway, localGateway) => {
+    // Priority: 1) User-configured local gateway, 2) Kubo config, 3) Public gateway
+    const url = localGateway || getURLFromAddress('Gateway', config) || publicGateway
+    // Normalize: remove trailing slashes to avoid double slashes when constructing paths
+    return url.replace(/\/+$/, '')
+  }
 )
 
 bundle.selectAvailableGatewayUrl = createSelector(

src/bundles/config.test.js

@@ -0,0 +1,54 @@
+/* global describe, it, expect, beforeEach, afterEach */
+import { jest } from '@jest/globals'
+import { composeBundles } from 'redux-bundler'
+import configBundle from './config.js'
+import gatewayBundle from './gateway.js'
+
+// selectIpfsReady is false so the reactConfigFetch reactor stays quiet and we
+// drive doFetchConfig (which runs getPromise) deterministically from the test.
+const createMockIpfsBundle = (config) => ({
+  name: 'ipfs',
+  getExtraArgs: () => ({ getIpfs: () => ({ config: { getAll: async () => config } }) }),
+  selectIpfsReady: () => false,
+  selectIpfsConnected: () => false
+})
+
+const createStore = (config) => composeBundles(
+  createMockIpfsBundle(config),
+  gatewayBundle,
+  configBundle
+)()
+
+describe('gateway selection with a Local Gateway URL override', () => {
+  // getURLFromAddress logs when @multiformats/multiaddr-to-uri cannot resolve a
+  // multiaddr, which it cannot under jest; the override path does not need it.
+  let logSpy
+  beforeEach(() => {
+    window.localStorage.clear()
+    logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+  })
+  afterEach(() => logSpy.mockRestore())
+
+  // https://github.com/ipfs/ipfs-webui/issues/2458
+  it('routes the configured and available gateway through the override, and falls back to the Kubo config gateway when cleared', async () => {
+    const store = createStore({ Addresses: { Gateway: '/ip4/127.0.0.1/tcp/8080' } })
+
+    // trailing slash is normalized away on save
+    await store.doUpdateLocalGateway('https://ipfs.example.com/')
+    await store.doFetchConfig()
+
+    expect(store.selectLocalGateway()).toBe('https://ipfs.example.com')
+    // override beats the Kubo config gateway for download links
+    expect(store.selectGatewayUrl()).toBe('https://ipfs.example.com')
+    // getPromise sets availableGateway to the override, so previews, thumbnails
+    // and IPNS links (which use selectAvailableGateway*) honor it too
+    expect(store.selectAvailableGateway()).toBe('https://ipfs.example.com')
+    expect(store.selectAvailableGatewayUrl()).toBe('https://ipfs.example.com')
+
+    // clearing the override removes it from gateway selection (the multiaddr
+    // ->URI fallback to the Kubo config gateway is covered by e2e, since
+    // @multiformats/multiaddr-to-uri does not load under jest)
+    await store.doUpdateLocalGateway('')
+    expect(store.selectLocalGateway()).toBe('')
+  })
+})

src/bundles/gateway.js

@@ -19,6 +19,13 @@ const readPublicGatewaySetting = () => {
   return setting || DEFAULT_PATH_GATEWAY
 }
 
+const readLocalGatewaySetting = () => {
+  const setting = readSetting('ipfsLocalGateway')
+  // Return empty string if not set, so we can distinguish between
+  // "not configured" and "configured to empty"
+  return setting || ''
+}
+
 const readPublicSubdomainGatewaySetting = () => {
   const setting = readSetting('ipfsPublicSubdomainGateway')
   return setting || DEFAULT_SUBDOMAIN_GATEWAY
@@ -33,7 +40,8 @@ const init = () => ({
   availableGateway: null,
   publicGateway: readPublicGatewaySetting(),
   publicSubdomainGateway: readPublicSubdomainGatewaySetting(),
-  ipfsCheckUrl: readIpfsCheckUrlSetting()
+  ipfsCheckUrl: readIpfsCheckUrlSetting(),
+  localGateway: readLocalGatewaySetting()
 })
 
 /**
@@ -51,6 +59,31 @@ export const checkValidHttpUrl = (value) => {
   return url.protocol === 'http:' || url.protocol === 'https:'
 }
 
+/**
+ * Default `kuboGateway` config consumed by Helia/verified-fetch
+ * (ipld-explorer-components) on the Explore page when no explicit Local Gateway
+ * URL is set.
+ */
+export const DEFAULT_KUBO_GATEWAY = { trustlessBlockBrokerConfig: { init: { allowLocal: true, allowInsecure: false } } }
+
+/**
+ * Convert a Local Gateway URL into the `kuboGateway` config shape consumed by
+ * Helia/verified-fetch on the Explore page, so the explorer fetches blocks from
+ * the same gateway the rest of the WebUI uses.
+ * @param {string} gatewayUrl
+ * @returns {{host: string, port: string, protocol: string, trustlessBlockBrokerConfig: object}}
+ */
+export const localGatewayToKuboGateway = (gatewayUrl) => {
+  const url = new URL(gatewayUrl)
+  const protocol = url.protocol.replace(':', '')
+  return {
+    host: url.hostname,
+    port: url.port || (url.protocol === 'https:' ? '443' : '80'),
+    protocol,
+    trustlessBlockBrokerConfig: { init: { allowLocal: true, allowInsecure: protocol === 'http' } }
+  }
+}
+
 /**
  * Check if any hashes from IMG_ARRAY can be loaded from the provided gatewayUrl
  * @param {string} gatewayUrl - The gateway URL to check
@@ -71,7 +104,9 @@ export const checkViaImgSrc = (gatewayUrl) => {
    */
   // @ts-expect-error - Promise.any requires ES2021 but we're on ES2020
   return Promise.any(IMG_ARRAY.map(element => {
-    const imgUrl = new URL(`${url.protocol}//${url.hostname}/ipfs/${element.hash}?now=${Date.now()}&filename=${element.name}#x-ipfs-companion-no-redirect`)
+    // url.host (not hostname) keeps the port, so the probe also works for local
+    // gateways on non-default ports, e.g. http://127.0.0.1:8080.
+    const imgUrl = new URL(`${url.protocol}//${url.host}/ipfs/${element.hash}?now=${Date.now()}&filename=${element.name}#x-ipfs-companion-no-redirect`)
     return checkImgSrcPromise(imgUrl)
   }))
 }
@@ -207,6 +242,10 @@ const bundle = {
       return { ...state, ipfsCheckUrl: action.payload }
     }
 
+    if (action.type === 'SET_LOCAL_GATEWAY') {
+      return { ...state, localGateway: action.payload }
+    }
+
     return state
   },
 
@@ -243,6 +282,29 @@ const bundle = {
     dispatch({ type: 'SET_IPFS_CHECK_URL', payload: url })
   },
 
+  /**
+   * @param {string} address
+   * @returns {function({dispatch: Function}): Promise<void>}
+   */
+  doUpdateLocalGateway: (address) => async ({ dispatch }) => {
+    // Normalize: remove trailing slashes
+    const normalizedAddress = address.replace(/\/+$/, '')
+    await writeSetting('ipfsLocalGateway', normalizedAddress)
+    dispatch({ type: 'SET_LOCAL_GATEWAY', payload: normalizedAddress })
+
+    // Keep kuboGateway (used by Helia/Explore) in sync with the override.
+    if (normalizedAddress) {
+      try {
+        await writeSetting('kuboGateway', localGatewayToKuboGateway(normalizedAddress))
+      } catch (e) {
+        console.error('Error syncing ipfsLocalGateway to kuboGateway:', e)
+      }
+    } else {
+      // Override cleared: restore defaults so Explore stops using the old host.
+      await writeSetting('kuboGateway', DEFAULT_KUBO_GATEWAY)
+    }
+  },
+
   /**
    * @param {any} state
    * @returns {string|null}
@@ -265,7 +327,13 @@ const bundle = {
    * @param {any} state
    * @returns {string}
    */
-  selectIpfsCheckUrl: (state) => state?.gateway?.ipfsCheckUrl
+  selectIpfsCheckUrl: (state) => state?.gateway?.ipfsCheckUrl,
+
+  /**
+   * @param {any} state
+   * @returns {string}
+   */
+  selectLocalGateway: (state) => state?.gateway?.localGateway
 }
 
 export default bundle

src/bundles/gateway.test.js

@@ -0,0 +1,43 @@
+/* global describe, it, expect */
+import { localGatewayToKuboGateway, checkValidHttpUrl } from './gateway.js'
+
+describe('localGatewayToKuboGateway', () => {
+  it('keeps an explicit port and treats http as insecure', () => {
+    expect(localGatewayToKuboGateway('http://127.0.0.1:8080')).toEqual({
+      host: '127.0.0.1',
+      port: '8080',
+      protocol: 'http',
+      trustlessBlockBrokerConfig: { init: { allowLocal: true, allowInsecure: true } }
+    })
+  })
+
+  it('defaults the port to 443 for https and keeps it secure', () => {
+    expect(localGatewayToKuboGateway('https://ipfs.example.com')).toEqual({
+      host: 'ipfs.example.com',
+      port: '443',
+      protocol: 'https',
+      trustlessBlockBrokerConfig: { init: { allowLocal: true, allowInsecure: false } }
+    })
+  })
+
+  it('defaults the port to 80 for http without an explicit port', () => {
+    expect(localGatewayToKuboGateway('http://gateway.local').port).toBe('80')
+  })
+
+  it('throws on an invalid URL', () => {
+    expect(() => localGatewayToKuboGateway('not a url')).toThrow()
+  })
+})
+
+describe('checkValidHttpUrl', () => {
+  it('accepts http and https URLs, including non-default ports', () => {
+    expect(checkValidHttpUrl('http://127.0.0.1:8080')).toBe(true)
+    expect(checkValidHttpUrl('https://ipfs.example.com')).toBe(true)
+  })
+
+  it('rejects non-http(s) and malformed values', () => {
+    expect(checkValidHttpUrl('ftp://example.com')).toBe(false)
+    expect(checkValidHttpUrl('not a url')).toBe(false)
+    expect(checkValidHttpUrl('')).toBe(false)
+  })
+})

src/bundles/ipfs-provider.js

@@ -6,6 +6,7 @@ import last from 'it-last'
 import * as Enum from '../lib/enum.js'
 import { perform } from './task.js'
 import { readSetting, writeSetting } from './local-storage.js'
+import { localGatewayToKuboGateway, DEFAULT_KUBO_GATEWAY } from './gateway.js'
 import { contextBridge } from '../helpers/context-bridge'
 import { createSelector } from 'redux-bundler'
 
@@ -332,12 +333,21 @@ const actions = {
     }
 
     const kuboGateway = readSetting('kuboGateway')
-    if (kuboGateway === null || typeof kuboGateway === 'string' || typeof kuboGateway === 'boolean' || typeof kuboGateway === 'number') {
+    const localGateway = readSetting('ipfsLocalGateway')
+
+    if (typeof localGateway === 'string' && localGateway) {
+      // User has configured a custom local gateway, sync it to kuboGateway for Helia/Explore
+      try {
+        await writeSetting('kuboGateway', localGatewayToKuboGateway(localGateway))
+      } catch (e) {
+        console.error('Error parsing ipfsLocalGateway for kuboGateway:', e)
+      }
+    } else if (kuboGateway === null || typeof kuboGateway === 'string' || typeof kuboGateway === 'boolean' || typeof kuboGateway === 'number') {
       // empty or invalid, set defaults
-      await writeSetting('kuboGateway', { trustlessBlockBrokerConfig: { init: { allowLocal: true, allowInsecure: false } } })
+      await writeSetting('kuboGateway', DEFAULT_KUBO_GATEWAY)
     } else if (/** @type {Record<string, any>} */(kuboGateway).trustlessBlockBrokerConfig == null) {
       // missing trustlessBlockBrokerConfig, set defaults
-      await writeSetting('kuboGateway', { ...kuboGateway, trustlessBlockBrokerConfig: { init: { allowLocal: true, allowInsecure: false } } })
+      await writeSetting('kuboGateway', { ...kuboGateway, ...DEFAULT_KUBO_GATEWAY })
     }
   },
 

src/components/ipns-manager/IpnsManager.js

@@ -53,7 +53,7 @@ const OptionsCell = ({ t, name, showRenameKeyModal, showRemoveKeyModal }) => {
   )
 }
 
-export const IpnsManager = ({ t, ipfsReady, doFetchIpnsKeys, doGenerateIpnsKey, doRenameIpnsKey, doRemoveIpnsKey, availableGateway, ipnsKeys }) => {
+export const IpnsManager = ({ t, ipfsReady, doFetchIpnsKeys, doGenerateIpnsKey, doRenameIpnsKey, doRemoveIpnsKey, availableGatewayUrl, ipnsKeys }) => {
   const [isGenerateKeyModalOpen, setGenerateKeyModalOpen] = useState(false)
   const showGenerateKeyModal = () => setGenerateKeyModalOpen(true)
   const hideGenerateKeyModal = () => setGenerateKeyModalOpen(false)
@@ -118,7 +118,7 @@ export const IpnsManager = ({ t, ipfsReady, doFetchIpnsKeys, doGenerateIpnsKey,
                   flexShrink={1}
                   cellRenderer={({ rowData }) => (
                     rowData.published
-                      ? <a href={`${availableGateway}/ipns/${rowData.id}`} target='_blank' rel='noopener noreferrer' className='link blue'>{rowData.id}</a>
+                      ? <a href={`${availableGatewayUrl}/ipns/${rowData.id}`} target='_blank' rel='noopener noreferrer' className='link blue'>{rowData.id}</a>
                       : rowData.id
                   )} />
                 <Column
@@ -184,7 +184,7 @@ IpnsManager.defaultProps = {
 export default connect(
   'selectIpfsReady',
   'selectIpnsKeys',
-  'selectAvailableGateway',
+  'selectAvailableGatewayUrl',
   'doFetchIpnsKeys',
   'doGenerateIpnsKey',
   'doRemoveIpnsKey',