Refresh docs

README.md

@@ -2,6 +2,63 @@
 
 Stack allows building and deployment of a suite of related applications as a single "stack".  It is a fork of https://git.vdb.to/cerc-io/stack intended for more general use.
 
+## Quick Start
+
+### Docker
+
+```
+# clone / build
+stack fetch stack bozemanpass/example-todo-list
+stack build containers --stack ~/bpi/example-todo-list/stacks/todo
+
+# config
+stack config init \
+  --stack ~/bpi/example-todo-list/stacks/todo \
+  --output todo.yml \
+  --map-ports-to-host localhost-same
+
+# create the deployment from the config
+stack deploy --spec-file todo.yml --deployment-dir ~/deployments/todo
+
+# start / status / logs / stop
+stack manage --dir ~/deployments/todo start
+stack manage --dir ~/deployments/todo status
+stack manage --dir ~/deployments/todo logs
+stack manage --dir ~/deployments/todo stop
+```
+
+### Kubernetes
+
+```
+# clone / build
+stack fetch stack bozemanpass/example-todo-list
+stack build containers --stack ~/bpi/example-todo-list/stacks/todo \
+    --image-registry $IMAGE_REGISTRY \
+    --publish-images
+
+# config
+stack config --deploy-to k8s init \
+    --stack ~/bpi/example-todo-list/stacks/todo \
+    --output todo.yml \
+    --image-registry $IMAGE_REGISTRY \
+    --kube-config /path/to/kubeconfig.yaml \
+    --http-proxy example-todo.bpi.servesthe.world:frontend:3000 \
+    --http-proxy example-todo.bpi.servesthe.world/api/todos:backend:5000 \
+    --config REACT_APP_API_URL=https://example-todo.bpi.servesthe.world/api/todos
+
+# create the deployment from the config
+stack deploy --spec-file todo.yml --deployment-dir ~/deployments/todo
+
+# push image tags for this deployment to the image registry used by Kubernetes
+stack manage --dir ~/deployments/todo push-images
+
+# start / status / logs / stop
+stack manage --dir ~/deployments/todo start
+stack manage --dir ~/deployments/todo status
+stack manage --dir ~/deployments/todo logs
+stack manage --dir ~/deployments/todo stop
+```
+
 ## Install
 
 **To get started quickly** on a fresh Ubuntu instance (e.g, Digital Ocean); [try this script](./scripts/quick-install-linux.sh). **WARNING:** always review scripts prior to running them so that you know what is happening on your machine.
