[mod] container: rework compose (#5906)
* [mod] container: rework compose See https://docs.searxng.org/admin/installation-docker.html#migrate-from-searxng-docker * [mod] container: apply suggestions https://github.com/searxng/searxng/pull/5906#discussion_r3004917087 https://github.com/searxng/searxng/pull/5906#discussion_r3004917090 https://github.com/searxng/searxng/pull/5906#discussion_r3004917084
This commit is contained in:
Ivan Gabaldon
@@ -9,7 +9,6 @@ Installation container
|
||||
.. _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
|
||||
|
||||
@@ -27,7 +26,7 @@ Installation container
|
||||
`Docker 101`_ before proceeding.
|
||||
|
||||
Container images are the basis for deployments in containerized environments,
|
||||
`Docker compose`_, Kubernetes and more.
|
||||
Compose, Kubernetes and more.
|
||||
|
||||
.. _Container installation:
|
||||
|
||||
@@ -55,10 +54,10 @@ In the case of Docker, you need to add the user running the container to the
|
||||
In the case of Podman, no additional steps are generally required, but there
|
||||
are some considerations when running `Podman rootless containers`_.
|
||||
|
||||
.. _Container pulling images:
|
||||
.. _Container registries:
|
||||
|
||||
Pulling images
|
||||
--------------
|
||||
Registries
|
||||
----------
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -70,26 +69,108 @@ The official images are mirrored at:
|
||||
- `DockerHub mirror`_
|
||||
- `GHCR mirror`_ (GitHub Container Registry)
|
||||
|
||||
Pull the latest image:
|
||||
.. _Container compose instancing:
|
||||
|
||||
Compose instancing
|
||||
==================
|
||||
|
||||
This is the recommended way to deploy SearXNG in a containerized environment.
|
||||
Compose templates allow you to define container configurations in a
|
||||
declarative manner.
|
||||
|
||||
.. _Container compose instancing setup:
|
||||
|
||||
Setup
|
||||
-----
|
||||
|
||||
1. Create the environment:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker pull docker.io/searxng/searxng:latest
|
||||
# Create the environment and configuration directories
|
||||
$ mkdir -p ./searxng/core-config/
|
||||
$ cd ./searxng/
|
||||
|
||||
\.\. or if you want to lock in to a specific version:
|
||||
# Fetch the latest compose template
|
||||
$ curl -fsSLO \
|
||||
https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
|
||||
https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
|
||||
|
||||
2. Rename the ``.env.example`` file to ``.env`` and edit the values as needed.
|
||||
|
||||
3. Start & stop the services:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker pull docker.io/searxng/searxng:2025.8.1-3d96414
|
||||
$ docker compose up -d
|
||||
$ docker compose down
|
||||
|
||||
.. _Container instancing:
|
||||
4. Setup your settings in ``core-config/settings.yml`` according to your preferences.
|
||||
|
||||
Instancing
|
||||
==========
|
||||
.. _Container compose instancing maintenance:
|
||||
|
||||
Management
|
||||
----------
|
||||
|
||||
.. important::
|
||||
|
||||
Remember to review the new templates for any changes that may affect your
|
||||
deployment, and update the ``.env`` file accordingly.
|
||||
|
||||
To update the templates to their latest versions:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker compose down
|
||||
$ curl -fsSLO \
|
||||
https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
|
||||
https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
|
||||
$ docker compose up -d
|
||||
|
||||
To update the services to their latest versions:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker compose down
|
||||
$ docker compose pull
|
||||
$ docker compose up -d
|
||||
|
||||
List running services:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker compose ps
|
||||
NAME IMAGE ... CREATED STATUS PORTS
|
||||
searxng-core ... ... 3 minutes ago Up 3 minutes 0.0.0.0:8080->8080/tcp
|
||||
searxng-valkey ... ... 3 minutes ago Up 3 minutes 6379/tcp
|
||||
|
||||
Print a service container logs:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker compose logs -f core
|
||||
|
||||
Access a service container shell (troubleshooting):
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker compose exec -it --user root core /bin/sh -l
|
||||
/usr/local/searxng #
|
||||
|
||||
Stop and remove the services:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker compose down
|
||||
|
||||
.. _Container manual instancing:
|
||||
|
||||
Manual 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.
|
||||
recommend using `Container compose instancing`_, which provides a preconfigured
|
||||
environment with sensible defaults.
|
||||
|
||||
Basic container instancing example:
|
||||
|
||||
@@ -121,12 +202,18 @@ List running containers:
|
||||
CONTAINER ID IMAGE ... CREATED PORTS NAMES
|
||||
1af574997e63 ... ... 3 minutes ago 0.0.0.0:8888->8080/tcp searxng
|
||||
|
||||
Print the container logs:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker container logs -f searxng
|
||||
|
||||
Access the container shell (troubleshooting):
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ docker container exec -it --user root searxng /bin/sh -l
|
||||
1af574997e63:/usr/local/searxng#
|
||||
/usr/local/searxng #
|
||||
|
||||
Stop and remove the container:
|
||||
|
||||
@@ -153,18 +240,12 @@ 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`.
|
||||
environment ``$SEARXNG_*`` in :ref:`settings server`, :ref:`settings
|
||||
general` and the :origin:`container/.env.example` template.
|
||||
- ``$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
|
||||
@@ -176,6 +257,8 @@ additional certificates as needed.
|
||||
They will be available on container (re)start or when running
|
||||
``update-ca-certificates`` in the container shell.
|
||||
|
||||
This requires the container to be running with ``root`` privileges.
|
||||
|
||||
.. _Container custom images:
|
||||
|
||||
Custom images
|
||||
@@ -199,3 +282,57 @@ container images are not officially supported):
|
||||
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
|
||||
|
||||
Migrate from ``searxng-docker``
|
||||
===============================
|
||||
|
||||
We expect the following source directory structure:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
.
|
||||
└── searxng-docker
|
||||
├── searxng
|
||||
│ ├── favicons.toml
|
||||
│ ├── limiter.toml
|
||||
│ ├── settings.yml
|
||||
│ └── ...
|
||||
├── .env
|
||||
├── Caddyfile
|
||||
├── docker-compose.yml
|
||||
└── ...
|
||||
|
||||
Create a brand new environment outside ``searxng-docker`` directory, following
|
||||
`Container compose instancing setup`_.
|
||||
|
||||
Once up and running, stop the services and move the configuration files from
|
||||
the old mount to the new one:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ mv ./searxng-docker/searxng/* ./searxng/core-config/
|
||||
|
||||
If you have any custom environment variables in the old ``.env`` file, make
|
||||
sure to add them manually to the new one.
|
||||
|
||||
Consider setting up a reverse proxy if exposing the instance to the public.
|
||||
|
||||
You should end with the following directory structure:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
.
|
||||
├── searxng
|
||||
│ ├── core-config
|
||||
│ │ ├── favicons.toml
|
||||
│ │ ├── limiter.toml
|
||||
│ │ ├── settings.yml
|
||||
│ │ └── ...
|
||||
│ ├── .env.example
|
||||
│ ├── .env
|
||||
│ └── docker-compose.yml
|
||||
└── searxng-docker
|
||||
└── ...
|
||||
|
||||
If everything is working on the new environment, you can remove the old
|
||||
``searxng-docker`` directory and its contents.
|
||||
|
||||
Reference in New Issue
Block a user