[mod] container: rework compose (#5906)

* [mod] container: rework compose

See https://docs.searxng.org/admin/installation-docker.html#migrate-from-searxng-docker

* [mod] container: apply suggestions

https://github.com/searxng/searxng/pull/5906#discussion_r3004917087
https://github.com/searxng/searxng/pull/5906#discussion_r3004917090
https://github.com/searxng/searxng/pull/5906#discussion_r3004917084

container/.env.example

@@ -0,0 +1,15 @@
+# Read the documentation before using the `docker-compose.yml` file:
+# https://docs.searxng.org/admin/installation-docker.html
+#
+# Additional ENVs:
+# https://docs.searxng.org/admin/settings/settings_general.html#settings-general
+# https://docs.searxng.org/admin/settings/settings_server.html#settings-server
+
+# Use a specific version tag. E.g. "latest" or "2026.3.25-541c6c3cb".
+#SEARXNG_VERSION=latest
+
+# Listen to a specific address.
+#SEARXNG_HOST=[::]
+
+# Listen to a specific port.
+#SEARXNG_PORT=8080

container/dist.dockerfile

@@ -24,8 +24,8 @@ LABEL org.opencontainers.image.created="$CREATED" \
     org.opencontainers.image.url="https://searxng.org" \
     org.opencontainers.image.version="$VERSION"
 
-ENV SEARXNG_VERSION="$VERSION" \
+ENV __SEARXNG_VERSION="$VERSION" \
-    SEARXNG_SETTINGS_PATH="$CONFIG_PATH/settings.yml" \
+    __SEARXNG_SETTINGS_PATH="$__SEARXNG_CONFIG_PATH/settings.yml" \
     GRANIAN_PROCESS_NAME="searxng" \
     GRANIAN_INTERFACE="wsgi" \
     GRANIAN_HOST="::" \
@@ -36,8 +36,8 @@ ENV SEARXNG_VERSION="$VERSION" \
     GRANIAN_BLOCKING_THREADS_IDLE_TIMEOUT="5m"
 
 # "*_PATH" ENVs are defined in base images
-VOLUME $CONFIG_PATH
+VOLUME $__SEARXNG_CONFIG_PATH
-VOLUME $DATA_PATH
+VOLUME $__SEARXNG_DATA_PATH
 
 EXPOSE 8080
 

container/docker-compose.yml

@@ -0,0 +1,28 @@
+# Read the documentation before using the `docker-compose.yml` file:
+# https://docs.searxng.org/admin/installation-docker.html
+
+name: searxng
+
+services:
+  core:
+    container_name: searxng-core
+    image: docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}
+    restart: always
+    ports:
+      - ${SEARXNG_HOST:+${SEARXNG_HOST}:}${SEARXNG_PORT:-8080}:${SEARXNG_PORT:-8080}
+    env_file: ./.env
+    volumes:
+      - ./core-config/:/etc/searxng/:Z
+      - core-data:/var/cache/searxng/
+
+  valkey:
+    container_name: searxng-valkey
+    image: docker.io/valkey/valkey:9-alpine
+    command: valkey-server --save 30 1 --loglevel warning
+    restart: always
+    volumes:
+      - valkey-data:/data/
+
+volumes:
+  core-data:
+  valkey-data:

container/entrypoint.sh

@@ -117,16 +117,22 @@ EOF
 }
 
 cat <<EOF
-SearXNG $SEARXNG_VERSION
+SearXNG $__SEARXNG_VERSION
 EOF
 
 # Check for volume mounts
-volume_handler "$CONFIG_PATH"
+volume_handler "$__SEARXNG_CONFIG_PATH"
-volume_handler "$DATA_PATH"
+volume_handler "$__SEARXNG_DATA_PATH"
 
 # Check for files
-config_handler "$SEARXNG_SETTINGS_PATH" "/usr/local/searxng/searx/settings.yml"
+config_handler "$__SEARXNG_SETTINGS_PATH" "/usr/local/searxng/searx/settings.yml"
 
-update-ca-certificates
+# root only features
+if [ "$(id -u)" -eq 0 ]; then
+    update-ca-certificates
+fi
+
+# ENVs aliases
+export GRANIAN_PORT="${SEARXNG_PORT:-$GRANIAN_PORT}"
 
 exec /usr/local/searxng/.venv/bin/granian searx.webapp:app

docs/admin/installation-docker.rst

@@ -9,7 +9,6 @@ Installation container
 .. _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
 
@@ -27,7 +26,7 @@ Installation container
    `Docker 101`_ before proceeding.
 
 Container images are the basis for deployments in containerized environments,
-`Docker compose`_, Kubernetes and more.
+Compose, Kubernetes and more.
 
 .. _Container installation:
 
@@ -55,10 +54,10 @@ In the case of Docker, you need to add the user running the container to the
 In the case of Podman, no additional steps are generally required, but there
 are some considerations when running `Podman rootless containers`_.
 
-.. _Container pulling images:
+.. _Container registries:
 
-Pulling images
+Registries
---------------
+----------
 
 .. note::
 
@@ -70,26 +69,108 @@ The official images are mirrored at:
 - `DockerHub mirror`_
 - `GHCR mirror`_ (GitHub Container Registry)
 
-Pull the latest image:
+.. _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
 
-   $ docker pull docker.io/searxng/searxng:latest
+   # Create the environment and configuration directories
+   $ mkdir -p ./searxng/core-config/
+   $ cd ./searxng/
 
-\.\. or if you want to lock in to a specific version:
+   # Fetch the latest compose template
+   $ curl -fsSLO \
+       https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
+       https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
+
+2. Rename the ``.env.example`` file to ``.env`` and edit the values as needed.
+
+3. Start & stop the services:
 
 .. code:: sh
 
-   $ docker pull docker.io/searxng/searxng:2025.8.1-3d96414
+   $ docker compose up -d
+   $ docker compose down
 
-.. _Container instancing:
+4. Setup your settings in ``core-config/settings.yml`` according to your preferences.
 
-Instancing
+.. _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 `Docker compose`_, which provides a preconfigured environment
+recommend using `Container compose instancing`_, which provides a preconfigured
-with sensible defaults.
+environment with sensible defaults.
 
 Basic container instancing example:
 
@@ -121,12 +202,18 @@ List running containers:
    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
-   1af574997e63:/usr/local/searxng#
+   /usr/local/searxng #
 
 Stop and remove the container:
 
@@ -153,18 +240,12 @@ 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
+  environment ``$SEARXNG_*`` in :ref:`settings server`, :ref:`settings
-  general`.
+  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 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 certificates:
 
 Custom certificates
@@ -176,6 +257,8 @@ 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
@@ -199,3 +282,57 @@ container images are not officially supported):
    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 you have any custom environment variables in the old ``.env`` file, make
+sure to add them manually 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.