From aa3b0265e761eec07055d8f248d677a5cb4e8725 Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Sun, 22 Dec 2019 14:05:33 +0100
Subject: [PATCH] doc: add 'Architecture' article to admin section

Herein we add some hints and suggestions about typical architectures of
searx infrastructures.  We start with a contribution from @dalf

- https://github.com/asciimoo/searx/pull/1776#issuecomment-567917320

thanks @dalf !!

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 docs/admin/arch_public.dot      | 33 +++++++++++++++++++++++++++++++++
 docs/admin/architecture.rst     | 24 ++++++++++++++++++++++++
 docs/admin/index.rst            |  1 +
 docs/dev/contribution_guide.rst |  2 ++
 4 files changed, 60 insertions(+)
 create mode 100644 docs/admin/arch_public.dot
 create mode 100644 docs/admin/architecture.rst

diff --git a/docs/admin/arch_public.dot b/docs/admin/arch_public.dot
new file mode 100644
index 000000000..a46c96de3
--- /dev/null
+++ b/docs/admin/arch_public.dot
@@ -0,0 +1,33 @@
+digraph G {
+
+  node [style=filled, shape=box, fillcolor="#ffffcc", fontname="Sans"];
+  edge [fontname="Sans"];
+
+  browser [label="Browser", shape=Mdiamond];
+  rp      [label="Reverse Proxy", href="url to configure reverse proxy"];
+  filtron [label="Filtron",       href="https://github.com/asciimoo/filtron"];
+  morty   [label="Morty",         href="https://github.com/asciimoo/morty"];
+  static  [label="Static files",  href="url to configure static files"];
+  uwsgi   [label="uwsgi",         href="url to configure uwsgi"]
+  searx1  [label="Searx #1"];
+  searx2  [label="Searx #2"];
+  searx3  [label="Searx #3"];
+  searx4  [label="Searx #4"];
+
+  browser -> rp [label="HTTPS"]
+
+  subgraph cluster_searx {
+      label = "Searx instance" fontname="Sans";
+      bgcolor="#fafafa";
+      { rank=same; static rp };
+      rp -> morty      [label="optional: images and HTML pages proxy"];
+      rp -> static     [label="optional: reverse proxy serves directly static files"];
+      rp -> filtron    [label="HTTP"];
+      filtron -> uwsgi [label="HTTP"];
+      uwsgi -> searx1;
+      uwsgi -> searx2;
+      uwsgi -> searx3;
+      uwsgi -> searx4;
+  }
+
+}
diff --git a/docs/admin/architecture.rst b/docs/admin/architecture.rst
new file mode 100644
index 000000000..7064a294b
--- /dev/null
+++ b/docs/admin/architecture.rst
@@ -0,0 +1,24 @@
+.. _architecture:
+
+============
+Architecture
+============
+
+.. sidebar:: Needs work!
+
+   This article needs some work / Searx is a collaborative effort.  If you have
+   any contribution, feel welcome to send us your :pull:`PR <../pulls>`, see
+   :ref:`how to contribute`.
+
+Herein you will find some hints and suggestions about typical architectures of
+searx infrastructures.
+
+We start with a contribution from :pull:`@dalf <1776#issuecomment-567917320>`.
+It shows a *reference* setup for public searx instances.
+
+.. _arch public:
+
+.. kernel-figure:: arch_public.dot
+   :alt: arch_public.dot
+
+   Reference architecture of a public searx setup.
diff --git a/docs/admin/index.rst b/docs/admin/index.rst
index 6e9a3451f..1b05db42d 100644
--- a/docs/admin/index.rst
+++ b/docs/admin/index.rst
@@ -7,6 +7,7 @@ Administrator documentation
 
    installation
    api
+   architecture
    filtron
    morty
    engines
diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst
index 6d8d3924d..ccc101d2e 100644
--- a/docs/dev/contribution_guide.rst
+++ b/docs/dev/contribution_guide.rst
@@ -1,3 +1,5 @@
+.. _how to contribute:
+
 =================
 How to contribute
 =================