Merge pull request #30 from eXist-db/improve/instdoc

Improve/instdoc
eXist-db · Aug 14, 2020 · 901fdb4 · 901fdb4
2 parents a234b2f + 4e3e6d3
commit 901fdb4
Show file tree

Hide file tree

Showing 7 changed files with 53 additions and 68 deletions.
diff --git a/README.md b/README.md
@@ -95,6 +95,17 @@ used to run each eXist-db instance under a separate user.
 
 The specified Unix user gets created by this role if it does not exist yet.
 
+    exist_instdescription: ''
+    #exist_instdescription: 'testing'
+    #exist_instdescription: 'my experimental setup'
+
+An optional description string for this eXist-db instance. This gets used by
+reporting tools only and is not required for operation. May be used to
+provide additional information about this instance. Can be a multiline string,
+but only the first line gets read by reporting tools. The content of this
+variable gets stored in `$EXIST_HOME/contrib/DESCRIPTION.md` along with other
+information.
+
     exist_http_port: 8080
     exist_ssl_port: 8443
     #exist_http_host: '127.0.0.1'

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -6,7 +6,7 @@
 
 # Current Version
 
-Version 1.0-SNAPSHOT (May 27 2020)
+Version 1.0-SNAPSHOT (Jun 11 2020)
 
 ## New Features
 
@@ -17,6 +17,7 @@ Version 1.0-SNAPSHOT (May 27 2020)
 
 ## Fixes and Improvements
 
+* provide installation documentation
 * cleanup exist_adminpass and exist_userpass_map formats
 * add syslog support
 * add logrotate support for automatic deletion of old log files

diff --git a/defaults/main.yml b/defaults/main.yml
@@ -12,13 +12,21 @@ exist_instname: 'exist'
 #exist_instname: 'exist-test'
 #exist_instname: 'exist-prod'
 
-# if you run multiple eXist-db instances on a single host, you may want to each
-# of them as a different user.
+# if you run multiple eXist-db instances on a single host, you may want to run
+# each of them as a different user.
 # if you're not running multiple instances the default is fine
 exist_instuser: 'existdb'
 #exist_instuser: 'tester'
 #exist_instuser: 'customer1'
 
+# if you run multiple eXist-db instances on a single host, you may want to give
+# each of them a descriptive comment.
+# if you're not running multiple instances the default is fine
+# this variable is only used by reporting tools and not required for operation
+exist_instdescription: ''
+#exist_instdescription: 'testing'
+#exist_instdescription: 'production'
+
 # for reference, but don't force anyone to localhost by default
 #exist_http_host: '127.0.0.1'
 #exist_ssl_host: '127.0.0.1'

diff --git a/files/psexist b/files/psexist
@@ -106,6 +106,7 @@ sub print_inst {
     my $i = shift;
     print 
 	"instance: $i\n",
+	"    description:        ", $DATA->{$i}->{instdesc}, "\n",
 	"    exist version:      ", $DATA->{$i}->{version}, "\n",
 	"    http port:          ", $DATA->{$i}->{http_port}, "\n",
 	"    ssl port:           ", $DATA->{$i}->{ssl_port}, "\n",
@@ -174,6 +175,17 @@ sub parse_ex5 {
     }
     close VERSION;
 
+    # read first line, fail silently if file missing
+    $data->{instdesc} = '';
+    if (open(DESCRIPTION,
+	     "sudo cat " . $data->{instpath} . "/contrib/DESCRIPTION.md |")) {
+	while (<DESCRIPTION>) {
+	    $data->{instdesc} = $_;
+	    last;
+	}
+	close DESCRIPTION;
+    }
+
     $DATA->{$data->{instname}} = $data;
 }
 

diff --git a/tasks/postinstall.yml b/tasks/postinstall.yml
@@ -369,6 +369,16 @@
     - config
     - exist5
 
+- name: Create instance description file
+  template:
+    src: 'DESCRIPTION.instance.j2'
+    dest: '{{ exist_path }}/contrib/DESCRIPTION.md'
+    owner: "{{ exist_instuser }}"
+    group: "{{ exist_group }}"
+  tags:
+    - config
+    - userdoc
+
 - name: Ensure privacy on instance directory tree
   file:
     path: '{{ exist_path }}'
