Merge pull request #146 from IQSS/143-solr-ip

143 solr ip

docker/dataverse-k8s/bin/bootstrap-job.sh

@@ -14,7 +14,10 @@ set -euo pipefail
 DATAVERSE_SERVICE_HOST=${DATAVERSE_SERVICE_HOST:-"dataverse"}
 DATAVERSE_SERVICE_PORT=${DATAVERSE_SERVICE_PORT:-"8080"}
 DATAVERSE_URL=${DATAVERSE_URL:-"http://${DATAVERSE_SERVICE_HOST}:${DATAVERSE_SERVICE_PORT}"}
-SOLR_K8S_HOST=${SOLR_K8S_HOST:-${SOLR_SERVICE_HOST}}
+# The Solr Service IP is always available under its name within the same namespace.
+# If people want to use a different Solr than we normally deploy, they have the
+# option to override.
+SOLR_K8S_HOST=${SOLR_K8S_HOST:-"solr"}
 
 # Check postgres and API key secrets are available
 if [ ! -s "${SECRETS_DIR}/db/password" ]; then

docs/day1/config.rst

@@ -123,6 +123,34 @@ is a bad idea. It's always a good idea to put it in revision control.
 
 You might consider providing a `CronJob` for scheduled, regular updates.
 
+Details of the configuration job
+################################
+
+.. uml::
+
+  @startuml
+  !includeurl "https://raw.githubusercontent.com/michiel/plantuml-kubernetes-sprites/master/resource/k8s-sprites-unlabeled-25pct.iuml"
+
+  actor User
+  participant "<color:#royalblue><$secret></color>\nSecrets" as S
+  participant "<color:#royalblue><$cm></color>\nConfigMap" as CM
+  participant "<color:#royalblue><$pod></color>\nPostgreSQL" as P
+  participant "<color:#royalblue><$pod></color>\nDataverse" as D
+  participant "<color:#royalblue><$job></color>\nConfigure Job" as CJ
+
+  create CJ
+  User -> CJ: Deploy Configure Job
+  S -> CJ: Pass API key
+  CM -> CJ: Pass settings
+  CJ <<-->> D: wait for
+  ...After Dataverse ready......
+  CJ -> D: Configure Dataverse DB-based\nsettings via API
+  activate D
+  D -> P: Store settings
+  return
+  destroy CJ
+  @enduml
+
 Alternative approaches
 ######################
 

docs/day1/index.rst

@@ -7,7 +7,8 @@ Day 1 - Deployment
     :caption: Contents:
     :hidden:
 
-    ./architecture
+    ./init-deploy
+    ./job-bootstrap
     ./config
     ./secrets
     ./resources

docs/day1/init-deploy.rst

@@ -0,0 +1,56 @@
+==================
+Initial Deployment
+==================
+
+Please familiarize yourself with the `architecture of Dataverse <http://guides.dataverse.org/en/latest/installation>`_
+if not already done: it helps a lot knowing how things are connected in Dataverse
+to also understand using it as a Kubernetes application.
+
+The below UML sequence diagram shows all necessary steps by "you" (the user activity on the left)
+or (preferably) your deployment framework (like Kustomize.io, Helm or similar)
+on your behalf for a new deployment of Dataverse. It also explains what happens
+in the background on an overview level.
+
+When you are done with the initial deployment, you have to :doc:`bootstrap </day1/job-bootstrap>`
+and :doc:`configure </day1/config>`.
+
+Maybe you should just read :doc:`/get-started/index` and follow that before going into details.
+
+.. uml::
+
+  @startuml
+  !includeurl "https://raw.githubusercontent.com/michiel/plantuml-kubernetes-sprites/master/resource/k8s-sprites-unlabeled-25pct.iuml"
+
+  actor User
+  participant "<color:#royalblue><$secret></color>\nSecrets" as S
+  participant "<color:#royalblue><$cm></color>\nConfigMap" as CM
+  participant "<color:#royalblue><$pod></color>\nPostgreSQL" as P
+  participant "<color:#royalblue><$pod></color>\nDataverse" as D
+  participant "<color:#royalblue><$pod></color>\nSolr" as Solr
+
+  create S
+  User -> S: Deploy Secrets
+  create CM
+  User -> CM: Deploy ConfigMap
+  note over P: Optional!
+  create P
+  User -> P: Deploy PostgreSQL
+  CM -> P: Pass username +\ndatabase name
+  S -> P: Pass password
+  P -> P: Init database
+
+  create Solr
+  User -> Solr: Deploy Solr from iqss/solr-k8s
+  Solr -> Solr: Init container:\nFix volume permissions\nDeploy schemas
+
+  create D
+  User -> D: Deploy Dataverse from iqss/dataverse-k8s
+  D -> D: Init container:\nFix volume permissions
+  D <<-->> P: wait for
+  D <<-->> Solr: wait for
+  D -> D: Deploy app
+  note right: see also in detail at\n"Container Startup"
+  D -> P: Persistance Framework:\nCreate tables
+  P --> D: Done
+
+  @enduml

