docs/admin/installation-docker.rst

.. _installation container:

======================
Installation container
======================

.. _Docker 101: https://docs.docker.com/get-started/docker-overview
.. _Docker cheat sheet (PDF doc): https://docs.docker.com/get-started/docker_cheatsheet.pdf
.. _Podman rootless containers: https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md
.. _DockerHub mirror: https://hub.docker.com/r/searxng/searxng
.. _GHCR mirror: https://ghcr.io/searxng/searxng

.. sidebar:: info

   - `Docker 101`_
   - `Docker cheat sheet (PDF doc)`_
   - `Podman rootless containers`_

.. important::

   Understanding container architecture basics is essential for properly
   maintaining your SearXNG instance.  This guide assumes familiarity with
   container concepts and provides deployment steps at a high level.

   If you're new to containers, we recommend learning the fundamentals at

   `Docker 101`_ before proceeding.



Container images are the basis for deployments in containerized environments,

Compose, Kubernetes and more.



.. _Container installation:



Installation

============



.. _Container prerequisites:



Prerequisites

-------------



You need a working Docker or Podman installation on your system.  Choose the

option that works best for your environment:



- `Docker <https://docs.docker.com/get-docker/>`_ (recommended for most users)

- `Podman <https://podman.io/docs/installation>`_



In the case of Docker, you need to add the user running the container to the

``docker`` group and restart the session:



.. code:: sh



   $ sudo usermod -aG docker $USER



In the case of Podman, no additional steps are generally required, but there

are some considerations when running `Podman rootless containers`_.



.. _Container registries:



Registries

----------



.. note::



   DockerHub now applies rate limits to unauthenticated image pulls.  If you

   are affected by this, you can use the `GHCR mirror`_ instead.



The official images are mirrored at:



- `DockerHub mirror`_

- `GHCR mirror`_ (GitHub Container Registry)



.. _Container compose instancing:



Compose instancing

==================



This is the recommended way to deploy SearXNG in a containerized environment.

Compose templates allow you to define container configurations in a

declarative manner.



.. _Container compose instancing setup:



Setup

-----



1. Create the environment:



.. code:: sh



   # Create the environment and configuration directories

   $ mkdir -p ./searxng/core-config/

   $ cd ./searxng/



   # Fetch the latest compose template

   $ curl -fsSL \

       -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \

       -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example



2. Copy the ``.env.example`` file and edit the values as needed:



.. code:: sh



   $ cp -i .env.example .env



   # nano or your preferred text editor...

   $ nano .env



3. Start & stop the services:



.. code:: sh



   $ docker compose up -d

   $ docker compose down



4. Setup your settings in ``core-config/settings.yml`` according to your preferences.



.. _Container compose instancing maintenance:



Management

----------



.. important::



    Remember to review the new templates for any changes that may affect your

    deployment, and update the ``.env`` file accordingly.



To update the templates to their latest versions:



.. code:: sh



   $ docker compose down

   $ curl -fsSLO \

       https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \

       https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example

   $ docker compose up -d



To update the services to their latest versions:



.. code:: sh



   $ docker compose down

   $ docker compose pull

   $ docker compose up -d



List running services:



.. code:: sh



   $ docker compose ps

   NAME            IMAGE  ...  CREATED        STATUS        PORTS

   searxng-core    ...    ...  3 minutes ago  Up 3 minutes  0.0.0.0:8080->8080/tcp

   searxng-valkey  ...    ...  3 minutes ago  Up 3 minutes  6379/tcp



Print a service container logs:



.. code:: sh



   $ docker compose logs -f core



Access a service container shell (troubleshooting):



.. code:: sh



   $ docker compose exec -it --user root core /bin/sh -l

   /usr/local/searxng #



Stop and remove the services:



.. code:: sh



   $ docker compose down



.. _Container manual instancing:



Manual instancing

=================



This section is intended for advanced users who need custom deployments.  We

recommend using `Container compose instancing`_, which provides a preconfigured

environment with sensible defaults.



Basic container instancing example:



