|
@@ -1,188 +1,190 @@
|
|
-.. _installation docker:
|
|
|
|
|
|
+.. _installation container:
|
|
|
|
|
|
-================
|
|
|
|
-Docker Container
|
|
|
|
-================
|
|
|
|
|
|
+======================
|
|
|
|
+Installation container
|
|
|
|
+======================
|
|
|
|
|
|
-.. _ENTRYPOINT: https://docs.docker.com/engine/reference/builder/#entrypoint
|
|
|
|
-.. _searxng/searxng @dockerhub: https://hub.docker.com/r/searxng/searxng
|
|
|
|
-.. _searxng-docker: https://github.com/searxng/searxng-docker
|
|
|
|
-.. _[caddy]: https://hub.docker.com/_/caddy
|
|
|
|
-.. _Redis: https://redis.io/
|
|
|
|
-
|
|
|
|
-----
|
|
|
|
|
|
+.. _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
|
|
.. sidebar:: info
|
|
|
|
|
|
- - `searxng/searxng @dockerhub`_
|
|
|
|
- - :origin:`Dockerfile`
|
|
|
|
- - `Docker overview <https://docs.docker.com/get-started/overview>`_
|
|
|
|
- - `Docker Cheat Sheet <https://docs.docker.com/get-started/docker_cheatsheet.pdf>`_
|
|
|
|
- - `Alpine Linux <https://alpinelinux.org>`_
|
|
|
|
- `(wiki) <https://en.wikipedia.org/wiki/Alpine_Linux>`__
|
|
|
|
- `apt packages <https://pkgs.alpinelinux.org/packages>`_
|
|
|
|
- - Alpine's ``/bin/sh`` is :man:`dash`
|
|
|
|
-
|
|
|
|
-**If you intend to create a public instance using Docker, use our well maintained
|
|
|
|
-docker container**
|
|
|
|
|
|
+ - `Docker 101`_
|
|
|
|
+ - `Docker cheat sheet (PDF doc)`_
|
|
|
|
+ - `Podman rootless containers`_
|
|
|
|
|
|
-- `searxng/searxng @dockerhub`_.
|
|
|
|
|
|
+.. important::
|
|
|
|
|
|
-.. sidebar:: hint
|
|
|
|
|
|
+ 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.
|
|
|
|
|
|
- The rest of this article is of interest only to those who want to create and
|
|
|
|
- maintain their own Docker images.
|
|
|
|
|
|
+ If you're new to containers, we recommend learning the fundamentals at
|
|
|
|
+ `Docker 101`_ before proceeding.
|
|
|
|
|
|
-The sources are hosted at searxng-docker_ and the container includes:
|
|
|
|
|
|
+Container images are the basis for deployments in containerized environments,
|
|
|
|
+`Docker compose`_, Kubernetes and more.
|
|
|
|
|
|
-- a HTTPS reverse proxy `[caddy]`_ and
|
|
|
|
-- a Redis_ DB
|
|
|
|
|
|
+.. _Container installation:
|
|
|
|
|
|
-The `default SearXNG setup <https://github.com/searxng/searxng-docker/blob/master/searxng/settings.yml>`_
|
|
|
|
-of this container:
|
|
|
|
|
|
+Installation
|
|
|
|
+============
|
|
|
|
|
|
-- enables :ref:`limiter <limiter>` to protect against bots
|
|
|
|
-- enables :ref:`image proxy <image_proxy>` for better privacy
|
|
|
|
-- enables :ref:`cache busting <static_use_hash>` to save bandwidth
|
|
|
|
|
|
+.. _Container prerequisites:
|
|
|
|
|
|
-----
|
|
|
|
|
|
+Prerequisites
|
|
|
|
+-------------
|
|
|
|
|
|
|
|
+You need a working Docker or Podman installation on your system. Choose the
|
|
|
|
+option that works best for your environment:
|
|
|
|
|
|
-Get Docker
|
|
|
|
-==========
|
|
|
|
|
|
+- `Docker <https://docs.docker.com/get-docker/>`_ (recommended for most users)
|
|
|
|
+- `Podman <https://podman.io/docs/installation>`_
|
|
|
|
|
|
-If you plan to build and maintain a docker image by yourself, make sure you have
|
|
|
|
-`Docker installed <https://docs.docker.com/get-docker/>`_. On Linux don't
|
|
|
|
-forget to add your user to the docker group (log out and log back in so that
|
|
|
|
-your group membership is re-evaluated):
|
|
|
|
|
|
+In the case of Docker, you need to add the user running the container to the
|
|
|
|
+``docker`` group and restart the session:
|
|
|
|
|
|
.. code:: sh
|
|
.. code:: sh
|
|
|
|
|
|
- $ sudo usermod -a -G docker $USER
|
|
|
|
-
|
|
|
|
|
|
+ $ sudo usermod -aG docker $USER
|
|
|
|
|
|
-searxng/searxng
|
|
|
|
-===============
|
|
|
|
|
|
+In the case of Podman, no additional steps are generally required, but there
|
|
|
|
+are some considerations when running `Podman rootless containers`_.
|
|
|
|
|
|
-.. sidebar:: ``docker run``
|
|
|
|
|
|
+.. _Container pulling images:
|
|
|
|
|
|
- - `-\-rm <https://docs.docker.com/engine/reference/run/#clean-up---rm>`__
|
|
|
|
- automatically clean up when container exits
|
|
|
|
- - `-d <https://docs.docker.com/engine/reference/run/#detached--d>`__ start
|
|
|
|
- detached container
|
|
|
|
- - `-v <https://docs.docker.com/engine/reference/run/#volume-shared-filesystems>`__
|
|
|
|
- mount volume ``HOST:CONTAINER``
|
|
|
|
|
|
+Pulling images
|
|
|
|
+--------------
|
|
|
|
|
|
-The docker image is based on :origin:`Dockerfile` and available from
|
|
|
|
-`searxng/searxng @dockerhub`_. Using the docker image is quite easy, for
|
|
|
|
-instance you can pull the `searxng/searxng @dockerhub`_ image and deploy a local
|
|
|
|
-instance using `docker run <https://docs.docker.com/engine/reference/run/>`_:
|
|
|
|
|
|
+.. note::
|
|
|
|
|
|
-.. code:: sh
|
|
|
|
|
|
+ DockerHub now applies rate limits to unauthenticated image pulls. If you
|
|
|
|
+ are affected by this, you can use the `GHCR mirror`_ instead.
|
|
|
|
|
|
- $ mkdir my-instance
|
|
|
|
- $ cd my-instance
|
|
|
|
- $ export PORT=8080
|
|
|
|
- $ docker pull searxng/searxng
|
|
|
|
- $ docker run --rm \
|
|
|
|
- -d -p ${PORT}:8080 \
|
|
|
|
- -v "${PWD}/searxng:/etc/searxng" \
|
|
|
|
- -e "BASE_URL=http://localhost:$PORT/" \
|
|
|
|
- -e "INSTANCE_NAME=my-instance" \
|
|
|
|
- searxng/searxng
|
|
|
|
- 2f998.... # container's ID
|
|
|
|
|
|
+The official images are mirrored at:
|
|
|
|
|
|
-The environment variables UWSGI_WORKERS and UWSGI_THREADS overwrite the default
|
|
|
|
-number of UWSGI processes and UWSGI threads specified in `/etc/searxng/uwsgi.ini`.
|
|
|
|
|
|
+- `DockerHub mirror`_
|
|
|
|
+- `GHCR mirror`_ (GitHub Container Registry)
|
|
|
|
|
|
-Open your WEB browser and visit the URL:
|
|
|
|
|
|
+Pull the latest image:
|
|
|
|
|
|
.. code:: sh
|
|
.. code:: sh
|
|
|
|
|
|
- $ xdg-open "http://localhost:$PORT"
|
|
|
|
|
|
+ $ docker pull docker.io/searxng/searxng:latest
|
|
|
|
|
|
-Inside ``${PWD}/searxng``, you will find ``settings.yml`` and ``uwsgi.ini``. You
|
|
|
|
-can modify these files according to your needs and restart the Docker image.
|
|
|
|
|
|
+\.\. or if you want to lock in to a specific version:
|
|
|
|
|
|
.. code:: sh
|
|
.. code:: sh
|
|
|
|
|
|
- $ docker container restart 2f998
|
|
|
|
|
|
+ $ docker pull docker.io/searxng/searxng:2025.6.3-b73ac81
|
|
|
|
|
|
-Use command ``container ls`` to list running containers, add flag `-a
|
|
|
|
-<https://docs.docker.com/engine/reference/commandline/container_ls>`__ to list
|
|
|
|
-exited containers also. With ``container stop`` a running container can be
|
|
|
|
-stopped. To get rid of a container use ``container rm``:
|
|
|
|
|
|
+.. _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
|
|
.. code:: sh
|
|
|
|
|
|
- $ docker container ls
|
|
|
|
- CONTAINER ID IMAGE COMMAND CREATED ...
|
|
|
|
- 2f998d725993 searxng/searxng "/sbin/tini -- /usr/…" 7 minutes ago ...
|
|
|
|
|
|
+ # Create directories for configuration and persistent data
|
|
|
|
+ $ mkdir -p ./searxng/config/ ./searxng/data/
|
|
|
|
+ $ cd ./searxng/
|
|
|
|
|
|
- $ docker container stop 2f998
|
|
|
|
- $ docker container rm 2f998
|
|
|
|
|
|
+ # 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
|
|
|
|
|
|
-.. sidebar:: Warning
|
|
|
|
|
|
+This will start SearXNG in the background, accessible at http://localhost:8888
|
|
|
|
|
|
- This might remove all docker items, not only those from SearXNG.
|
|
|
|
|
|
+.. _Container management:
|
|
|
|
|
|
-If you won't use docker anymore and want to get rid of all containers & images
|
|
|
|
-use the following *prune* command:
|
|
|
|
|
|
+Management
|
|
|
|
+----------
|
|
|
|
|
|
-.. code:: sh
|
|
|
|
|
|
+List running containers:
|
|
|
|
|
|
- $ docker stop $(docker ps -aq) # stop all containers
|
|
|
|
- $ docker system prune # make some housekeeping
|
|
|
|
- $ docker rmi -f $(docker images -q) # drop all images
|
|
|
|
|
|
+.. code:: sh
|
|
|
|
|
|
|
|
+ $ docker container list
|
|
|
|
+ CONTAINER ID IMAGE ... CREATED PORTS NAMES
|
|
|
|
+ 37f6487c8703 ... ... 3 minutes ago 0.0.0.0:8888->8080/tcp searxng
|
|
|
|
|
|
-shell inside container
|
|
|
|
-----------------------
|
|
|
|
|
|
+Access the container shell (troubleshooting):
|
|
|
|
|
|
-.. sidebar:: Bashism
|
|
|
|
|
|
+.. code:: sh
|
|
|
|
|
|
- - `A tale of two shells: bash or dash <https://lwn.net/Articles/343924/>`_
|
|
|
|
- - `How to make bash scripts work in dash <http://mywiki.wooledge.org/Bashism>`_
|
|
|
|
- - `Checking for Bashisms <https://dev.to/bowmanjd/writing-bash-scripts-that-are-not-only-bash-checking-for-bashisms-and-testing-with-dash-1bli>`_
|
|
|
|
|
|
+ $ docker container exec -it --user root searxng /bin/sh -l
|
|
|
|
+ 37f6487c8703:/usr/local/searxng#
|
|
|
|
|
|
-To open a shell inside the container:
|
|
|
|
|
|
+Stop and remove the container:
|
|
|
|
|
|
.. code:: sh
|
|
.. code:: sh
|
|
|
|
|
|
- $ docker exec -it 2f998 sh
|
|
|
|
|
|
+ $ docker container stop searxng
|
|
|
|
+ $ docker container rm searxng
|
|
|
|
|
|
|
|
+.. _Container volumes:
|
|
|
|
|
|
-Build the image
|
|
|
|
-===============
|
|
|
|
|
|
+Volumes
|
|
|
|
+=======
|
|
|
|
|
|
-It's also possible to build SearXNG from the embedded :origin:`Dockerfile`::
|
|
|
|
|
|
+Two volumes are exposed that should be mounted to preserve its contents:
|
|
|
|
|
|
- $ git clone https://github.com/searxng/searxng.git
|
|
|
|
- $ cd searxng
|
|
|
|
- $ make docker.build
|
|
|
|
- ...
|
|
|
|
- Successfully built 49586c016434
|
|
|
|
- Successfully tagged searxng/searxng:latest
|
|
|
|
- Successfully tagged searxng/searxng:1.0.0-209-9c823800-dirty
|
|
|
|
|
|
+- ``/etc/searxng``: Configuration files (settings.yml, etc.)
|
|
|
|
+- ``/var/cache/searxng``: Persistent data (faviconcache.db, etc.)
|
|
|
|
|
|
- $ docker images
|
|
|
|
- REPOSITORY TAG IMAGE ID CREATED SIZE
|
|
|
|
- searxng/searxng 1.0.0-209-9c823800-dirty 49586c016434 13 minutes ago 308MB
|
|
|
|
- searxng/searxng latest 49586c016434 13 minutes ago 308MB
|
|
|
|
- alpine 3.13 6dbb9cc54074 3 weeks ago 5.61MB
|
|
|
|
|
|
+.. _Container environment variables:
|
|
|
|
|
|
|
|
+Environment variables
|
|
|
|
+=====================
|
|
|
|
|
|
-Command line
|
|
|
|
-============
|
|
|
|
|
|
+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):
|
|
|
|
|
|
-.. sidebar:: docker run
|
|
|
|
|
|
+- ``$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``)
|
|
|
|
|
|
- Use flags ``-it`` for `interactive processes
|
|
|
|
- <https://docs.docker.com/engine/reference/run/#foreground>`__.
|
|
|
|
|
|
+.. _Container custom images:
|
|
|
|
|
|
-In the :origin:`Dockerfile` the ENTRYPOINT_ is defined as
|
|
|
|
-:origin:`container/entrypoint.sh`
|
|
|
|
|
|
+Custom images
|
|
|
|
+=============
|
|
|
|
+
|
|
|
|
+To build your own SearXNG container image from source (please note, custom
|
|
|
|
+container images are not officially supported):
|
|
|
|
|
|
.. code:: sh
|
|
.. code:: sh
|
|
|
|
|
|
- docker run --rm -it searxng/searxng -h
|
|
|
|
|
|
+ $ 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
|