feat: usage instructions

Makefile

@@ -53,29 +53,29 @@ define test_loadbalance
 endef
 
 
-configure:
+configure: ## Configure whole deployment 
 	$(call configure_ping)
 	$(call configure_base)
 	$(call configure_libreddit)
 	$(call configure_loadbalance)
 
-configure.ping:
+configure.ping: ## Ping all VMs
 	$(call configure_ping)
 
-configure.base:
+configure.base: ## Configure all VMs to base production configuration
 	$(call configure_ping)
 	$(call configure_base)
 
-configure.libreddit:
+configure.libreddit: ## Configure libreddit
 	$(call configure_ping)
 	$(call configure_libreddit)
 
-configure.loadbalance:
+configure.loadbalance: ## Configure loadbalancer
 	$(call configure_ping)
 	$(call configure_loadbalance)
 
 
-lint:
+lint: ## Lint source code
 	terraform fmt
 	ansible-lint --write ./ansible/playbook.yml
 	ansible-lint --write ./ansible/shutdown.yml
@@ -83,23 +83,27 @@ lint:
 	ansible-lint --write ./ansible/libreddit.yml
 	. ./venv/bin/activate && black tests/
 
-on:
+on: ## Boot VMs
 	./scripts/on.sh
 	virsh list
 
-shutdown:
+shutdown: ## Shutdown VMs
 	ansible-playbook -i ./ansible/inventory/hosts.ini -f 10 ./ansible/shutdown.yml
 
-test:
+test: ## Run all tests
 	$(call test_base)
 	$(call test_loadbalance)
 	$(call test_libreddit)
 
-test.base:
+test.base: ## Test base configuration on all VMs
 	$(call test_base)
 
-test.loadbalance:
+test.loadbalance: ## Test loadbalancer installation
 	$(call test_loadbalance)
 
-test.libreddit:
+test.libreddit: ## Test libreddit installation
 	$(call test_libreddit)
+
+
+help: ## Prints help for targets with comments
+	@cat $(MAKEFILE_LIST) | grep -E '^[a-zA-Z_-].+:.*?## .*$$' | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

README.md

@@ -0,0 +1,78 @@
+# Load-balanced libreddit deployment
+
+Use KVM/QEMU, Docker, libvirt, Terraform, and Ansible to deploy
+loadbalanced [libreddit](https://github.com/libreddit/libreddit/) and
+verify deployment with Testinfra.
+
+## Dependencies
+
+1. GNU/Linux host machine
+2. KVM
+3. QEMU
+4. Libvirt
+5. Terraform
+6. Python 3
+7. Ansible
+8. Testinfra
+9. Debian 11 Bullseye qcow2 bootable
+
+## Usage instructions
+
+### 1. Provision resources (VMs) on KVM using Terraform
+
+1. Generate and verify deployment plan
+
+```bash
+terraform plan -out=libreddit
+```
+
+2. Apply deployment plan
+
+```bash
+terraform apply "libreddit"
+```
+
+### 2. Verify VMs are reachable from host
+
+```bash
+make configure.ping
+```
+
+### 3. Configure VMs
+
+```bash
+make configure
+```
+
+### 4. Test deployment
+
+```bash
+make test
+```
+
+### 5. Take down deployment
+
+```bash
+terraform destroy
+```
+
+## Functions
+
+Utility scripts exist for the following operations:
+
+```bash
+19:46 atm@lab iac ±|master ✗|→ make help
+configure                      Configure whole deployment
+configure.ping                 Ping all VMs
+configure.base                 Configure all VMs to base production configuration
+configure.libreddit            Configure libreddit
+configure.loadbalance          Configure loadbalancer
+lint                           Lint source code
+on                             Boot VMs
+shutdown                       Shutdown VMs
+test                           Run all tests
+test.base                      Test base configuration on all VMs
+test.loadbalance               Test loadbalancer installation
+test.libreddit                 Test libreddit installation
+help                           Prints help for targets with comments
+```