mirror of
https://github.com/searxng/searxng.git
synced 2025-08-10 13:56:45 +02:00
3de7a6da2d
Building the container currently does not work properly. When rebuilding several times with `make container`, `version_frozen.py` is recreated, which wouldn't be an issue if the file’s timestamp was constant. Now, when creating `version_frozen.py`, it will have the same timestamp as the commit when it was created. (`version_frozen.py` is moved to a dedicated layer). Reusing "builder" cache when building "dist" could be slow (CD reports 2 seconds, but locally I've seen it take up to 10 seconds), so the Dockerfile is now split and we save a couple steps by importing the "builder" image directly. The last changes made it possible to remove the layer cache in "builder", since the overhead is now greater than building the layers from scratch. Until now, all "dist" layers were squashed into a single layer, which in most cases is a good idea (except for storage/delivery pricing/overhead), but in our case, since we manage the entire pipeline, we can ignore this and share layers between builds. This means (for example) that if we change files unrelated to the container in several consecutive commits (documentation changes), we don't have to push the entire image to registry, but only the different layers (`version_frozen.py` in this example). The same applies when pulling, as only the layers that have changed compared to the local layers will be downloaded (that's the theory, we'll see if this works as expected or if we need to tweak something else).
190 lines
5.4 KiB
ReStructuredText
190 lines
5.4 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.8.1-3d96414
|
|
|
|
.. _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
|
|
1af574997e63 ... ... 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
|
|
1af574997e63:/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 2025.8.1-3d96414 ... About a minute ago 183 MB
|
|
localhost/searxng/searxng latest ... About a minute ago 183 MB
|
|
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
|