From bc79f4d6a95c2a2fdb1a521987c7cc9893bdea9f Mon Sep 17 00:00:00 2001 From: Thomas E Lackey Date: Fri, 2 May 2025 12:50:27 -0500 Subject: [PATCH 1/2] Refresh docs --- README.md | 84 +++++++++++++++++++++---- docs/cli.md | 122 +++++++++++++++++++++++++++++++++---- docs/webapp.md | 14 ++--- src/stack/deploy/deploy.py | 3 +- src/stack/util.py | 4 +- 5 files changed, 191 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 25650d3..66ef728 100644 --- a/README.md +++ b/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 \ No newline at end of file diff --git a/docs/cli.md b/docs/cli.md index f7e264b..8ddede5 100644 --- a/docs/cli.md +++ b/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 +$ 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 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 --force-rebuild +$ stack manage --dir ~/deployments/todo exec frontend 'node --version' ``` \ No newline at end of file diff --git a/docs/webapp.md b/docs/webapp.md index e6e61ff..e1c58d8 100644 --- a/docs/webapp.md +++ b/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 ``` diff --git a/src/stack/deploy/deploy.py b/src/stack/deploy/deploy.py index bef54fc..582b36c 100644 --- a/src/stack/deploy/deploy.py +++ b/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): diff --git a/src/stack/util.py b/src/stack/util.py index 5d724fe..75d990e 100644 --- a/src/stack/util.py +++ b/src/stack/util.py @@ -34,10 +34,10 @@ def include_exclude_check(s, include, exclude): return True if include is not None: include_list = include.split(",") - return s in include_list + return s.name in include_list if exclude is not None: exclude_list = exclude.split(",") - return s not in exclude_list + return s.name not in exclude_list def get_stack_path(stack): From 99f69047b376490fba02aa93be8af01dc61ebf90 Mon Sep 17 00:00:00 2001 From: Thomas E Lackey Date: Fri, 2 May 2025 12:53:36 -0500 Subject: [PATCH 2/2] Leave as string --- src/stack/build/prepare_containers.py | 2 +- src/stack/util.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/stack/build/prepare_containers.py b/src/stack/build/prepare_containers.py index 29fa502..55a4032 100644 --- a/src/stack/build/prepare_containers.py +++ b/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(): diff --git a/src/stack/util.py b/src/stack/util.py index 75d990e..5d724fe 100644 --- a/src/stack/util.py +++ b/src/stack/util.py @@ -34,10 +34,10 @@ def include_exclude_check(s, include, exclude): return True if include is not None: include_list = include.split(",") - return s.name in include_list + return s in include_list if exclude is not None: exclude_list = exclude.split(",") - return s.name not in exclude_list + return s not in exclude_list def get_stack_path(stack):