degoog-org · fccview · May 5, 2026 · May 1, 2026 · May 1, 2026 · May 1, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,8 +6,8 @@
 
 # Coding standards
 
-- **Functions that return a value** — use arrow functions (e.g. `const getX = () => value`).
-- **Functions that do not return** (side-effect only) — use regular `function` declarations.
-- **Internal / private helpers** — prepend with `_` (e.g. `_parseQuery`, `_formatDate`).
-- **CSS** — Reuse existing app classes where possible (see [Styling](docs/styling.html) for a list). Must use SCSS/CSS variables (e.g. `$primary or var(--text-primary)`) so themes and light/dark mode keep working wel.
-- **Structure** — Keep things modular; follow the existing folder structure (e.g. one folder per plugin, one file or folder per engine).
+- **Functions that return a value** - use arrow functions (e.g. `const getX = () => value`).
+- **Functions that do not return** (side-effect only) - use regular `function` declarations.
+- **Internal / private helpers** - prepend with `_` (e.g. `_parseQuery`, `_formatDate`).
+- **CSS** - Reuse existing app classes where possible (see [Styling](docs/styling.html) for a list). Must use SCSS/CSS variables (e.g. `$primary or var(--text-primary)`) so themes and light/dark mode keep working wel.
+- **Structure** - Keep things modular; follow the existing folder structure (e.g. one folder per plugin, one file or folder per engine).
diff --git a/Dockerfile b/Dockerfile
@@ -12,7 +12,7 @@ COPY . .
 RUN bun run build
 
 FROM base AS release
-RUN apk add --no-cache git ca-certificates gosu curl
+RUN apk add --no-cache git ca-certificates su-exec curl
 
 COPY --from=install /app/node_modules ./node_modules
 COPY --from=build /app/src ./src

