From d7aff91545aafc278d93aa445e1da1c95dbf45e6 Mon Sep 17 00:00:00 2001
From: David Redmin <david.redmin@gwe.cisa.dhs.gov>
Date: Wed, 2 Oct 2024 17:19:09 -0400
Subject: [PATCH] Update README from skeleton to include useful information

Co-authored-by: Mark Feldhousen <mark.feldhousen@gwe.cisa.dhs.gov>
---
 README.md | 112 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 98 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 139655b..abee5e9 100644
--- a/README.md
+++ b/README.md
@@ -5,20 +5,104 @@
 [![Coverage Status](https://coveralls.io/repos/github/cisagov/cyhy-db/badge.svg?branch=develop)](https://coveralls.io/github/cisagov/cyhy-db?branch=develop)
 [![Known Vulnerabilities](https://snyk.io/test/github/cisagov/cyhy-db/develop/badge.svg)](https://snyk.io/test/github/cisagov/cyhy-db)
 
-This is a generic skeleton project that can be used to quickly get a
-new [cisagov](https://github.com/cisagov) Python library GitHub
-project started.  This skeleton project contains [licensing
-information](LICENSE), as well as
-[pre-commit hooks](https://pre-commit.com) and
-[GitHub Actions](https://github.com/features/actions) configurations
-appropriate for a Python library project.
-
-## New Repositories from a Skeleton ##
-
-Please see our [Project Setup guide](https://github.com/cisagov/development-guide/tree/develop/project_setup)
-for step-by-step instructions on how to start a new repository from
-a skeleton. This will save you time and effort when configuring a
-new repository!
+This repository implements a Python module for interacting with a Cyber Hygiene database.
+
+## Pre-requisites ##
+
+- [Python 3.10](https://www.python.org/downloads/) or newer
+- A running [MongoDB](https://www.mongodb.com/) instance that you have access to
+
+## Starting a Local MongoDB Instance for Testing ##
+
+> [!IMPORTANT] This requires [Docker](https://www.docker.com/) to be installed in
+> order for this to work.
+
+You can start a local MongoDB instance in a container with the following
+command:
+
+```console
+pytest -vs --mongo-express
+```
+
+> [!NOTE] The command `pytest -vs --mongo-express` not only starts a local
+> MongoDB instance, but also runs all the `cyhy-db` unit tests, which will
+> create various collections and documents in the database.
+
+Sample output (trimmed to highlight the important parts):
+
+```console
+<snip>
+MongoDB is accessible at mongodb://mongoadmin:secret@localhost:32859 with database named "test"
+Mongo Express is accessible at http://admin:pass@localhost:8081
+
+Press Enter to stop Mongo Express and MongoDB containers...
+```
+
+Note that the previous command will execute all of the `cyhy-db` unit tests,
+which will create a variety of collections and documents.
+
+Based on the example output above, you can access the MongoDB instance at
+`mongodb://mongoadmin:secret@localhost:32859` and the Mongo Express web
+interface at `http://admin:pass@localhost:8081`.  Note that the MongoDB
+containers will remain running until you press "Enter" in that terminal.
+
+## Example Usage ##
+
+Once you have a MongoDB instance running, the sample Python code below
+demonstrates how to initialize the database, create a new request document, save
+it, and then retrieve it.
+
+```python
+import asyncio
+from cyhy_db import initialize_db
+from cyhy_db.models import RequestDoc
+from cyhy_db.models.request_doc import Agency
+
+async def main():
+    # Initialize the CyHy database
+    await initialize_db("mongodb://mongoadmin:secret@localhost:32859", "test")
+
+    # Create a new CyHy request document and save it in the database
+    new_request = RequestDoc(
+        agency=Agency(name="Acme Industries", acronym="AI")
+    )
+    await new_request.save()
+
+    # Find the request document and print its agency information
+    request = await RequestDoc.get("AI")
+    print(request.agency)
+
+asyncio.run(main())
+```
+
+Output:
+
+```console
+name='Acme Industries' acronym='AI' type=None contacts=[] location=None
+```
+
+## Additional Testing Options ##
+
+> [!WARNING] The default usernames and passwords are for testing purposes only.
+> Do not use them in production environments. Always set strong, unique
+> credentials.
+
+### Environment Variables ###
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MONGO_INITDB_ROOT_USERNAME` | The MongoDB root username | `mongoadmin` |
+| `MONGO_INITDB_ROOT_PASSWORD` | The MongoDB root password | `secret` |
+| `DATABASE_NAME` | The name of the database to use for testing | `test` |
+| `MONGO_EXPRESS_PORT` | The port to use for the Mongo Express web interface | `8081` |
+
+### Pytest Options ###
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--mongo-express` | Start a local MongoDB instance and Mongo Express web interface | n/a |
+| `--mongo-image-tag` | The tag of the MongoDB Docker image to use | `docker.io/mongo:latest` |
+| `--runslow` | Run slow tests | n/a |
 
 ## Contributing ##