1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
.. _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
|
