fogstack

English · Tiếng Việt

fogstack is a host-isolated local app-run harness for personal projects. The default profile runs a real Kubernetes cluster, OCI registry, Postgres, and Redis on your machine. The full profile adds a Floci-backed AWS-compatible API and OpenSearch when an application needs those integrations.

It is one local application environment, not a miniature AWS account. Runtime stays in Docker and generated client configuration stays inside this repository, away from company Kubernetes contexts and real AWS credentials.

Quickstart

fogstack v0.1.0 is developed and tested on macOS with Docker Desktop. Give the Docker VM at least 8 GB of memory. The first app path needs Docker Desktop, kind, kubectl, helm, and curl; follow the copy/paste instructions in the installation guide before continuing.

git clone https://github.com/vankhaivn/fogstack.git
cd fogstack
./engine/fog init
./engine/fog doctor
./engine/fog demo

fog init creates .env only when it does not already exist. fog demo starts or reuses the stack, builds, pushes, and deploys the included sample app, then prints the working local URL and a response containing fogstack-sample-ok.

The default minimal profile is enough for this path. When you need the AWS-compatible API or OpenSearch, start the full profile instead:

./engine/fog demo --profile full

Use The Endpoints

Preview the exact values before importing them into your current shell:

./engine/fog endpoints
eval "$(./engine/fog endpoints)"

After a full-profile start, fog endpoints and fog status use the last-started profile by default. You can still select one explicitly with --profile.

kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" get pods -A
psql "$POSTGRES_URL"
docker build -t "$REGISTRY/my-app:dev" .
docker push "$REGISTRY/my-app:dev"

Profiles And Tools

Capability	Starts or does	Host tools
minimal runtime	kind, registry, Postgres, Redis, local load balancing	Docker Desktop, kind, kubectl, curl
full runtime	everything above plus Floci, OpenSearch, and Dashboards	same runtime tools; more Docker memory is helpful
fog demo	builds and deploys the sample app	runtime tools plus helm
Terraform workflow	writes a local AWS-provider override	terraform; full profile for AWS calls
AWS recipes	calls the local AWS-compatible endpoint	AWS CLI; full profile
contributor verification	deterministic repository checks	use checks/verify.sh and the pinned toolbox

fog up defaults to minimal. Helm, Terraform, and the AWS CLI are checked when their capability needs them; they do not block a minimal runtime startup.

Connect Your Project

Terraform overrides are no-clobber by default:

./engine/fog tf-init ../my-app/terraform

If fogstack_override.tf already exists, review it and opt into replacement with --force. Do not commit the generated local override to another project.

AWS CLI and SDK calls must always receive the local endpoint explicitly:

./engine/fog up --profile full
eval "$(./engine/fog endpoints)"
aws --endpoint-url "$AWS_ENDPOINT_URL" s3 ls

See Connect Your Project for Kubernetes, Helm, Terraform, SDK, Postgres, Redis, and registry examples.

Stop Without Losing Data

./engine/fog down

This removes the cluster and runtime containers but keeps named data volumes. A clean reset is intentionally explicit and destructive:

./engine/fog down --volumes --yes

That command permanently removes fogstack Postgres, Redis, emulator, and OpenSearch data. Inspect or back up first. checks/verify.sh is the safe default project check; checks/smoke.sh is a clean-room runtime test that refuses to run over pre-existing fogstack resources.

Endpoint Contract

Endpoint	Profile	Role	Backend
KUBECONFIG=<repo>/.state/kubeconfig.yaml	minimal, full	Kubernetes deployment target	kind + cloud-provider-kind
localhost:5001	minimal, full	OCI image push/pull loop	registry
localhost:5432	minimal, full	database	Postgres
localhost:6379	minimal, full	cache	Redis
http://localhost:4566	full	AWS-compatible API plane	Floci
http://localhost:9200	full	search API	OpenSearch
http://localhost:5601	full	search dashboard	OpenSearch Dashboards

All host ports bind to 127.0.0.1. fogstack points Kubernetes and AWS clients at files under .state/, exports fake local AWS credentials for its process, and never needs ~/.kube or ~/.aws.

Documentation

Start with the documentation map, or jump directly to:

• Install — supported platform, required tools, and remediation.
• Your First App — the demo path and the manual inner loop.
• Architecture — components, lifecycle, and host isolation.
• Interactive architecture: English · Tiếng Việt — download or open the tracked HTML file locally.
• Runbook and Troubleshooting — safe daily operation and recovery.
• Reference — commands, variables, ports, containers, and volumes.
• Contributing, Security, and Changelog.

Limits

VPC and security-group APIs can help exercise create/read/update/delete wiring, but they do not enforce real network policy. IAM is not a real authorization boundary. The AWS-compatible emulator can change faster than AWS itself.

Do not use fogstack as a production-parity or security-validation environment. It is for local feedback, integration wiring, and learning AWS-adjacent workflows without touching a real account.

License And Credits

fogstack is released under the MIT License.

Credits: Floci, kind, cloud-provider-kind, OpenSearch, PostgreSQL, Redis, Terraform, Helm, kubectl, Docker, ShellCheck, and Hadolint.