Repository fixes

Makefile

@@ -1,3 +1,4 @@
+CONTAINER = astro
 SOURCE_DIR = ${CURDIR}/site
 
 # The OS environment variable is always defined by windows.
@@ -15,7 +16,7 @@ else
 endif
 
 serve: up
-	@docker-compose exec astro sh -c "npm run dev"
+	@docker-compose exec $(CONTAINER) sh -c "npm run dev"
 
 up:
 	@docker-compose up --detach
@@ -24,38 +25,51 @@ down:
 	@docker-compose down
 
 shell:
-	@docker-compose exec astro bash
+	@docker-compose exec $(CONTAINER) bash
 
 version: up
 ifndef number
 	$(error Please define a 'number' that represents the new version)
 endif
-	@docker-compose exec astro sh -c "npm version ${number}"
+	@docker-compose exec $(CONTAINER) sh -c "npm version ${number}"
 # @git tag -a v${number}
 
 preview: $(SOURCE_DIR)/dist
-	@docker-compose exec astro sh -c "npm run preview"
+	@docker-compose exec $(CONTAINER) sh -c "npm run preview"
 
 build:
 	@docker-compose build
 
 dist: clean-js-dist $(SOURCE_DIR)/dist
 
 $(SOURCE_DIR)/dist:
-	@docker-compose exec astro sh -c "npm run build"
+	@docker-compose exec $(CONTAINER) sh -c "npm run build"
 
 $(SOURCE_DIR)/node_modules:
 	@echo Install JS dependencies. This will take awhile.
-	docker-compose exec astro sh -c "npm install"
+	docker-compose exec $(CONTAINER) sh -c "npm install"
+
+upgrade-astro: up
+	@echo Updating Astro specific dependencies.
+	@docker compose exec ${CONTAINER} sh -c "npx @astrojs/upgrade"
+
+update-dependencies: up
+	@echo Updating package.json.
+	@docker compose exec ${CONTAINER} sh -c "npx npm-check-updates -u"
+
+clean-astro-content:
+	@echo Removing the Astro content directories.
+	@$(RemoveDirCmd) $(call FixPath,$(SOURCE_DIR)/.astro)
 
 clean-js-dist:
 	$(RemoveDirCmd) $(call FixPath,$(SOURCE_DIR)/dist)
 
 clean-js-modules:
 	$(RemoveDirCmd) $(call FixPath,$(SOURCE_DIR)/node_modules)
 
-clean: clean-js-dist clean-js-modules
+clean: clean-astro-content clean-js-dist clean-js-modules
 
 .PHONY: serve up down build shell \
-	clean clean-js-dist clean-js-modules \
+    upgrade-astro update-dependencies \
+	clean clean-astro-content clean-js-dist clean-js-modules \
 	.FORCE

README.md

@@ -18,4 +18,16 @@ We [welcome comments and feedback](https://github.com/accessiblecommunity/useabl
     * When cloning the repository, you make use your local [Node.js](https://nodejs.org/) install, or the supplied [Docker](https://www.docker.com/) container.
 * The [`site`](https://github.com/accessiblecommunity/useable/tree/main/site) folder contains the javascript code used to build the site.
     * `useable` is powered by [Astro](https://astro.build/).
-    * The `integration` folder is an Astro integration that converts the raw data into Astro content.
+    * The `integration` folder is an Astro integration that converts the raw data into Astro content.
+
+## Setting up a Development Environment
+
+On almost every project, getting your development environment established is the first task and it can take a day or two to do so. This is a high-level overview so that you can be productive quickly.
+
+* If you don't have one, we recommend installing an IDE that supports multiple languages (Python, Javascript, HTML/CSS, etc). The recommendations are [VS Code](https://code.visualstudio.com/) or [Sublime Text](https://www.sublimetext.com/), but really this is a developer choice.
+* Install [Docker Desktop](https://www.docker.com/products/docker-desktop) or another way to run a containerized environment.
+  * If on Windows, we recommend installing the [Linux Subsystem](https://learn.microsoft.com/en-us/windows/wsl/install) to help performance, but it’s not required. See [configuring Docker Desktop to use WSL 2](https://docs.docker.com/desktop/wsl/).
+* Install a way to run `make`.
+  * On Windows, use the Linux Subsystem or [chocolatey](https://chocolatey.org/).
+  * On Mac, install the Xcode client tools or use [homebrew](https://brew.sh/).
+  * If preferred, install some integration with the IDE you are using instead.

docker-compose.yml

@@ -1,14 +1,12 @@
-version: "3.7"
-
 services:
   astro:
-    container_name: astro
+    container_name: useable-astro
     build:
       context: ./site
       target: dev-test
     restart: always
     ports:
-      - 4321:4321
-      - 4322:4322
+      - 4323:4323
+      - 4324:4324
     volumes:
       - '.:/useable'