mirror of
https://github.com/searxng/searxng.git
synced 2025-07-09 03:04:26 -04:00
01be2612ab
* [mod] container: replace uWSGI with Granian The configuration in Granian is handled with ENVs, much more convenient and practical for updating. The settings have been tested for over two months in a production instance, being usable on small to somewhat large instances without having to modify anything. It also removes the patch functions and ENVs abstraction from the entrypoint, this makes it possible to run the container with immutable configuration. In some setups, It may be desired to have the volumes/files under a specific uid/gid (other than searxng:searxng), if the entrypoint has root permissions it will chown automatically on every start, which may not be desired. Explicitly setting the new ENV `FORCE_OWNERSHIP=false` will prevent ownership from being modified. No manual migration is necessary **unless** the user has changed the default uWSGI configuration or has a very specific setup. Closes https://github.com/searxng/searxng/issues/4894 Closes https://github.com/searxng/searxng/issues/4818 Closes https://github.com/searxng/searxng/issues/4802 Supersedes https://github.com/searxng/searxng/pull/4596 Related https://github.com/searxng/searxng/discussions/4479 * [mod] docs: add container/granian All container documentation has been recreated. A new documentation page has been created for Granian. * [enh] misc: apply suggestions Minor documentation changes. Suggested https://github.com/searxng/searxng/pull/4820#discussion_r2134539259 Suggested https://github.com/searxng/searxng/pull/4820#discussion_r2134538610 Suggested https://github.com/searxng/searxng/pull/4820#discussion_r2134827964 Suggested https://github.com/searxng/searxng/pull/4820#discussion_r2134544300 Suggested https://github.com/searxng/searxng/pull/4820#discussion_r2149387388 --------- Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Co-authored-by: Ivan Gabaldon <igabaldon@inetol.net> Co-authored-by: Markus Heiser <markus.heiser@darmarit.de>
191 lines
5.5 KiB
ReStructuredText
191 lines
5.5 KiB
ReStructuredText
.. _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
|