Degoog Documentation

If you are new to self hosting, click here to jump straight to our beginner guide at the bottom of the page where we walk you through setting up Docker from scratch.

Overview

Degoog can be customised with plugins, themes, search engines, transports, and aliases. Extensions live under data/ and can be installed from Store repositories (git repos you add in Settings then Store).

Running Degoog

By default the app will run on port 4444 with user 1000:1000. Please check the environment variable documentation for a comprehensive list of configuration options.

First, prepare your data directory:

mkdir -p ./data
        sudo chown -R 1000:1000 ./data

Docker Compose

services:
          degoog:
            image: ghcr.io/degoog-org/degoog:latest
            volumes:
              - ./data:/app/data
            ports:
              - "4444:4444"
            restart: unless-stopped

Inline podman

podman run -d --name degoog -p 4444:4444 -v ./data:/app/data --security-opt label=disable --restart unless-stopped ghcr.io/degoog-org/degoog:latest

Podman Quadlet Container File

[Unit]
        Description=Degoog selfhosted search aggregator
        Wants=network-online.target
        After=network-online.target
        
        [Container]
        Image=ghcr.io/degoog-org/degoog:latest
        AutoUpdate=registry
        ContainerName=degoog
        Environment=TZ=<Country/City>
        Environment=PUID=1000
        Environment=PGID=1000
        UIDMap=+%U:@%U
        Volume=<Path to config>:/app/data:Z
        PublishPort=4444:4444
        Network=degoog
        
        [Service]
        Restart=always
        
        [Install]
        WantedBy=default.target

Inline docker

docker run -d --name degoog -p 4444:4444 -v ./data:/app/data --restart unless-stopped ghcr.io/degoog-org/degoog:latest

Run natively

You will need a .env file for your env variables and the following required dependencies: bun, git, and curl.

git clone https://github.com/degoog-org/degoog.git
        cd degoog
        bun install
        bun run build
        bun run start

Note: If HTTPS requests fail with certificate errors, install the ca-certificates package.

Default enabled or disabled engines

Search engines have two separate layers of enabled state: instance defaults and your browser saved selection.

• Instance defaults (server side): on startup, Degoog computes a default enabled or disabled value for every engine. Engines that are marked as disabled by default, or engines that have required settings that are not configured, start out disabled. You can override these defaults by saving a data/default-engines.json file (this is what the Settings then Engines Save defaults button writes).
• Your selection (client side): the Engines tab stores your toggles in your browser IndexedDB. Those saved values take priority over the instance defaults for that browser or profile, so your choice persists even if the server defaults change later.

Example data/default-engines.json:

{
          "google": true,
          "duckduckgo": true,
          "bing": false,
          "engine-my-custom-engine": true
        }

When you toggle engines on the Engines tab, the state is sent along with each search request, so different users can use different engine sets at the same time.

Where things live

Quick start

1. Open Settings then Store.
2. Add a repo: paste https://github.com/degoog-org/official-extensions.git and add it.
3. Browse the Store tab and install a plugin (like Weather) or theme (like Zen).

The official extensions repo is automatically added to your instance when you start it for the first time.

Use as your browser default search engine

Any browser that supports custom search engines can use degoog. Replace https://your-instance with your actual instance URL.

Browsers that support OpenSearch can detect degoog automatically. Right clicking the search bar on your instance will offer to add it.

Extension types

• Plugins: Bang commands (!weather London), result slots, search result tabs, search bar actions, API routes, middleware.
• Themes: Override CSS and optionally home or search HTML.
• Search engines: Custom search backends (web, images, video).
• Transports: Custom HTTP fetch strategies (like fetch or curl).
• Store: Add git repos and install extensions from them.
• Aliases: Custom command mappings.

Beginner guide to Docker

Welcome! If you are reading this, you might be new to running your own software. Let us break it down simply. Think of Docker as a shipping container. Instead of installing all the messy requirements for an app directly onto your computer, Docker grabs a neat pre packaged box that has everything the app needs to run perfectly. All you do is tell Docker to start the box.

To get started, you will need to install Docker Desktop if you are on Windows or Mac, or Docker Engine if you are using Linux. Once installed, the easiest way to launch Degoog is using something called Docker Compose. It uses a simple text file to tell Docker exactly how to run the container. Just copy the Docker Compose text block from the Run section above, save it in a folder as docker-compose.yml, open your terminal or command prompt in that folder, and type docker compose up -d.

That command pulls the Degoog box from the internet and starts it up quietly in the background. Once it finishes, you can just open your web browser and go to http://localhost:4444 to see your brand new search engine.