diff --git a/bun.lock b/bun.lock
diff --git a/docs/aliases.html b/docs/aliases.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Aliases — Degoog docs</title>
+    <title>Aliases - Degoog docs</title>
     <script>
       (function () {
         try {

diff --git a/docs/api.html b/docs/api.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>API reference — Degoog docs</title>
+    <title>API reference - Degoog docs</title>
     <script>
       (function () {
         try {
@@ -152,6 +152,28 @@ <h2>Overview</h2>
             Server, and these limits will apply to every caller.
           </p>
 
+          <h2>API key protection (optional)</h2>
+          <p>
+            In Settings -> Server you can require authentication for search, search
+            stream, search retry, and suggest. When that is enabled for a route,
+            requests without valid credentials receive
+            <code>401</code> and a JSON body such as
+            <code>{"error":"Unauthorized"}</code>.
+          </p>
+          <p>
+            For external callers (scripts, integrations,
+            <code>curl</code>, Open WebUI, etc.), use the API key from the same
+            settings screen (the 64-character hexadecimal value) as a Bearer token.
+            The server compares it to the stored secret; only that exact key is
+            accepted.
+          </p>
+          <pre><code>curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
+  "http://localhost:4444/api/search?q=hello"</code></pre>
+          <p>
+            The in-browser UI does not rely on this header; it uses a separate
+            short-lived nonce supplied with the page when protection is on.
+          </p>
+
           <h2><code>GET /api/search</code></h2>
           <p>Run a metasearch and get merged and scored results.</p>
           <table>
@@ -296,6 +318,12 @@ <h2>
             Just remember to replace <code>http://127.0.0.1:4444</code> with
             your actual Degoog address.
           </p>
+          <p>
+            If you enabled API key protection for search, configure your client to
+            send <code>Authorization: Bearer …</code> with your instance key as
+            described above (Open WebUI must support custom headers for the search
+            URL if you use that mode).
+          </p>
         </main>
       </div>
       <div id="ade-backdrop" class="ade-backdrop"></div>

diff --git a/docs/engines.html b/docs/engines.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Search engines — Degoog docs</title>
+    <title>Search engines - Degoog docs</title>
     <script>
       (function () {
         try {
@@ -303,6 +303,16 @@ <h2>Language &amp; time filters</h2>
                   target a specific thumbnail container first.
                 </td>
               </tr>
+              <tr>
+                <td><code>context.signProxyUrl(url)</code></td>
+                <td><code>(url: string) =&gt; string</code></td>
+                <td>
+                  Returns a signed <code>/api/proxy/image</code> URL for the
+                  given external image URL. Use this when you include thumbnails
+                  in your results so they load correctly regardless of the
+                  outgoing allowlist configuration.
+                </td>
+              </tr>
             </tbody>
           </table>
           <p>
@@ -388,16 +398,8 @@ <h2>Proxies</h2>
               Use <code>context.fetch</code> for every outbound HTTP request
               instead of the global <code>fetch</code>.
             </li>
-            <li>
-              Export <strong>outgoingHosts</strong> as an array of hostname
-              strings without the protocol or path. These hostnames get added to
-              the proxy allowlist. Only use <code>["*"]</code> if your engine
-              needs to fetch from random user provided URLs.
-            </li>
           </ol>
-          <pre><code>export const outgoingHosts = ["www.example.com", "example.com"];
-
-export default class MyEngine {
+          <pre><code>export default class MyEngine {
   name = "My Search";
   async executeSearch(query, page = 1, _timeFilter, context) {
     const url = `https://www.example.com/search?q=${encodeURIComponent(query)}`;
@@ -457,9 +459,8 @@ <h2>Examples from the official store</h2>
                 rel="noopener"
                 >Ecosia</a
               >
-              is a web engine using <code>outgoingHosts</code> and
-              <code>bangShortcut</code> while correctly utilizing
-              <code>context.fetch</code>.
+              is a web engine using <code>bangShortcut</code> while correctly
+              utilizing <code>context.fetch</code>.
             </li>
             <li>
               <a

diff --git a/docs/env.html b/docs/env.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Environment variables — Degoog docs</title>
+    <title>Environment variables - Degoog docs</title>
     <script>
       (function () {
         try {
@@ -152,6 +152,25 @@ <h2>General</h2>
                 <td>The port your server listens on.</td>
                 <td><code>4444</code></td>
               </tr>
+              <tr>
+                <td><code>DEGOOG_BASE_URL</code></td>
+                <td>
+                  Base path for serving Degoog behind a reverse proxy at a
+                  sub-path. The expected value is a path like
+                  <code>/degoog</code>. A full URL is also accepted -
+                  <code>https://example.com/degoog</code> behaves the same as
+                  <code>/degoog</code> since only the path portion is used.
+                  A bare domain with no sub-path (e.g.
+                  <code>https://degoog.org</code>) has no effect since there
+                  is no path to prepend. When unset, Degoog is served at the
+                  root <code>/</code> as usual.
+                  <br /><br />
+                  <strong>Note:</strong> the OpenSearch XML descriptor always
+                  uses only the path portion of this value so that its URLs
+                  remain valid regardless of how the variable was set.
+                </td>
+                <td></td>
+              </tr>
               <tr>
                 <td><code>DEGOOG_SETTINGS_PASSWORDS</code></td>
                 <td>
@@ -187,34 +206,33 @@ <h2>General</h2>
               <tr>
                 <td><code>DEGOOG_DEFAULT_SEARCH_LANGUAGE</code></td>
                 <td>
-                  The default ISO 639 1 language code applied to all searches
-                  when a user does not select a specific language (like
-                  <code>en</code>, <code>de</code>, or <code>it</code>).
+                  Default ISO 639-1 language code applied to all searches when
+                  searches when no language is selected by the user (e.g.
+                  <code>en</code>, <code>de</code>, <code>it</code>).
                 </td>
                 <td><code>en-US</code></td>
               </tr>
               <tr>
                 <td><code>DEGOOG_I18N</code></td>
                 <td>
-                  This forces the UI locale for all requests and overrides the
-                  <code>Accept-Language</code> header (for example
-                  <code>en-US</code> or <code>fr-FR</code>). When you set this,
-                  the normal locale pipeline runs but uses this as the source.
-                  If left empty, it falls back to the
-                  <code>Accept-Language</code> header.
+                  Forces the UI locale for all requests, overriding the
+                  <code>Accept-Language</code> header (e.g. <code>en-US</code>,
+                  <code>fr-FR</code>). When set, the same locale pipeline runs
+                  as normal - only the source changes. Unset or empty:
+                  <code>Accept-Language</code> is used as today.
                 </td>
                 <td></td>
               </tr>
               <tr>
                 <td><code>LOG_LEVEL</code></td>
                 <td>
-                  Controls how verbose your server console output is. Supported
-                  levels from most to least severe are <code>fatal</code>,
-                  <code>error</code>, <code>warn</code>, <code>info</code>,
-                  <code>log</code>, and <code>debug</code>. Each level includes
-                  all messages of higher severity. Use <code>debug</code> to
-                  print absolutely everything, including your plugin execution
-                  times. If you use Docker, you can view your logs by running
+                  Controls the verbosity of server-side console output.
+                  Supported levels from most to least severe:
+                  <code>fatal</code>, <code>error</code>, <code>warn</code>,
+                  <code>info</code>, <code>log</code>, <code>debug</code>. Each
+                  level includes all levels of higher severity. Set to
+                  <code>debug</code> to print all messages, including plugin
+                  execution times. If you use docker you can view your logs with
                   <code>docker compose logs -f</code>.
                 </td>
                 <td><code>info</code></td>
@@ -293,6 +311,18 @@ <h2>Plugins, themes, engines</h2>
                 </td>
                 <td><code>data/plugin-settings.json</code></td>
               </tr>
+              <tr>
+                <td><code>DEGOOG_DEFAULT_ENGINES_FILE</code></td>
+                <td>
+                  Path to the JSON file storing default enabled/disabled engines
+                </td>
+                <td><code>data/default-engines.json</code></td>
+              </tr>
+              <tr>
+                <td><code>DEGOOG_SETTINGS_TOKENS_FILE</code></td>
+                <td>Path to the JSON file storing settings tokens</td>
+                <td><code>data/settings-tokens.json</code></td>
+              </tr>
               <tr>
                 <td><code>DEGOOG_ALIASES_FILE</code></td>
                 <td>

diff --git a/docs/index.html b/docs/index.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Degoog — Documentation</title>
+    <title>Degoog - Documentation</title>
     <script>
       (function () {
         try {

diff --git a/docs/plugins.html b/docs/plugins.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Plugins — Degoog docs</title>
+    <title>Plugins - Degoog docs</title>
     <script>
       (function () {
         try {
@@ -199,7 +199,37 @@ <h3>Plugin context and init()</h3>
   // ctx.template contains your template.html
   // ctx.dir is the absolute path to your plugin folder
   // ctx.readFile is an async function to read any file from your plugin folder
+  // ctx.signProxyUrl(url) returns a signed /api/proxy/image URL for any external image
+  // ctx.fetch(url, init?) is a proxy-aware fetch, respects your outgoing proxy settings
+  // ctx.createCache(defaultTtlMs) returns an in-memory TTL cache { get, set, clear }
 }</code></pre>
+          <h3>TTL cache (<code>createCache</code>)</h3>
+          <p>
+            Both <code>init(ctx)</code> and slot <code>execute(query, context)</code>
+            receive <strong><code>createCache</code></strong>: a factory compatible with
+            the built-in server helper. Call
+            <code>ctx.createCache&lt;T&gt;(defaultTtlMs)</code> (or
+            <code>context.createCache&lt;T&gt;(defaultTtlMs)</code> in slots) to get an
+            object with <code>get(key)</code>, <code>set(key, value, ttlMs?)</code>, and
+            <code>clear()</code>. Keys are strings; values are typed by your generic
+            <code>T</code>. Entries expire automatically after the TTL (milliseconds).
+          </p>
+          <p>
+            Built-in and third-party code paths share this API: typical usage is to
+            call <code>createCache</code> once in <code>init</code>, keep the returned
+            cache on a module-level variable, and reuse <code>get</code> /
+            <code>set</code> from <code>execute</code> (for example for fetched page
+            excerpts). Prefer <strong>always</strong> using
+            <code>ctx.createCache</code> / <code>context.createCache</code> rather than
+            importing cache helpers from server internals so plugins behave the same in
+            every environment.
+          </p>
+          <p>
+            Store <code>ctx.fetch</code> during <code>init</code> if your plugin
+            makes outgoing HTTP requests outside of <code>execute()</code>, for
+            example inside custom plugin routes. Using it keeps your requests
+            consistent with the proxy settings configured in Settings.
+          </p>
           <p>
             For example, you might build a plugin that uses both a command
             template and a separate card template. The
@@ -242,7 +272,11 @@ <h2 id="bang-commands">Bang commands</h2>
           <p>
             The second argument passed to <code>execute</code> is
             <code>context</code>, which might contain your
-            <code>clientIp</code> and <code>page</code>.
+            <code>clientIp</code>, <code>page</code>, and
+            <code>signProxyUrl(url)</code>. Call
+            <code>context.signProxyUrl</code> to get a signed
+            <code>/api/proxy/image</code> URL for any external image you want to
+            serve through the built-in image proxy.
           </p>
           <p>
             You can also include optional properties like
@@ -388,10 +422,14 @@ <h2>Slot plugins</h2>
               <strong>execute(query, context)</strong> (async): Return an object
               with an optional <code>title</code> string and an
               <code>html</code> string. If you return an empty string for the
-              html, nothing will show up. The <code>context</code> contains the
-              <code>clientIp</code> and an array of <code>results</code>. Note
-              that the results array is only populated if you set
-              <code>waitForResults: true</code> on your plugin.
+              html, nothing will show up. The <code>context</code> includes
+              <code>clientIp</code>; <code>results</code> (only when
+              <code>waitForResults: true</code>); proxy-aware
+              <code>fetch(url, init?)</code>; <code>signProxyUrl(url)</code> for
+              external images; and <code>createCache(defaultTtlMs)</code> for the same
+              TTL cache factory as in <code>init(ctx)</code>. Note that the results
+              array is only populated if you set <code>waitForResults: true</code> on
+              your plugin.
             </li>
           </ul>
           <p>

diff --git a/docs/store.html b/docs/store.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Store repositories — Degoog docs</title>
+    <title>Store repositories - Degoog docs</title>
     <script>
       (function () {
         try {

diff --git a/docs/style.css b/docs/style.css
@@ -52,7 +52,7 @@ html[data-theme="dark"] {
   --ade-bg: #0f0e0d;
   --ade-surface: #171614;
   --ade-sidebar-bg: #131210;
-  --ade-border: #2c2b27;
+  --ade-border: #636055;
   --ade-text: #e2dfd6;
   --ade-text-muted: #857f74;
   --ade-active-bg: #252420;

diff --git a/docs/styling.html b/docs/styling.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Styling — Degoog docs</title>
+    <title>Styling - Degoog docs</title>
     <script>
       (function () {
         try {

diff --git a/docs/themes.html b/docs/themes.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Themes — Degoog docs</title>
+    <title>Themes - Degoog docs</title>
     <script>
       (function () {
         try {