From 54ff79dfe0ed31fc4c0345cf4847e858f1972eaa Mon Sep 17 00:00:00 2001
From: Adam Chalkley <atc0005@users.noreply.github.com>
Date: Thu, 21 Jan 2021 05:01:10 -0600
Subject: [PATCH] Add doc coverage for manual first run requirement

- Add Wrap-up section to README
- Extend deployment doc
  - add steps for deploying Postfix support packages,
    config fragments
- Add wrap-up doc file listing manual first-run requirement

refs GH-7
---
 README.md       |  5 +++++
 docs/deploy.md  | 34 ++++++++++++++++++++++++++++++++++
 docs/wrap-up.md | 30 ++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+)
 create mode 100644 docs/wrap-up.md

diff --git a/README.md b/README.md
index a3a2aa77..12b452ef 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ Mirror MySQL database tables to local SQLite database.
   - [Build applications](#build-applications)
   - [Deploy applications](#deploy-applications)
   - [Configure applications](#configure-applications)
+  - [Wrap-up](#wrap-up)
 - [License](#license)
 - [References](#references)
 
@@ -144,6 +145,10 @@ See the [deployment](docs/deploy.md) documentation for details.
 
 See the [configure](docs/configure.md) doc for details.
 
+### Wrap-up
+
+See the [wrap-up](docs/wrap-up.md) doc for remaining steps.
+
 ## License
 
 From the [LICENSE](LICENSE) file:
diff --git a/docs/deploy.md b/docs/deploy.md
index ba5985e5..3656fde0 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -23,6 +23,10 @@
   - [Deploy logrotate config fragment](#deploy-logrotate-config-fragment)
   - [Deploy cron config fragment](#deploy-cron-config-fragment)
   - [Deploy Nagios "client" configuration file](#deploy-nagios-client-configuration-file)
+  - [Postfix](#postfix)
+    - [Install Support packages](#install-support-packages)
+    - [Deploy lookup table config fragments](#deploy-lookup-table-config-fragments)
+    - [Restart Postfix to apply changes](#restart-postfix-to-apply-changes)
 
 ## Overview
 
@@ -226,3 +230,33 @@ will be executed.
 1. Restart the `nrpe` daemon
    - Debian-based: `sudo service nagios-nrpe-server restart`
    - RedHat-based: `sudo service nrpe restart`
+
+### Postfix
+
+#### Install Support packages
+
+These directions assume that an existing Postfix installation is present,
+likely with MySQL support packages already installed. At this point the next
+step is to install the support packages necessary for Postfix to query SQLite
+databases for lookup table information.
+
+1. `sudo apt-get update`
+1. `sudo apt-get install postfix-mysql`
+   - on the chance that the package is not already present
+1. `sudo apt-get install postfix-sqlite`
+
+#### Deploy lookup table config fragments
+
+Once the Postfix SQLite support package is installed, we need to deploy the
+lookup table config fragments which instruct Postfix how to find the database
+and what queries to use to obtain lookup table information. As is the case for
+the rest of these directions, the exact steps needed for your environment will
+vary.
+
+1. `sudo mkdir -vp /etc/postfix/lookup_tables/sqlite`
+1. Deploy all `postfix/lookup_tables/sqlite/*.cf` files to
+   `/etc/postfix/lookup_tables/sqlite/`
+
+#### Restart Postfix to apply changes
+
+1. `sudo systemctl restart postfix`
diff --git a/docs/wrap-up.md b/docs/wrap-up.md
new file mode 100644
index 00000000..cb015039
--- /dev/null
+++ b/docs/wrap-up.md
@@ -0,0 +1,30 @@
+<!-- omit in toc -->
+# mysql2sqlite: Wrap-up
+
+- [Project README](../README.md)
+
+<!-- omit in toc -->
+## Table of contents
+
+### Generate SQLite database file
+
+After [deploying](deploy.md) and [configuring](configure.md) the applications,
+the next step is the first manual run of the `mysql2sqlite` binary in order to
+generate the `mailserver.db` SQLite database file. From there, the wrapper
+scripts described previously can be used to monitor the database and keep it
+in sync.
+
+**NOTE**: The database must be created manually *at least once*, otherwise a
+loop of sorts will occur.
+
+This loop occurs because the wrapper script used to generate the SQLite
+database requires either an `OK` or `WARNING` state as a response from the
+Nagios plugin. If a `CRITICAL` state is returned (e.g., the database file is
+missing or empty) the `mysql2sqlite` binary is never called. This occurs most
+often on a system where `mysql2sqlite` has not previously been used.
+
+The workaround is to run the `mysql2sqlite` binary once manually to bootstrap
+the process.
+
+1. `sudo -u mysql2sqlite /usr/local/sbin/mysql2sqlite --config-file
+   /usr/local/etc/mysql2sqlite/config.yaml --log-format logfmt`