From 6376a8f6351d6b546af53f1568e0d0b3e7a44f81 Mon Sep 17 00:00:00 2001
From: David Douard <david.douard@sdfa3.org>
Date: Fri, 7 Feb 2025 15:32:29 +0100
Subject: [PATCH] mirror: add admonitions to try to make it clearer where to
start from
---
docs/sysadm/mirror-operations/deploy.rst | 5 +++++
docs/sysadm/mirror-operations/index.rst | 26 +++++++++++++++++++++++-
2 files changed, 30 insertions(+), 1 deletion(-)
diff --git a/docs/sysadm/mirror-operations/deploy.rst b/docs/sysadm/mirror-operations/deploy.rst
index 5f69a73d..89a154f2 100644
--- a/docs/sysadm/mirror-operations/deploy.rst
+++ b/docs/sysadm/mirror-operations/deploy.rst
@@ -29,6 +29,11 @@ Each service consists in an HTTP-based RPC served by a `gunicorn
<https://gunicorn.org/>`_ `WSGI
<https://fr.wikipedia.org/wiki/Web_Server_Gateway_Interface>`_ server.
+.. Note:: It is **not** recommended to try to deploy each |swh| service
+ individually. You should rather start from the example docker-based
+ deployment project linked below.
+
+
Docker-based deployment
-----------------------
diff --git a/docs/sysadm/mirror-operations/index.rst b/docs/sysadm/mirror-operations/index.rst
index f34af064..fbe9835a 100644
--- a/docs/sysadm/mirror-operations/index.rst
+++ b/docs/sysadm/mirror-operations/index.rst
@@ -24,6 +24,8 @@ proper mirror should also allow to:
- navigate the archive copy using a Web browser and/or the Web API (typically
using the :ref:`the web application <swh-web>`),
+- have minimal search capabilities (typically using :ref:`the swh-search
+ service <swh-search>` with an Elasticsearch backend),
- retrieve data from the copy of the archive (typically using the :ref:`the
vault service <swh-vault>`)
@@ -41,9 +43,23 @@ blob objects (file content) from the |swh| :ref:`object storage <swh-objstorage>
General view of the |swh| mirroring architecture.
+.. Note:: This general view is very simplified and does not show all the
+ services involved in hosting and operating a mirror.
+
See the :ref:`planning-a-mirror` for a complete description of the requirements
to host a mirror.
+.. Note:: Hosting a complete mirror is a complex task, involving the deployment
+ of dozens of inter related (micro-)services. It should be planned and
+ operated carefully, using state-of-art ops practices (cloud-based, or
+ using container orchestration tools on an elastic execution platform
+ like kubernetes_, `docker swarm`_, or using tools like Ansible_ or
+ `Salt Stack`_).
+
+.. Important:: It is **strongly** recommended to start with a simple `docker
+ swarm`_ based deployment (this can be done on a single machine) as
+ described in :ref:`mirror_deploy`.
+
Mirroring the Graph Storage
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -110,7 +126,11 @@ Installation
When using the |swh| software stack to deploy a mirror, a number of |swh|
software components must be installed (cf. architecture diagram above).
-A `docker-swarm <https://docs.docker.com/engine/swarm/>`_ based deployment
+.. Note:: It is **not** recommended to try to deploy each |swh| service
+ individually. You should rather start from the example docker-based
+ deployment project :ref:`described here <mirror_docker>`.
+
+A `docker swarm`_ based deployment
solution is provided as a working example of the mirror stack,
see :ref:`mirror_deploy`.
@@ -119,6 +139,10 @@ production-like deployment.
.. _Kafka: https://kafka.apache.org/
.. _msgpack: https://msgpack.org
+.. _`docker swarm`: https://docs.docker.com/engine/swarm/
+.. _Ansible: https://docs.ansible.com/ansible/latest/index.html
+.. _kubernetes: https://kubernetes.io/fr/
+.. _`Salt Stack`: https://saltproject.io/
You may want to read:
--
GitLab