mirror of
https://github.com/searxng/searxng.git
synced 2025-10-31 18:47:07 -04:00
3bf702447b
Let container instance administrators to add custom certificates: https://docs.searxng.org/admin/installation-docker.html#custom-certificates Closes https://github.com/searxng/searxng/issues/5206
202 lines
5.7 KiB
ReStructuredText
202 lines
5.7 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 certificates:
|
|
|
|
Custom certificates
|
|
===================
|
|
|
|
You can mount ``/usr/local/share/ca-certificates/`` folder to add/remove
|
|
additional certificates as needed.
|
|
|
|
They will be available on container (re)start or when running
|
|
``update-ca-certificates`` in the container shell.
|
|
|
|
.. _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
|