@@ -379,32 +389,3 @@
     mode: 'go-rwx'
   tags:
     - config
-
-#- name: Create symbolic link to instance in user home dir
-#  file:
-#    src: '{{ exist_path}}'
-#    dest: '/home/{{ exist_instuser }}/{{ exist_instname }}'
-#    owner: '{{ exist_instuser }}'
-#    group: '{{ exist_group }}'
-#    state: link
-#    force: yes
-#  when:
-#    - exist_instuser != exist_user
-#    - not exist_instuser in exist_prohibit_usermod
-#  tags:
-#    - config
-#    - userdoc
-
-#- name: Drop WELCOME file for this instance in user home dir
-#  template:
-#    src: WELCOME.instance.j2
-#    dest: '/home/{{ exist_instuser }}/WELCOME.{{ exist_instname }}.md'
-#    owner: "{{ exist_instuser }}"
-#    group: "{{ exist_group }}"
-#    mode: 0644
-#  when:
-#    - exist_instuser != exist_user
-#    - not exist_instuser in exist_prohibit_usermod
-#  tags:
-#    - config
-#    - userdoc
diff --git a/templates/WELCOME.instance.j2 → templates/DESCRIPTION.instance.j2 b/templates/WELCOME.instance.j2 → templates/DESCRIPTION.instance.j2
@@ -1,8 +1,6 @@
-# Welcome!
+{{ exist_instdescription }}
 
-You are running eXist-db in a multi-instance setup on host
-{{ network_hostname }}.  This setup was created using
-the eXist-db Ansible role.
+This setup was created using the eXist-db Ansible role.
 
 * instance name:     {{ exist_instname }}
 * instance user:     {{ exist_instuser }}
@@ -28,38 +26,6 @@ the eXist-db Ansible role.
 {% endif %}
 * Log dir:           {{ exist_logdir }}
 
-{% if exist_instdns is defined %}
-There is an nginx proxy in front of your eXist-db instance that listens on the
-standard HTTP (80/tcp) and HTTPS (443/tcp) ports. It proxies requests to
-{{ exist_instdns }} to the local ports of your instance.
-
-A TLS certificate for {{ exist_instdns }} has been installed in nginx.
-
-{% endif %}
-## Accessing the Instance
-
-You should have received a password for your eXist-db instance. This is
-* the admin password to access eXist-db
-* the SSH user password for shell access
-
-Access the instance with a Browser:
-{% if exist_instdns is defined %}
-* `https://{{ exist_instdns }}/exist`
-{% else %}
-{% if exist_ssl_host is defined %}
-* `https://{{ exist_ssl_host }}:{{ exist_ssl_port }}/exist`
-{% else %}
-* `http://{{ exist_http_host }}:{{ exist_http_port }}/exist`
-{% endif %}
-{% endif %}
-
-Access the instance with SSH:
-* `ssh {{ exist_instuser }}@{{ network_hostname }}`
-
-When logging in with SSH, you will be placed in `/home/{{ exist_instuser }}`.
-There is a symbolic link `{{ exist_instname }}` that points to the installation
-directory of your instance.
-
 ## Starting/Stopping the Instance
 
 Use the commands below to manage your eXist-db instance from the shell.

diff --git a/templates/exist.fact.j2 b/templates/exist.fact.j2
@@ -3,6 +3,7 @@
 ex_path="{{ exist_path }}"
 
 # defaults
+ex_description=
 ex_running=false
 ex_installed=false
 ex_version=
@@ -46,6 +47,10 @@ if [ -f $ex_path/etc/conf.xml ]; then
     fi
 fi
 
+if [ -f $ex_path/contrib/DESCRIPTION.md ]; then
+    ex_description=`head -1 $ex_path/contrib/DESCRIPTION.md 2>/dev/null`
+fi
+
 if pgrep -lfu {{ exist_instuser }} '{{ exist_instname }} org.codehaus' >/dev/null; then
     ex_running=true
 fi
@@ -59,6 +64,7 @@ fi
 cat <<EOF
 {
     "exist_installed": ${ex_installed},
+    "exist_description": "${ex_description}",
     "exist_path": "${ex_path}",
     "exist_running": ${ex_running},
     "exist_version": "${ex_version}",