Add post setup docs

docs/src/getting_started.md

@@ -175,7 +175,7 @@ $ ansible-inventory --graph --vars
 $ ansible-playbook main.yml
 ```
 
-The playbook will perform the following idempotently:
+The playbook will perform the following:
 
 1. Create a root and intermediate CA for Vault
 2. Configure Vault to use new CA
@@ -196,3 +196,31 @@ existing state in the `terraform/vault` subdirectory if a different
 `vault_terraform_workspace` is not provided. This WILL result in permanent data
 loss and care should be taken when running the role (and playbook) on multiple
 clusters or servers.
+
+## Post Setup
+
+### Smoke Tests
+
+Smoke tests are performed with [goss](https://github.com/goss-org/goss) as part
+of the `main.yml` playbook to ensure all required software are installed and
+running.
+
+>**Note**: The included goss files are static with hardcoded information. As
+>such, they will fail if some of the Ansible default variables are changed (eg.
+>username, NFS mountpoints). See
+>[issues](./references/issues.md#static-goss-files) for details on a workaround.
+
+### Running Applications
+
+After verifying that the cluster is up and running, we can begin to run
+applications on it with Nomad jobs. This project provides a number of Nomad
+jobspec files in `terraform/nomad/apps` to be run with Terraform with the
+following features:
+
+- With Vault integration configured, Nomad supports the fetching of application
+secrets with Vault
+- Traefik as a reverse proxy
+- (Optional) Postgres as a database (with Vault-managed DB credentials)
+
+See [Adding a New Application](./apps/add_new.md) for details on onboarding a
+new application to Nomad.

docs/src/references/issues.md

@@ -23,3 +23,20 @@ is [not supported](https://github.com/hashicorp/vault/issues/20538).~
 [#18562](https://github.com/hashicorp/vault/issues/18562). A
 [fix](https://github.com/hashicorp/vault/pull/19002) is available in Vault
 1.14.~
+
+## Static Goss Files
+
+The provided goss files in `ansible/goss` contain hardcoded information that can
+cause the smoke tests to fail if some Ansible variables are modified:
+
+- common_user
+- common_nfs_dir
+- common_packages
+
+The temporary workaround is to create your own goss files, edit the given goss
+files or to simply comment out the smoke test tasks.
+
+To fix this, goss
+[supports](https://github.com/goss-org/goss/blob/master/docs/gossfile.md#templates)
+templating to create dynamic goss files. The `ansible_collection.goss` role must
+be modified to add support for dynamic tests.