.. code:: sh



   # Create directories for configuration and persistent data

   $ mkdir -p ./searxng/config/ ./searxng/data/

   $ cd ./searxng/



   # Run the container

   $ docker run --name searxng -d \

       -p 8888:8080 \

       -v "./config/:/etc/searxng/" \

       -v "./data/:/var/cache/searxng/" \

       docker.io/searxng/searxng:latest



This will start SearXNG in the background, accessible at http://localhost:8888



.. _Container management:



Management

----------



List running containers:



.. code:: sh



   $ docker container list

   CONTAINER ID  IMAGE  ...  CREATED        PORTS                   NAMES

   1af574997e63  ...    ...  3 minutes ago  0.0.0.0:8888->8080/tcp  searxng



Print the container logs:



.. code:: sh



   $ docker container logs -f searxng



Access the container shell (troubleshooting):



.. code:: sh



   $ docker container exec -it --user root searxng /bin/sh -l

   /usr/local/searxng #



Stop and remove the container:



.. code:: sh



   $ docker container stop searxng

   $ docker container rm searxng



.. _Container volumes:



Volumes

=======



Two volumes are exposed that should be mounted to preserve its contents:



- ``/etc/searxng``: Configuration files (settings.yml, etc.)

- ``/var/cache/searxng``: Persistent data (faviconcache.db, etc.)



.. _Container environment variables:



Environment variables

=====================



The following environment variables can be configured:



- ``$SEARXNG_*``: Controls the SearXNG configuration options, look out for

  environment ``$SEARXNG_*`` in :ref:`settings server`, :ref:`settings

  general` and the :origin:`container/.env.example` template.

- ``$GRANIAN_*``: Controls the :ref:`Granian server options <Granian configuration>`.

- ``$FORCE_OWNERSHIP``: Ensures mounted volumes/files are owned by the

  ``searxng:searxng`` user (default: ``true``)



.. _Container custom certificates:



Custom certificates

===================



You can mount ``/usr/local/share/ca-certificates/`` folder to add/remove

additional certificates as needed.



They will be available on container (re)start or when running

``update-ca-certificates`` in the container shell.



This requires the container to be running with ``root`` privileges.



.. _Container custom images:



Custom images

=============



To build your own SearXNG container image from source (please note, custom

container images are not officially supported):



.. code:: sh



   $ git clone https://github.com/searxng/searxng.git

   $ cd ./searxng/



   # Run the container build script

   $ make container



   $ docker images

   REPOSITORY                 TAG                 IMAGE ID  CREATED             SIZE

   localhost/searxng/searxng  2025.8.1-3d96414    ...       About a minute ago  183 MB

   localhost/searxng/searxng  latest              ...       About a minute ago  183 MB

   localhost/searxng/searxng  builder             ...       About a minute ago  524 MB

   ghcr.io/searxng/base       searxng-builder     ...       2 days ago          378 MB

   ghcr.io/searxng/base       searxng             ...       2 days ago          42.2 MB



Migrate from ``searxng-docker``

===============================



We expect the following source directory structure:



.. code:: sh



   .

   └── searxng-docker

       ├── searxng

       │   ├── favicons.toml

       │   ├── limiter.toml

       │   ├── settings.yml

       │   └── ...

       ├── .env

       ├── Caddyfile

       ├── docker-compose.yml

       └── ...



Create a brand new environment outside ``searxng-docker`` directory, following

`Container compose instancing setup`_.



Once up and running, stop the services and move the configuration files from

the old mount to the new one:



.. code:: sh



   $ mv ./searxng-docker/searxng/* ./searxng/core-config/



If using Valkey features like bot protection (limiter), you will need to update

the URL hostname in :origin:`searx/settings.yml` file to ``valkey`` or

``searxng-valkey``.



If you have any environment variables in the old ``.env`` file, make

sure to add them to the new one.



Consider setting up a reverse proxy if exposing the instance to the public.



You should end with the following directory structure:



.. code:: sh



    .

    ├── searxng

    │   ├── core-config

    │   │   ├── favicons.toml

    │   │   ├── limiter.toml

    │   │   ├── settings.yml

    │   │   └── ...

    │   ├── .env.example

    │   ├── .env

    │   └── docker-compose.yml

    └── searxng-docker

        └── ...



If everything is working on the new environment, you can remove the old

``searxng-docker`` directory and its contents.