Update and organize documentation

docs/developer/README.md

@@ -0,0 +1,37 @@
+# Development
+========================
+
+If you're new to Django, see [Getting Started with Django](https://www.djangoproject.com/start/) for an introduction to the framework.
+
+## Local Setup
+
+* Install Docker <https://docs.docker.com/get-docker/>
+* Initialize the application:
+
+  ```shell
+  cd src
+  docker-compose build
+  ```
+* Run the server: `docker-compose up`
+
+  Press Ctrl-c when you'd like to exit or pass `-d` to run in detached mode.
+
+Visit the running application at [http://localhost:8080](http://localhost:8080).
+
+## Setting Vars
+
+Every environment variable for local development is set in [src/docker-compose.yml](../../src/docker-compose.yml).
+
+Including variables which would be secrets and set via a different mechanism elsewhere.
+
+## Viewing Logs
+
+If you run via `docker-compose up`, you'll see the logs in your terminal.
+
+If you run via `docker-compose up -d`, you can get logs with `docker-compose logs -f`.
+
+You can change the logging verbosity, if needed. Do a web search for "django log level".
+
+## Running tests
+
+tbd.

docs/operations/README.md

@@ -0,0 +1,35 @@
+# Operations
+========================
+
+Some basic information and setup steps are included in this README.
+
+Instructions for specific actions can be found in our [runbooks](./runbooks/).
+
+## Continuous Delivery
+
+We use a [cloud.gov service account](https://cloud.gov/docs/services/cloud-gov-service-account/) to deploy from this repository to cloud.gov with a SpaceDeveloper user.
+
+## Authenticating to Cloud.gov via the command line
+
+You'll need the [Cloud Foundry CLI](https://docs.cloud.gov/getting-started/setup/).
+
+We use the V7 Cloud Foundry CLI.
+
+```shell
+cf login -a api.fr.cloud.gov --sso
+```
+
+After authenticating, make sure you are targeting the correct org and space!
+
+```bash
+cf spaces
+cf target -o <ORG> -s <SPACE>
+```
+
+## Database
+
+In sandbox, created with `cf create-service aws-rds micro-psql getgov-database`.
+
+Binding the database in `manifest-<ENVIRONMENT>.json` automatically inserts the connection string into the environment as `DATABASE_URL`.
+
+[Cloud.gov RDS documentation](https://cloud.gov/docs/services/relational-database/).

docs/operations/runbooks/rotate_application_secrets.md

@@ -1,24 +1,7 @@
-# Operations
+# HOWTO Rotate the Application's Secrets
 ========================
 
-## Authenticating
+Secrets are read from the running environment.
-
-You'll need the [Cloud Foundry CLI](https://docs.cloud.gov/getting-started/setup/).
-
-We use the V7 Cloud Foundry CLI.
-
-```shell
-cf login -a api.fr.cloud.gov --sso
-```
-
-After authenticating, make sure you are targeting the correct org and space!
-
-```bash
-cf spaces
-cf target -o <ORG> -s <SPACE>
-```
-
-## Rotating Environment Secrets
 
 Secrets were originally created with:
 
@@ -48,12 +31,4 @@ cf uups getgov-credentials -p credentials-unstable.json
 cf restage getgov-unstable --strategy rolling
 ```
 
-Non-secret environment variables can be declared in `manifest-<ENVIRONMENT>.json` directly.
+Non-secret environment variables can be declared in `manifest-<ENVIRONMENT>.json` directly.
-
-## Database
-
-In sandbox, created with `cf create-service aws-rds micro-psql getgov-database`.
-
-Binding the database in `manifest-<ENVIRONMENT>.json` automatically inserts the connection string into the environment as `DATABASE_URL`.
-
-[Cloud.gov RDS documentation](https://cloud.gov/docs/services/relational-database/).

docs/operations/runbooks/rotate_continuous_deployment_secrets.md

@@ -0,0 +1,12 @@
+# HOWTO Rotate Cloud.gov Secrets
+========================
+
+These are the secrets GitHub uses to access Cloud.gov during continuous deployment.
+
+Make sure that you have cf v7 and not cf v8 as it will not work with this script. 
+
+Secrets are set and rotated using the [cloud.gov secret rotation script](../../../ops/scripts/rotate_cloud_secrets.sh).
+
+Prerequisites for running the script are installations of `jq`, `gh`, and the `cf` CLI tool. 
+
+NOTE: Secrets must be rotated every 90 days. This script can be used for that routine rotation or it can be used to revoke and re-create tokens if they are compromised.

docs/operations/runbooks/update_python_dependencies.md

@@ -0,0 +1,8 @@
+# HOWTO Update Python Dependencies
+========================
+
+1. Check the [Pipfile](./src/Pipfile) for pinned dependencies and manually adjust the version numbers
+1. Run `cd src`, `docker-compose up -d`, and `docker-compose exec app pipenv update` to perform the upgrade and generate a new [Pipfile.lock](./src/Pipfile.lock) 
+1. (optional) Run `docker-compose stop` and `docker-compose build` to build a new image for local development with the updated dependencies.
+
+The reason for de-coupling the `build` and `update` steps is to increase consistency between builds and reduce "it works on my laptop!". Therefore, `build` uses the lock file as-is; dependencies are never updated except by explicit choice.

docs/runbook/continuous_delivery.md

@@ -1,17 +0,0 @@
-# Cloud.gov Continuous Delivery
-
-We use a [cloud.gov service account](https://cloud.gov/docs/services/cloud-gov-service-account/) to deploy from this repository to cloud.gov with a SpaceDeveloper user.
-
-## Rotating Cloud.gov Secrets
-
-Make sure that you have cf v7 and not cf v8 as it will not work with this script. 
-
-Secrets are set and rotated using the [cloud.gov secret rotation script](./scripts/rotate_cloud_secrets.sh).
-
-Prerequistes for running the script are installations of `jq`, `gh`, and the `cf` CLI tool. 
-
-NOTE: Secrets must be rotated every 90 days. This script can be used for that routine rotation or it can be used to revoke and re-create tokens if they are compromised.
-
-## Github Action
-
-TBD info about how we are using the github action to deploy.

src/README.md

@@ -1,22 +1,6 @@
-# Registrar
+# Registrar source code
 ========================
 
-## Development
+[Developer documentation](../docs/developer/README.md) is in [docs/developer](../docs/developer/).
 
-If you're new to Django, see [Getting Started with Django](https://www.djangoproject.com/start/) for an introduction to the framework.
+[Operations documentation](../docs/operations/README.md) is in [docs/operations](../docs/operations/).
-
-### Local Setup
-
-* Install Docker <https://docs.docker.com/get-docker/>
-* Initialize the application:
-
-  ```shell
-  cd src
-  docker-compose build
-  ```
-* Run the server: `docker-compose up`
-
-### Update Dependencies
-
-1. Check the [Pipfile](./src/Pipfile) for pinned dependencies and manually adjust the version numbers
-1. Run `cd src`, `docker-compose up`, and `docker-compose exec app pipenv update` to perform the upgrade and generate a new [Pipfile.lock](./src/Pipfile.lock)