api: Updates to Makefile and configuration files.

- Re-organized and documented make targets.
- Parameterized the make targets to more cleanly support multiple
  development scenarios.
- Documented the different development scenarios in a README.
- Standardized the host port used when running locally.
- Updated DEV and PROD database config files to match current practice.
- Renamed `personal_measure_api.config.prod.json` to
  `personal_measure_api.config.docker.json` to more accurately reflect
  that this is the config used when building the docker image
  (regardless of which env it ends up in).

api/Dockerfile

@@ -16,7 +16,7 @@ RUN apk -v --update add --no-cache \
   postgresql-client
 
 COPY --from=build /pm-api/personal_measure_api /
-COPY personal_measure_api.config.prod.json /personal_measure_api.config.json
+COPY personal_measure_api.config.docker.json /personal_measure_api.config.json
 CMD ["/personal_measure_api", "serve"]
 
 # TODO: replace the above with something like:

api/Makefile

@@ -1,45 +1,123 @@
 PGSQL_CONTAINER_ID=`cat postgres.container.id`
-ECR_ACCOUNT_URL=063932952339.dkr.ecr.us-west-2.amazonaws.com
-DB_NAME="personal_measure"
-VERSION=`git describe`
 SOURCES=$(wildcard src/main/nim/*.nim) $(wildcard src/main/nim/personal_measure_apipkg/*.nim)
 
-serve-local: personal_measure_api start-postgres
+# Variables that can be overriden
+# -------------------------------
+
+# AWS Account URL for the ECR repository
+ECR_ACCOUNT_URL ?= 063932952339.dkr.ecr.us-west-2.amazonaws.com
+
+# The version number that will be tagged the container image. You might want to
+# override this when doing local development to create local versions that are
+# reflect changes not yet committed.
+VERSION ?= `git describe`
+
+# The port on the host machine (not the container)
+PORT ?= 8100
+
+# The name of the database (used then creating a local Postgres container)
+DB_NAME ?= personal_measure
+
+# The database connection string. You would change this to point the API at a
+# different database server (default is the local Postgres container).
+DB_CONN_STRING ?= host=localhost dbname=$(DB_NAME) user=postgres password=password port=5500
+
+# The API authentication secret (used for hashing passwords, etc.)
+AUTH_SECRET ?= 123abc
+
+
+default: start-postgres serve-docker
+
+# Building and deploying the API container image
+# ----------------------------------------------
+
+personal_measure_api-image: $(SOURCES)
+	# Build the container image.
+	docker image build -t $(ECR_ACCOUNT_URL)/personal_measure_api:$(VERSION) .
+
+push-image: personal_measure_api-image
+	# Push the container image to the private AWS ECR
+	docker push $(ECR_ACCOUNT_URL)/personal_measure_api:$(VERSION)
+
+# Running the API locally on bare metal
+# -------------------------------------
+
+personal_measure_api: $(SOURCES)
+	# Build the API
+	nimble build
+
+serve: personal_measure_api
+	# Run the API on this machine. Note that configuration is taken by default
+	# from the `personal_measure_api.config.json` file, but environment variables
+	# specified when running make can be used to override these (to change the
+	# DB_CONN_STRING, for example).
 	./personal_measure_api serve
 
-serve-docker: personal_measure_api-image start-postgres
-	docker run -e AUTH_SECRET=abc123 -e "DB_CONN_STRING=host=host.docker.internal port=5500 user=postgres password=password dbname=personal_measure" -e PORT=80 -p 127.0.0.1:8100:80/tcp $(ECR_ACCOUNT_URL)/personal_measure_api:$(VERSION)
+# Running the API locally in a container
+# --------------------------------------
+
+serve-docker: personal_measure_api-image
+	# Run the API in a docker container. Note that the configuration loaded into
+	# the Docker container defines very little of the actual configuration as
+	# environment variables are used in the deployed environments. Accordingly,
+	# we must specify them explicitly here.
+	docker run \
+		-e AUTH_SECRET=$(AUTH_SECRET) \
+		-e PORT=80 \
+		-e "DB_CONN_STRING=$(DB_CONN_STRING)" \
+		-e 'KNOWN_ORIGINS=["https://curl.localhost"]' \
+		-p 127.0.0.1:$(PORT):80/tcp \
+		$(ECR_ACCOUNT_URL)/personal_measure_api:$(VERSION)
+
+# Managing Postgres in a local container
+# --------------------------------------
+#
+#   This supports local development on this machine. These commands rely on a
+#   file named `postgres.container.id` to track the existing and ID of the
+#   local Postgres instance.
 
 postgres.container.id:
+	# This creates a new local Postegres container and initializes the PM API
+	# database scheme.
 	docker run --name postgres-$(DB_NAME) -e POSTGRES_PASSWORD=password -p 5500:5432 -d postgres > postgres.container.id
 	sleep 5
 	PGPASSWORD=password psql -p 5500 -U postgres -h localhost -c "CREATE DATABASE $(DB_NAME);"
 	db_migrate up -c database-local.json
 
 start-postgres: postgres.container.id
+	# Start the existing local Postgres container
 	docker start $(PGSQL_CONTAINER_ID)
 	sleep 1
 	db_migrate up -c database-local.json
 
 stop-postgres: postgres.container.id
+	# Stop the existing local Postgres container
 	docker stop $(PGSQL_CONTAINER_ID)
 
 delete-postgres-container:
+	# Delete the local Postgres container. Note that this will destroy any data
+	# in this database instance.
 	-docker stop $(PGSQL_CONTAINER_ID)
 	docker container rm $(PGSQL_CONTAINER_ID)
 	rm postgres.container.id
 
-connect:
+connect-postgres:
+	# Connect to the Postgres instance running in the local container
 	PGPASSWORD=password psql -p 5500 -U postgres -h localhost ${DB_NAME}
 
+
+# Utility
+# -------
+
 ecr-auth:
+	# Authenticate docker to the AWS private elastic container repository.
 	aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 063932952339.dkr.ecr.us-west-2.amazonaws.com
 
-personal_measure_api: $(SOURCES)
-	nimble build
-
-personal_measure_api-image: $(SOURCES)
-	docker image build -t $(ECR_ACCOUNT_URL)/personal_measure_api:$(VERSION) .
-
-push-image: personal_measure_api-image
-	docker push $(ECR_ACCOUNT_URL)/personal_measure_api:$(VERSION)
+echo-vars:
+	@echo \
+		" ECR_ACCOUNT_URL=$(ECR_ACCOUNT_URL)\n" \
+		"VERSION=$(VERSION)\n" \
+		"PORT=$(PORT)\n" \
+		"DB_NAME=$(DB_NAME)\n" \
+		"DB_CONN_STRING=$(DB_CONN_STRING)\n" \
+		"AUTH_SECRET=$(AUTH_SECRET)\n"

api/README.md

@@ -0,0 +1,30 @@
+## Local Development
+
+Examples of different local development & testing scenarios:
+
+- Bare-metal API server, local Postgres container
+
+      make start-postgres
+      make serve
+
+- Bare-metal API server, different Postgres server
+
+      DB_CONN_STRING="host=<db-hostname> user=pmapi password=<pwd>" make serve
+
+- Docker API Server, local Postgres container
+
+      make start-postgres
+      VERSION=0.X.0-alpha make serve-docker
+
+- Docker API server, different Postgres server
+
+      DB_CONN_STRING="host=<db-hostname> user=pmapi password=<pwd>" \
+      VERSION=0.X.0-alpha \
+        make serve-docker
+
+All of the available `make` targets are documented inline; see the
+[Makefile](./Makefile) for more details.
+
+### Using the API CLI wrapper
+
+The API CLI wrapper

api/database-dev.json

@@ -1,5 +1,5 @@
 {
   "driver": "postgres",
-  "connectionString": "host=localhost port=5999 dbname=personal_measure_dev user=postgres",
+  "connectionString": "host=localhost port=5432 dbname=personal_measure_dev user=pmapi",
   "sqlDir": "src/main/sql/migrations"
 }

api/database-prod.json

@@ -1,5 +1,5 @@
 {
   "driver": "postgres",
-  "connectionString": "host=localhost port=5999 dbname=personal_measure user=postgres",
+  "connectionString": "host=localhost port=5432 dbname=personal_measure user=pmapi",
   "sqlDir": "src/main/sql/migrations"
 }

api/personal_measure_api.config.docker.json

@@ -0,0 +1,4 @@
+{
+  "debug":false,
+  "pwdCost":11
+}

api/personal_measure_api.config.json

@@ -2,7 +2,7 @@
   "authSecret":"bifekHuffIs3",
   "dbConnString":"host=localhost port=5500 dbname=personal_measure user=postgres password=password",
   "debug":true,
-  "port":8081,
+  "port":8100,
   "pwdCost":11,
   "knownOrigins": [ "https://curl.localhost" ]
 }

api/personal_measure_api.config.prod.json

@@ -1,5 +0,0 @@
-{
-  "debug":false,
-  "pwdCost":11,
-  "knownOrigins": [ "https://pm.jdb-software.com", "https://pm-dev.jdb-software.com" ]
-}