@@ -12,7 +69,7 @@ For any other installation, follow along below and **adapt these instructions ba
 Ensure that the following are already installed:
 
 - [Python3](https://wiki.python.org/moin/BeginnersGuide/Download): `python3 --version` >= `3.8.10` (the Python3 shipped in Ubuntu 20+ is good to go)
-- [Docker](https://docs.docker.com/get-docker/): `docker --version` >= `20.10.21`
+- [Docker](https://docs.docker.com/get-docker/): `docker --version` >= `20.10.21` or [podman](https://podman.io/) `podman --version` >= `3.4.4`
 - [jq](https://stedolan.github.io/jq/download/): `jq --version` >= `1.5`
 - [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git): `git --version` >= `2.10.3`
 
@@ -24,8 +81,8 @@ curl -SL https://github.com/docker/compose/releases/download/v2.11.2/docker-comp
 chmod +x ~/.docker/cli-plugins/docker-compose
 ```
 
-Next decide on a directory where you would like to put the stack program. Typically this would be 
-a "user" binary directory such as `~/bin` or perhaps `/usr/local/stack` or possibly just the current working directory.
+Next decide on a directory where you would like to put the stack program. Typically, this would be 
+a "user" binary directory such as `~/bin` or perhaps `/usr/local/bin/stack` or possibly just the current working directory.
 
 Now, having selected that directory, download the latest release from [this page](https://github.com/bozemanpass/stack/tags) into it (we're using `~/bin` below for concreteness but edit to suit if you selected a different directory). Also be sure that the destination directory exists and is writable:
 
@@ -47,12 +104,6 @@ Verify operation (your version will probably be different, just check here that
 stack version
 Version: 2.0.0-fb86d3c-202503251632
 ```
-Save the distribution url to `~/.stack/config.yml`:
-> Note: You only need to do this if you are using a fork from a different URL, rather than the main release from https://github.com/bozemanpass/stack
-```bash
-mkdir ~/.stack
-echo "distribution-url: https://github.com/bozemanpass/stack/releases/latest/download/stack" >  ~/.stack/config.yml
-```
 
 ### Update
 If `stack` was installed using the process above, it is able to self-update to the current latest version by running:
@@ -61,10 +112,17 @@ If `stack` was installed using the process above, it is able to self-update to t
 stack update
 ```
 
-## Contributing
+#### Alternate Update Locations (e.g., a fork)
 
-See the [CONTRIBUTING.md](/docs/CONTRIBUTING.md) for developer mode install.
+If you want to update from a different location (e.g., a fork), you can do so setting the distribution URL to use:
 
-## Platform Support
+Save the alternate distribution URL in `~/.stack/config.yml`:
+
+```bash
+mkdir ~/.stack
+echo "distribution-url: https://github.com/example-org/my-stack-fork/releases/latest/download/stack" >  ~/.stack/config.yml
+```
+
+## Contributing
 
-Native aarm64 is _not_ currently supported.
+See the [CONTRIBUTING.md](/docs/CONTRIBUTING.md) for developer mode install.d

docs/cli.md

@@ -2,40 +2,136 @@
 
 Sub-commands and flags
 
+## fetch stack
+```
+$ stack fetch stack bozemanpass/example-todo-list
+```
+
 ## fetch repositories
 
 Clone the repositories for a stack:
 ```
-$ stack fetch repositories --stack ~/bpi/gitea-stack
+$ stack fetch repositories --stack ~/bpi/example-todo-list/stacks/todo
 ```
 Pull latest commits from origin:
 ```
-$ stack fixturenet-eth fetch repositories --stack ~/bpi/gitea-stack --pull
+$ stack fetch repositories --stack ~/bpi/example-todo-list/stacks/todo --pull
 ```
 Use SSH rather than https:
 ```
-$ stack fixturenet-eth fetch repositories --stack ~/bpi/gitea-stack --git-ssh
+$ stack fetch repositories --stack ~/bpi/example-todo-list/stacks/todo --git-ssh
 ```
 
 ## build containers
 
-Build a single container:
+Build all containers:
+```
+$ stack build containers --stack ~/bpi/example-todo-list/stacks/todo
+```
+Build a specific container:
+```
+$ stack build containers --stack ~/bpi/example-todo-list/stacks/todo --include "bpi/todo-frontend"
+```
+Force full rebuild of container images:
 ```
-$ stack build containers --include <container-name>
+$ stack build containers --stack ~/bpi/example-todo-list/stacks/todo --build-policy build-force
 ```
-e.g.
+
+See [fetching-containers](fetching-containers.md) for more information on fetching, building,
+and checking for container images.
+
+## config
+
+Create a configuration spec file with the default values:
 ```
-$ stack build containers --include bpi/go-ethereum
+$ stack config init --stack ~/bpi/example-todo-list/stacks/todo --output todo.yml
 ```
-Build the containers for a stack:
+
+Map stack ports to localhost:
 ```
-$ stack --stack <stack-name> build containers
+$ stack config init --stack ~/bpi/example-todo-list/stacks/todo --output todo.yml --map-ports-to-host localhost-same
 ```
-e.g.
+
+Set a configuration value:
 ```
-$ stack --stack fixturenet-eth build containers
+$ stack config init --stack ~/bpi/example-todo-list/stacks/todo --output todo.yml \
+    --map-ports-to-host localhost-same \
+    --config REACT_APP_API_URL=http://127.0.0.1:5000/api/todos
 ```
-Force full rebuild of container images:
+
+Full Kubernetes configuration with image registry, HTTP ingress, and environment settings:
+```
+$ stack config --deploy-to k8s init \
+    --stack ~/bpi/example-todo-list/stacks/todo \
+    --output todo.yml                         \
+    --image-registry $IMAGE_REGISTRY \
+    --kube-config /path/to/kubeconfig.yaml \
+    --http-proxy example-todo.bpi.servesthe.world:frontend:3000 \
+    --http-proxy example-todo.bpi.servesthe.world/api/todos:backend:5000 \
+    --config REACT_APP_API_URL=https://example-todo.bpi.servesthe.world/api/todos
+```
+
+## deploy
+
+Deploy the stack according to the configuration spec:
+
+```
+$ stack deploy --spec-file todo.yml --deployment-dir ~/deployments/todo
+```
+
+## manage
+
+Push image tags for stack containers (needed with Kubernetes and external image registries):
+```
+$ stack manage --deployment-dir ~/deployments/todo push-images
+```
+
+Start the stack:
+```
+$ stack manage --deployment-dir ~/deployments/todo start
+```
+
+Stop the stack:
+```
+$ stack manage --deployment-dir ~/deployments/todo stop
+```
+
+Stop the stack and delete volumes:
+```
+$ stack manage --deployment-dir ~/deployments/todo stop --delete-volumes
+```
+
+Reload to pick up config changes:
+```
+$ stack manage --deployment-dir ~/deployments/todo reload
+```
+
+Show basic stack and container status:
+```
+$ stack manage --deployment-dir ~/deployments/todo status
+```
+
+List running container ids, names, and ports:
+```
+$ stack manage --deployment-dir ~/deployments/todo ps
+```
+
+Show port mapping details for a specific service and port:
+```
+$ stack manage --deployment-dir ~/deployments/todo port frontend 3000
+```
+
+Print service logs:
+```
+$ stack manage --deployment-dir ~/deployments/todo logs
+```
+
+Follow logs (limited to _n_ lines):
+```
+$ stack manage --deployment-dir ~/deployments/todo logs -f -n 10
+```
+
+Execute a command in a running container:
 ```
-$ stack build containers --include <container-name> --force-rebuild
+$ stack manage --dir ~/deployments/todo exec frontend 'node --version'
 ```

docs/webapp.md

@@ -1,6 +1,6 @@
 ### Building and Running Webapps
 
-It is possible to build and run Next.js webapps using the `webapp build` and `webapp run` subcommands.
+It is possible to build and run static, React, and Next.js webapps using the `webapp build` and `webapp run` subcommands.
 
 To make it easier to build once and deploy into different environments and with different configuration,
 compilation and static page generation are separated in the `webapp build` and `webapp run` steps.
@@ -18,7 +18,7 @@ can be overidden with the build arguments `BPI_NEXT_VERSION` and `BPI_BUILD_TOOL
 **Example**:
 ```
 $ cd ~/bpi
-$ git clone git@git.vdb.to:cerc-io/test-progressive-web-app.git
+$ git clone https://github.com/bozemanpass/test-progressive-web-app
 $ stack webapp build --source-repo ~/bpi/test-progressive-web-app
 ...
 
@@ -53,12 +53,12 @@ ID: 9ab96494f563aafb6c057d88df58f9eca81b90f8721a4e068493a289a976051c
 URL: http://localhost:32769
 ```
 
-## Deploying
+## Deploy and Run
 
-Use the subcommand `webapp init create` to make a deployment directory that can be subsequently deployed to a Kubernetes cluster.
+Use the subcommand `webapp deploy` to make a deployment directory that can be subsequently deployed to a Kubernetes cluster.
 Example commands are shown below, assuming that the webapp container image `bpi/test-progressive-web-app:stack` has already been built:
 ```
-$ stack webapp init create --kube-config ~/kubectl/k8s-kubeconfig.yaml --image-registry registry.digitalocean.com/laconic-registry --deployment-dir webapp-k8s-deployment --image bpi/test-progressive-web-app:stack --url https://test-pwa-app.hosting.laconic.com/ --env-file test-webapp.env
-$ stack deployment --dir webapp-k8s-deployment push-images
-$ stack deployment --dir webapp-k8s-deployment start
+$ stack webapp deploy --kube-config ~/kubectl/k8s-kubeconfig.yaml --image-registry registry.digitalocean.com/laconic-registry --deployment-dir ~/bpi/webapp-k8s-deployment --image bpi/test-progressive-web-app:stack --url https://test-pwa-app.bpi.servesthe.world --env-file test-webapp.env
+$ stack manage --dir ~/bpi/webapp-k8s-deployment push-images
+$ stack manage --dir ~/bpi/webapp-k8s-deployment start
 ```

src/stack/build/prepare_containers.py

@@ -191,7 +191,7 @@ def command(ctx, stack, include, exclude, git_ssh, build_policy, extra_build_arg
     )
 
     # check if we have any repos that specify the container targets / build info
-    containers_in_scope = [c for c in get_containers_in_scope(stack.name) if include_exclude_check(c, include, exclude)]
+    containers_in_scope = [c for c in get_containers_in_scope(stack.name) if include_exclude_check(c.name, include, exclude)]
     for stack_container in containers_in_scope:
         # No container ref means use the stack repo.
         if (not stack_container.ref or stack_container.ref == ".") and stack_container.path and stack.get_repo_name():

src/stack/deploy/deploy.py

@@ -148,7 +148,8 @@ def port_operation(ctx, extra_args):
         if global_context.verbose:
             print(f"Running compose port {service_name} {exposed_port}")
         mapped_port_data = ctx.obj.deployer.port(service_name, exposed_port)
-        print(f"{mapped_port_data[0]}:{mapped_port_data[1]}")
+        if mapped_port_data:
+            print(f"{mapped_port_data[0]}:{mapped_port_data[1]}")
 
 
 def exec_operation(ctx, extra_args):