[doc] build from commit ff2e0ea278

_sources/admin/installation-docker.rst.txt

@@ -0,0 +1,190 @@
+.. _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
+.. _Docker compose: https://github.com/searxng/searxng-docker
+
+.. 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,
+`Docker 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 pulling images:
+
+Pulling images
+--------------
+
+.. 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)
+
+Pull the latest image:
+
+.. code:: sh
+
+   $ docker pull docker.io/searxng/searxng:latest
+
+\.\. or if you want to lock in to a specific version:
+
+.. code:: sh
+
+   $ docker pull docker.io/searxng/searxng:2025.6.3-b73ac81
+
+.. _Container instancing:
+
+Instancing
+==========
+
+This section is intended for advanced users who need custom deployments.  We
+recommend using `Docker compose`_, 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 --replace -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
+   37f6487c8703  ...    ...  3 minutes ago  0.0.0.0:8888->8080/tcp  searxng
+
+Access the container shell (troubleshooting):
+
+.. code:: sh
+
+   $ docker container exec -it --user root searxng /bin/sh -l
+   37f6487c8703:/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` and :ref:`settings
+  general`.
+- ``$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 internal paths (don't modify unless you know what you're doing):
+
+- ``$CONFIG_PATH``: Path to the SearXNG configuration directory (default: ``/etc/searxng``)
+- ``$SEARXNG_SETTINGS_PATH``: Path to the SearXNG settings file (default: ``$CONFIG_PATH/settings.yml``)
+- ``$DATA_PATH``: Path to the SearXNG data directory (default: ``/var/cache/searxng``)
+
+.. _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  latest                    b14e256bfc36  14 seconds ago  201 MB
+   localhost/searxng/searxng  2025.5.1-b653119ab-dirty  b14e256bfc36  14 seconds ago  201 MB
+   localhost/searxng/searxng  builder                   7f334c752b41  20 seconds ago  765 MB
+   ghcr.io/searxng/base       searxng-builder           7d6b8a1bed4a  20 hours ago    625 MB
+   ghcr.io/searxng/base       searxng                   29baf9ef13ef  20 hours ago    62.5 MB