docs/day1/job-bootstrap.rst

@@ -0,0 +1,46 @@
+=============
+Bootstrap Job
+=============
+
+After deploying every components of Dataverse on Kubernetes for the first time
+(see :doc:`./init-deploy`), you will need to bootstrap your installation.
+That will create a superadmin user, root dataverse and block important API endpoints.
+
+It will also set the option ``:SolrHostColonPort``, configuring where Dataverse
+can find the Solr Search index. It will default to ``solr:8983``, but can be
+overridden by setting a hostname or IP in ``SOLR_K8S_HOST`` via ``ConfigMap``
+(see :doc:`config`).
+
+.. uml::
+
+  @startuml
+  !includeurl "https://raw.githubusercontent.com/michiel/plantuml-kubernetes-sprites/master/resource/k8s-sprites-unlabeled-25pct.iuml"
+
+  actor User
+  participant "<color:#royalblue><$secret></color>\nSecrets" as S
+  participant "<color:#royalblue><$cm></color>\nConfigMap" as CM
+  participant "<color:#royalblue><$pod></color>\nPostgreSQL" as P
+  participant "<color:#royalblue><$pod></color>\nDataverse" as D
+  participant "<color:#royalblue><$job></color>\nBootstrap Job" as BJ
+  participant "<color:#royalblue><$pod></color>\nSolr" as Solr
+
+  create BJ
+  User -> BJ: Deploy Bootstrapping Job
+  S -> BJ: Pass db password\n+API key
+  CM -> BJ: Pass settings
+  BJ <<-->> P: wait for
+  BJ <<-->> Solr: wait for
+  BJ <<-->> D: wait for
+
+  ... After Dataverse, Solr and PostgreSQL have been reached successfully... ...
+
+  BJ -> P: Additional SQL init
+  BJ -> D: Bootstrapping w/ setup-all.sh\n(Metadata, user, root dataverse, ...)
+  activate D
+  BJ -> D: Configure Solr location\n+ admin contact
+  BJ -> D: Block API with unblock-key
+  D -> P: Store settings
+  return
+  destroy BJ
+
+  @enduml

docs/images/index.rst

@@ -21,3 +21,59 @@ images to be used for Dataverse deployment and maintenance.
     build
     dataverse-k8s
     solr-k8s
+
+Container Startup
+-----------------
+
+Solr Search index
+^^^^^^^^^^^^^^^^^
+
+Described in detail at :doc:`/day2/job-index`.
+
+Dataverse Application Server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the Kubernetes pod containing the application server container starts,
+one of the following happens, dependent on the type of image you are using.
+
+The following happens when using the :doc:`dataverse-k8s` or a derived image.
+
+.. uml::
+
+  @startuml
+  !includeurl "https://raw.githubusercontent.com/michiel/plantuml-kubernetes-sprites/master/resource/k8s-sprites-unlabeled-25pct.iuml"
+
+  participant "<color:#royalblue><$pod></color>\nContainer" as K
+  participant Tini
+  note right Tini: "Tiny init"\ngithub.com/krallin/tini
+  participant "Entrypoint" as E
+  participant "Init script" as I
+  participant "Appserver" as A
+
+  create Tini
+  K -> Tini: Start
+
+  create E
+  Tini -> E: Start
+  create I
+  E -> I: Start
+
+  create A
+  I -> A: Start
+  activate A
+  I -> A: Configure password aliases
+  I -> A: Configure keys for S3
+  I -> A: Configure resources
+  I -> A: Configure Dataverse\nJVM options
+  I -> A: Stop
+  destroy A
+  I -> I: Symlink WAR & more
+
+  create A
+  E -> A: Start in foreground
+  activate A
+  E --> Tini: exec(): replace with Appserver
+  destroy E
+  Tini -> A: Keep running until container stops
+  A -> A: Autodeploy WAR
+  @enduml