From 12b55320eaac6551e885852966afd6413715ee4c Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 29 Apr 2021 14:33:35 +0200 Subject: [PATCH] [doc] docker: revision and preparation of the documentation - add sidebars with addition infos about commands and docker in general - fix long lines & indentation - correct link to https://github.com/searxng/searxng-docker Signed-off-by: Markus Heiser --- docs/admin/installation-docker.rst | 165 ++++++++++++++++++++++++----- 1 file changed, 138 insertions(+), 27 deletions(-) diff --git a/docs/admin/installation-docker.rst b/docs/admin/installation-docker.rst index 7e40546c6..750d41679 100644 --- a/docs/admin/installation-docker.rst +++ b/docs/admin/installation-docker.rst @@ -1,60 +1,171 @@ + .. _installation docker: =================== Docker installation =================== -.. contents:: Contents - :depth: 2 - :local: - :backlinks: entry +.. _ENTRYPOINT: https://docs.docker.com/engine/reference/builder/#entrypoint +.. _searxng-docker: https://github.com/searxng/searxng-docker +.. _[filtron]: https://hub.docker.com/r/dalf/filtron +.. _[morty]: https://hub.docker.com/r/dalf/morty +.. _[caddy]: https://hub.docker.com/_/caddy + +.. sidebar:: info ----- + - :origin:`Dockerfile` + - `searxng/searxng @dockerhub `_ + - `Docker overview `_ + - `Docker Cheat Sheet `_ + - `Alpine Linux `_ `(wiki) `__ `apt packages `_ + - Alpine's ``/bin/sh`` is :man:`dash` -Docker image searxng/searxng -============================ +.. tip:: + If you intend to create a public instance using Docker, use our well + maintained searxng-docker_ image which includes -The docker image is `searxng/searxng `_ (based on `github.com/searxng/searxng `_). + - :ref:`protection ` `[filtron]`_, + - a :ref:`result proxy ` `[morty]`_ and + - a HTTPS reverse proxy `[caddy]`_. -Make sure you have `installed Docker `_. For instance, you can deploy a local instance: +Make sure you have `installed Docker `_ and +on Linux, don't forget to add your user to the docker group (log out and log +back in so that your group membership is re-evaluated): .. code:: sh - export PORT=80 - docker pull searxng/searxng - docker run --rm -d -v ${PWD}/searx:/etc/searx -p $PORT:8080 -e BASE_URL=http://localhost:$PORT/ searxng/searxng + $ sudo usermod -a -G docker $USER -Go to ``http://localhost:$PORT``. -Inside ``${PWD}/searx``, you will find ``settings.yml`` and ``uwsgi.ini``. -You can modify these files according to your needs and restart the Docker image. +searxng/searxng +=============== +.. sidebar:: ``docker run`` -Command line ------------- + - `-\-rm `__ + automatically clean up when container exits + - `-d `__ start + detached container + - `-v `__ + mount volume ``HOST:CONTAINER`` +The docker image is based on :origin:`Dockerfile` and available from +`searxng/searxng @dockerhub`_. Using the docker image is quite easy, for +instance you can pull the `searxng/searxng @dockerhub`_ image and deploy a local +instance using `docker run `_: .. code:: sh - docker run --rm -it searxng/searxng -h + $ mkdir my-instance + $ cd my-instance + $ export PORT=8080 + $ docker pull searxng/searxng + $ docker run --rm \ + -d -p ${PORT}:8080 \ + -v "${PWD}/searx:/etc/searx" \ + -e "BASE_URL=http://localhost:$PORT/" \ + -e "INSTANCE_NAME=my-instance" \ + searxng/searxng + 2f998.... # container's ID -.. program-output:: ../dockerfiles/docker-entrypoint.sh -h +Open your WEB browser and visit the URL: +.. code:: sh -Build the image ---------------- + $ xdg-open "http://localhost:$PORT" + +Inside ``${PWD}/searx``, you will find ``settings.yml`` and ``uwsgi.ini``. You +can modify these files according to your needs and restart the Docker image. + +.. code:: sh -It's also possible to build SearXNG from the embedded Dockerfile. + $ docker container restart 2f998 + +Use command ``container ls`` to list running containers, add flag `-a +`__ to list +exited containers also. With ``container stop`` a running container can be +stoped. To get rid of a container use ``container rm``: .. code:: sh - git clone https://github.com/searxng/searxng.git - cd searx - make docker.build + $ docker container ls + CONTAINER ID IMAGE COMMAND CREATED ... + 2f998d725993 searxng/searxng "/sbin/tini -- /usr/…" 7 minutes ago ... + + $ docker container stop 2f998 + $ docker container rm 2f998 + +.. sidebar:: Warning + + This might remove all docker items, not only those from searxng. + +If you won't use docker anymore and want to get rid of all conatiners & images +use the following *prune* command: + +.. code:: sh + + $ docker stop $(docker ps -aq) # stop all containers + $ docker system prune # make some housekeeping + $ docker rmi -f $(docker images -q) # drop all images + + +shell inside container +---------------------- + +.. sidebar:: Bashism + - `A tale of two shells: bash or dash `_ + - `How to make bash scripts work in dash `_ + - `Checking for Bashisms `_ -Public instance +Like in many other distributions, Alpine's `/bin/sh +`__ is :man:`dash`. Dash is meant to be +`POSIX-compliant `__. +Compared to debian, in the Alpine image :man:`bash` is not installed. The +:origin:`dockerfiles/docker-entrypoint.sh` script is checked *against dash* +(``make tests.shell``). + +To open a shell inside the container: + +.. code:: sh + + $ docker exec -it 2f998 sh + + +Build the image =============== -If you intend to create a public instance using Docker, see https://github.com/searx/searx-docker +It's also possible to build SearXNG from the embedded :origin:`Dockerfile`:: + + $ git clone https://github.com/searxng/searxng.git + $ cd searx + $ make docker.build + ... + Successfully built 49586c016434 + Successfully tagged searxng/searxng:latest + Successfully tagged searxng/searxng:1.0.0-209-9c823800-dirty + + $ docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + searxng/searxng 1.0.0-209-9c823800-dirty 49586c016434 13 minutes ago 308MB + searxng/searxng latest 49586c016434 13 minutes ago 308MB + alpine 3.13 6dbb9cc54074 3 weeks ago 5.61MB + + +Command line +============ + +.. sidebar:: docker run + + Use flags ``-it`` for `interactive processes + `__. + +In the :origin:`Dockerfile` the ENTRYPOINT_ is defined as +:origin:`dockerfiles/docker-entrypoint.sh` + +.. code:: sh + + docker run --rm -it searxng/searxng -h + +.. program-output:: ../dockerfiles/docker-entrypoint.sh -h