diff --git a/tasks/compile_callas_binaries.yml b/tasks/compile_callas_binaries.yml index 19741fa825a7d0011d42d4ec7d9db36130faf79c..e2d9c8d4f17d3294f560a4d2e0b75ee2e5d4cc17 100644 --- a/tasks/compile_callas_binaries.yml +++ b/tasks/compile_callas_binaries.yml @@ -8,7 +8,7 @@ # version is used, the CGI-Binaries for validation and repair fail. Make sure # to keep the package on the Debian repo server up to date with the latest # Debian releases. -- name: install prerequisite packages for compilation +- name: Install prerequisite packages for compilation. ansible.builtin.apt: name: [ 'g++', @@ -18,19 +18,22 @@ ] state: present -- name: setup deploy key +- name: > + Setup SSH deploy key that is needed to authenticate against SLUB's local + GitLab instance when cloning the PDF/A-Webservice Git repo. ansible.builtin.copy: src: "{{ role_path }}/../ansible_vaults/{{ role_name }}/id_ed25519_deploykey" dest: "/tmp/id_ed25519_deploykey" mode: "0600" -- name: clear Git repo directory for fresh checkout +- name: Clear Git repo directory for fresh checkout. ansible.builtin.file: path: "/opt/pdfa_webservice/" state: absent - changed_when: false # This cannot be idempotent, because later tasks change the repo content. + changed_when: false # This cannot be idempotent, because later tasks + # change the repo content. -- name: checkout PDF/A-Webservice Git repo +- name: Clone PDF/A-Webservice Git repo. ansible.builtin.git: repo: "git@git.slub-dresden.de:slub-digitalpreservation/pdfa_webservice.git" dest: "/opt/pdfa_webservice/" @@ -39,9 +42,12 @@ key_file: "/tmp/id_ed25519_deploykey" ssh_opts: "-o StrictHostKeyChecking=accept-new" update: true - changed_when: false # This cannot be idempotent, because later tasks change the repo content. + changed_when: false # This cannot be idempotent, because later tasks + # change the repo content. -- name: set symlinks for Callas PDF Engine +- name: > + Set symlinks for Callas PDF Engine, so files can be found at their + respective standard paths. ansible.builtin.file: state: link src: "/usr/local/lib/callas_pdfEngine_SDK_x64/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}/{{ item }}" @@ -54,7 +60,9 @@ - "var" changed_when: false # This always changes, because the dest path is fresh. -- name: remove libstdc++ that is delivered with CallasSDK to ensure that local system lib is used +- name: > + Remove libstdc++ that is shipped with CallasSDK to ensure that the local + system library is used. ansible.builtin.file: name: "/usr/lib/cgi-bin/lib/libstdc++.so.6" state: absent @@ -63,7 +71,7 @@ # We need to use the ansible.builtin.shell module here, because the # ansible.builtin.command module does not accept setting environment variables # inline. Molecule errors are turned off for this. -- name: compile PDF/A-Webservice binary # noqa command-instead-of-shell +- name: Compile PDF/A-Webservice binaries. # noqa command-instead-of-shell ansible.builtin.shell: cmd: 'make --directory /opt/pdfa_webservice/src/' changed_when: false # This always changes, because the dest path is fresh. diff --git a/tasks/configure_apache.yml b/tasks/configure_apache.yml index d66b4a9663a14355c8c495b42a5016b30b6f6ad4..79e4f2d727295f9a7855c0cac2fccd879a1452d7 100644 --- a/tasks/configure_apache.yml +++ b/tasks/configure_apache.yml @@ -1,17 +1,20 @@ --- -### APACHE KONFIGURIEREN ### # symlink /etc/apache2/mods-available/cgi.load to /etc/apache2/mods-enabled/ -- name: CGI-Extension-Modul aktivieren +- name: > + Activate CGI-Extension-Module and SSL-Extension-Module in order to be able + to run the Services as cgi-bin scripts secured by TLS. community.general.apache2_module: name: "{{ item }}" loop: - "cgid" - "ssl" notify: restart apache -- name: Restart apache immediately to make sure mod_ssl is running before configuring TLS. +- name: > + Restart apache immediately to make sure mod_ssl is running before + configuring TLS. ansible.builtin.meta: flush_handlers -- name: Apache-Konfigurationsdateien einspielen (copied) +- name: Deploy Apache config files (copied). ansible.builtin.copy: src: "{{ item.src }}" dest: "{{ item.dest }}" @@ -24,7 +27,7 @@ notify: - restart apache -- name: Apache-Konfigurationsdateien einspielen (templated) +- name: Deploy Apache config files (templated). ansible.builtin.template: src: "{{ item.src }}.j2" dest: "{{ item.dest }}" @@ -35,13 +38,13 @@ notify: - restart apache -- name: check if config needs to be enabled +- name: Check if config needs to be enabled. ansible.builtin.command: "/usr/sbin/a2query -c serve-cgi-bin" register: a2query changed_when: false # symlink /etc/apache2/conf-available/serve-cgi-bin.conf to /etc/apache2/conf-enabled/ -- name: CGI-Extension-Config aktivieren +- name: Activate CGI-Extension-Config. ansible.builtin.command: "/usr/sbin/a2enconf serve-cgi-bin" # noqa no-changed-when when: not "(enabled by site administrator)" in a2query.stdout register: a2enconf @@ -49,14 +52,13 @@ notify: - restart apache -### STARTSEITE INSTALLIEREN ### -- name: alte Startseite löschen +- name: Delete default/old index page. It will be replaced by a custom file. ansible.builtin.file: path: "/var/www/html/index.html" state: absent changed_when: false -- name: Startseite neu installieren +- name: Install new landing page that links to the services offered here. ansible.builtin.blockinfile: dest: "/var/www/html/index.html" backup: false @@ -87,7 +89,9 @@ insertafter: EOF changed_when: false -- name: set HTTP timeout +- name: > + Set custom HTTP timeout. We want to keep connections open longer than the + default 60 seconds, because file uploads might take longer. ansible.builtin.lineinfile: path: "/etc/apache2/apache2.conf" regexp: "^Timeout [0-9]+$" @@ -96,7 +100,7 @@ notify: - restart apache -- name: copy server certificates +- name: Install TLS server certificates for providing TLS connections. ansible.builtin.copy: src: "{{ role_path }}/../ansible_vaults/{{ role_name }}/{{ ansible_hostname }}/{{ item }}" dest: "/etc/ssl/certs/{{ item }}" diff --git a/tasks/configure_crontab.yml b/tasks/configure_crontab.yml index 2cbbed84db08deaf15bf03a7ea46bc5ac37ad229..e85fded7e65df8e9fa37b923033d42fa0db2219a 100644 --- a/tasks/configure_crontab.yml +++ b/tasks/configure_crontab.yml @@ -3,7 +3,7 @@ - name: DEBUG ansible.builtin.debug: var: users -- name: Cronjob zum Löschen alter tmpfiles aus /tmp erstellen +- name: Create Cronjob for deleting old tmpfiles from /tmp/. ansible.builtin.cron: name: "delete old tmpfiles from /tmp" hour: "0" diff --git a/tasks/configure_iptables.yml b/tasks/configure_iptables.yml index 32d13f9ad0f0f1c9a8f5a5882e50c97bf985b506..30cdffe4ffd09edc1b046e9165302267faab4450 100644 --- a/tasks/configure_iptables.yml +++ b/tasks/configure_iptables.yml @@ -1,5 +1,5 @@ --- -- name: iptables-Regeln setzen +- name: Configure iptables rules. ansible.builtin.iptables: action: "insert" chain: "INPUT" diff --git a/tasks/configure_local_mounts.yml b/tasks/configure_local_mounts.yml index 0ea27b9eab1687be4b423e30ba313fe254939d5a..4330579cf31fe75e8f459c10df6694c70aae14ad 100644 --- a/tasks/configure_local_mounts.yml +++ b/tasks/configure_local_mounts.yml @@ -1,5 +1,5 @@ --- -- name: Mount tmpfs for non-persistent and fast /tmp directory +- name: Mount tmpfs for non-persistent and fast /tmp/ directory. ansible.posix.mount: boot: true fstype: "tmpfs" diff --git a/tasks/configure_nfs_mounts.yml b/tasks/configure_nfs_mounts.yml index a3c217fb03d34bfdf6db6b16d84addedb3858538..c848b402d099fc2c5faa4aac0df3ec627fef7246 100644 --- a/tasks/configure_nfs_mounts.yml +++ b/tasks/configure_nfs_mounts.yml @@ -1,11 +1,14 @@ --- -- name: Mountpoint fuer Logging anlegen +- name: > + Explicitely create mountpoint for logging. We do this to be able to set + restrictive permissions, so a failed log share can be easily detected due + to the write errors that will occur if the NFS share fails. ansible.builtin.file: path: "{{ nfs_mounts.log.mountpoint }}{{ ansible_hostname }}" state: directory mode: "0400" -- name: NFS-Shares fuer Logging mounten +- name: Mount NFS-Share for logging. ansible.posix.mount: name: "{{ nfs_mounts.log.mountpoint }}{{ ansible_hostname }}" src: "{{ nfs_mounts.log.share }}/{{ ansible_hostname }}" diff --git a/tasks/create_users_groups.yml b/tasks/create_users_groups.yml index 9162d9fc13c2f312534c706ca21c825917110ebc..2d5589e0c766a082163209bcc89acca5b62421b1 100644 --- a/tasks/create_users_groups.yml +++ b/tasks/create_users_groups.yml @@ -1,12 +1,12 @@ --- -- name: Gruppen erstellen +- name: Create groups. ansible.builtin.group: name: "{{ item.name }}" gid: "{{ item.gid | default(omit) }}" state: "{{ item.state | default('present') }}" loop: "{{ grouplist | flatten(levels=1) }}" -- name: User in Gruppen einfügen und primäre Gruppe setzen +- name: Add users to groups and set their respective primary group. ansible.builtin.user: name: "{{ item.name }}" group: "{{ item.group }}" diff --git a/tasks/install_callas_pdf_engine.yml b/tasks/install_callas_pdf_engine.yml index c51c211be696a5d381f4343d11a8719b7b46619a..b35322bf38c0d15cfbdc843d724b0033957ac1bf 100644 --- a/tasks/install_callas_pdf_engine.yml +++ b/tasks/install_callas_pdf_engine.yml @@ -1,5 +1,24 @@ --- -- name: remove old version of callas PDFEngine +# get latest version of callas PDFEngine at +# http://www.callassoftware.com/extranet/callas_pdfEngineSDK/callas_pdfEngineSDK_x64_Linux.tar.gz +# downloading with unarchive will be deprecated, so we use a separate copy task +# !!! CAUTION: DO NOT AUTOMATICALLY INSTALL NEW SDK VERSIONS WITHOUT RECOMPILING +# CGI-BIN FILES!!! +- name: Download Callas PDFEngine. + ansible.builtin.get_url: + url: "http://www.callassoftware.com/extranet/callas_pdfEngineSDK/callas_pdfEngineSDK_x64_Linux.tar.gz" + dest: "/usr/local/lib/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}.tar.gz" + mode: "0644" + changed_when: false # This will always change, because we're installing a + # fresh version of Callas into a cleaned directory + # (see tasks below, where we delete the .tar.gz). + +- name: > + Remove old version of callas PDFEngine. Callas only provide a universal URL + that will redirect to the latest version of the library, so we cannot + select a specific Callas version and always have to install the latest + version. To do this, we first have to make sure that there are no remains + of older versions on the system. ansible.builtin.file: path: "/usr/local/lib/callas_pdfEngine_SDK_x64" state: absent @@ -7,7 +26,7 @@ # idempotent, because we install a new version in # later tasks. -- name: create directories for CGI-BIN and callas PDFEngine +- name: Create directories for CGI-BIN and Callas PDFEngine. ansible.builtin.file: path: "{{ item }}" state: directory @@ -18,23 +37,9 @@ changed_when: false # This will always change, because we just removed the # dir in the previous task to clean up. -# get latest version of callas PDFEngine at -# http://www.callassoftware.com/extranet/callas_pdfEngineSDK/callas_pdfEngineSDK_x64_Linux.tar.gz -# downloading with unarchive will be deprecated, so we use a separate copy task -# !!! CAUTION: DO NOT AUTOMATICALLY INSTALL NEW SDK VERSIONS WITHOUT RECOMPILING -# CGI-BIN FILES!!! -- name: copy callas PDFEngine - ansible.builtin.get_url: - url: "http://www.callassoftware.com/extranet/callas_pdfEngineSDK/callas_pdfEngineSDK_x64_Linux.tar.gz" - dest: "/usr/local/lib/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}.tar.gz" - mode: "0644" - changed_when: false # This will always change, because we're installing a - # fresh version of Callas into a cleaned directory - # (see tasks below, where we delete the .tar.gz). - # !!! CAUTION: DO NOT EXTRACT TO /tmp/ # (https://github.com/ansible/ansible/issues/28569) -- name: unpack callas PDFEngine +- name: Unpack callas PDFEngine... ansible.builtin.unarchive: src: "/usr/local/lib/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}.tar.gz" dest: "/usr/local/lib/callas_pdfEngine_SDK_x64" @@ -48,7 +53,7 @@ changed_when: false # This will always change. We just downloaded a fresh # archive that now needs to be cleaned up. -- name: set permissions for PDFEngine +- name: Set permissions for PDFEngine. ansible.builtin.file: path: "/usr/local/lib/callas_pdfEngine_SDK_x64" group: "www-data" @@ -56,7 +61,10 @@ state: directory changed_when: false # This will always change. -- name: symlink callas PDFEngine from '/usr/local/lib/callas_pdfEngine_SDK_x64/*' to '/usr/lib/cgi-bin/*' +- name: > + Symlink callas PDFEngine from '/usr/local/lib/callas_pdfEngine_SDK_x64/*' + to '/usr/lib/cgi-bin/*', so Callas libraries can be found below standard + paths. ansible.builtin.file: src: "/usr/local/lib/callas_pdfEngine_SDK_x64/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}/{{ item }}" dest: "/usr/lib/cgi-bin/{{ item }}" @@ -65,12 +73,14 @@ - "lib" - "lang" -- name: install libstdc++ +- name: Install libstdc++. ansible.builtin.apt: name: "libstdc++-11-dev" state: present -- name: remove symlinks to distro version of libstdc++, because we need to use what's provided with PDFEngine +- name: > + Remove symlinks to distro version of libstdc++, because we need to use + what's provided with PDFEngine. ansible.builtin.file: path: "{{ item }}" state: absent diff --git a/tasks/install_converters.yml b/tasks/install_converters.yml index 66c7a1a4280747d730e9c7e61cc775230267f5cf..d675ab96e2d24937e77cada765b6c46ec628daad 100644 --- a/tasks/install_converters.yml +++ b/tasks/install_converters.yml @@ -1,5 +1,7 @@ --- -- name: "'convert_pdfa.bin' nach '/usr/lib/cgi-bin/convert_to_pdfa' kopieren & umbenennen, Rechte setzen" +- name: > + "Copy 'convert_pdfa.bin' to '/usr/lib/cgi-bin/convert_to_pdfa', rename it + to match URLs and set permissions." ansible.builtin.copy: src: "/opt/pdfa_webservice/src/unix/convert_to_pdfa.bin" dest: "/usr/lib/cgi-bin/convert_to" diff --git a/tasks/install_fonts.yml b/tasks/install_fonts.yml index 3293c79f062b4f5bdadd6aad73c0eac5b34b6347..6ada7c126c680d8659de3ce437348c50861761e0 100644 --- a/tasks/install_fonts.yml +++ b/tasks/install_fonts.yml @@ -1,6 +1,5 @@ --- -# install applefonts -- name: install applefonts package +- name: Install applefonts package. ansible.builtin.package: name: "applefonts" state: latest diff --git a/tasks/install_packages.yml b/tasks/install_packages.yml index 357e5368e5d9b08637406ec800fb4198e3adadf6..f4a4b017e47fa16a80d680c6ea7e2dbd66d10a54 100644 --- a/tasks/install_packages.yml +++ b/tasks/install_packages.yml @@ -1,5 +1,5 @@ --- -- name: Install/Update Debian packages +- name: Install/Update Debian packages. ansible.builtin.apt: update_cache: true state: present @@ -39,7 +39,7 @@ 'unzip' ] -- name: remove unnecessary packages +- name: Remove unnecessary packages. ansible.builtin.apt: state: absent name: [ diff --git a/tasks/install_validators.yml b/tasks/install_validators.yml index 821c010f6484441872e8517d93fa8c73c204feb2..6bd2ba8d597185fbf0c3a28d6380036d189df863 100644 --- a/tasks/install_validators.yml +++ b/tasks/install_validators.yml @@ -1,6 +1,7 @@ --- -### INSTALLATION VALIDATOREN ### -- name: "'validate_pdfa.bin' nach '/usr/lib/cgi-bin/is_valid' kopieren & umbenennen, Rechte setzen" +- name: > + "Copy 'validate_pdfa.bin' to '/usr/lib/cgi-bin/is_valid', rename it to + match URLs and set permissions." ansible.builtin.copy: src: "/opt/pdfa_webservice/src/unix/validate_pdfa.bin" dest: "/usr/lib/cgi-bin/is_valid" diff --git a/tasks/main.yml b/tasks/main.yml index 3f76f4543cab6c634cb69381f87a22b5e0e8672c..8d86977e23dcb2db8e26c7e577d8f108dda515fd 100644 --- a/tasks/main.yml +++ b/tasks/main.yml @@ -5,50 +5,60 @@ - "validator.vault" tags: [always] -- name: install packages +- name: > + Install packages that are necessary for running and testing the validation/ + conversion services. ansible.builtin.import_tasks: "install_packages.yml" tags: [apt, package, packages] -- name: create users and groups +- name: Create users and groups. ansible.builtin.import_tasks: "create_users_groups.yml" tags: [user, users, group, groups] -- name: configure local mounts +- name: > + Configure local mounts. To increase performance, we use a RAMdisk to store + temporary files. ansible.builtin.import_tasks: "configure_local_mounts.yml" tags: [mount] -- name: configure nfs mounts +- name: Configure NFS mounts. Logs are currently written to an NFS share. ansible.builtin.import_tasks: "configure_nfs_mounts.yml" tags: [nfs] -- name: configure Apache webserver +- name: > + Configure Apache webserver. Converters and validators run as Apache cgi-bin + scripts and should be reachable via HTTPS only. ansible.builtin.import_tasks: "configure_apache.yml" tags: [apache] -- name: install Callas PDF Engine SDK +- name: > + Install Callas PDF Engine SDK. This is a prerequisite to run any + PDF-related services. ansible.builtin.import_tasks: "install_callas_pdf_engine.yml" tags: [callas, callaspdf, callassdk] -- name: compile Callas binaries +- name: Compile Callas binaries. ansible.builtin.import_tasks: "compile_callas_binaries.yml" tags: [callas, callaspdf, callassdk] -- name: install fonts +- name: Install fonts. Conversion requires installed fonts to work. ansible.builtin.import_tasks: "install_fonts.yml" tags: [fonts] -- name: install validators +- name: Install validators. ansible.builtin.import_tasks: "install_validators.yml" tags: [validators] -- name: install converters +- name: Install converters. ansible.builtin.import_tasks: "install_converters.yml" tags: [converters] -- name: configure Crontab +- name: > + Configure Crontab for cleanup tasks in order to prevent clogging the + temporary file storage. ansible.builtin.import_tasks: "configure_crontab.yml" tags: [cron] -- name: configure iptables +- name: Configure iptables. ansible.builtin.import_tasks: "configure_iptables.yml" tags: [firewall, iptables]