mirror of
https://github.com/searxng/searxng.git
synced 2025-07-09 03:04:26 -04:00
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
|