diff options
Diffstat (limited to 'docs/admin/installation-docker.rst')
| -rw-r--r-- | docs/admin/installation-docker.rst | 248 |
1 files changed, 125 insertions, 123 deletions
diff --git a/docs/admin/installation-docker.rst b/docs/admin/installation-docker.rst index fba7268a2..ffce2df61 100644 --- a/docs/admin/installation-docker.rst +++ b/docs/admin/installation-docker.rst @@ -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 - - `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 - $ 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 - $ 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 - $ 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 - $ 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 - $ 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 - 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 |