Skip to content

tutorial-first-app.md

Latest commit

 

History

History
140 lines (100 loc) · 4.11 KB

tutorial-first-app.md

File metadata and controls

140 lines (100 loc) · 4.11 KB
Raw

Tutorial: Your First App

This tutorial starts with the shortest route to a real application response, then shows the build/push/deploy loop that fog demo automates. It uses the included examples/sample-app and repo-local client state; it does not need host Kubernetes or AWS configuration.

Before starting, complete Install. The demo needs Docker Desktop, kind, kubectl, helm, and curl.

1. Initialize And Diagnose

From the fogstack repository:

./engine/fog init
./engine/fog doctor

fog init is no-clobber: it leaves an existing .env unchanged. The demo defaults to the minimal profile and invokes stack startup itself, so you do not need to call fog up separately.

2. Get The First Response

./engine/fog demo

The command builds and pushes the sample image, deploys its Helm chart idempotently, starting or reusing the selected stack first. It waits for readiness, then prints a reachable local URL and the verified response. A healthy run contains:

fogstack-sample-ok

Running fog demo again updates/reuses the same release. To exercise the same app while the full profile is active, use ./engine/fog demo --profile full.

3. Inspect What Is Running

First preview the endpoint exports, then import them into this shell:

./engine/fog endpoints
eval "$(./engine/fog endpoints)"
./engine/fog status
kubectl --kubeconfig "$KUBECONFIG" --context "$KUBE_CONTEXT" get pods,svc

When no --profile is given, status and endpoints use the last-started profile. The exported values are scoped to this terminal and should not be added to a global shell profile.

4. Understand The Manual Inner Loop

The demo automates these same steps. Build and push a new image tag:

docker build -t "$REGISTRY/sample-app:0.1.1" examples/sample-app
docker push "$REGISTRY/sample-app:0.1.1"

Upgrade the existing release:

helm upgrade --install sample-app examples/sample-app/chart \
  --kubeconfig "$KUBECONFIG" \
  --kube-context "$KUBE_CONTEXT" \
  --set "image.repository=$REGISTRY/sample-app" \
  --set image.tag=0.1.1 \
  --wait --timeout 180s

Use the URL printed by fog demo to curl the updated app. This is the local inner loop: edit, build, push, upgrade, verify.

5. Try The Backing Services

Postgres is available through the exported URL:

psql "$POSTGRES_URL" -c 'SELECT version();'

If psql is not installed, use the container client:

docker exec fogstack-postgres psql -U fogstack -d appdb -c 'SELECT version();'
docker exec fogstack-redis redis-cli ping

Pods can reach the same services at fogstack-postgres:5432 and fogstack-redis:6379 on the kind Docker network.

6. Swap In Your App

  1. Build and push "$REGISTRY/<your-app>:<tag>".
  2. Point your chart at that repository and tag.
  3. Use Service type LoadBalancer for a controller-provided local endpoint, or ClusterIP with kubectl port-forward for direct development.

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

Optional: Full-Tour Integration App

The full-tour Go app talks to Postgres, Redis, S3 through the AWS-compatible API, and OpenSearch from inside the cluster. It tests integration wiring, not AWS security or production parity.

./engine/fog up --profile full
./engine/fog demo --profile full
eval "$(./engine/fog endpoints)"

For its build/deploy details, inspect examples/full-tour and use the full-profile clean-room smoke journey. AWS CLI is required for the standalone recipes in AWS Recipes, not for minimal startup.

Clean Up Safely

Remove only the sample Helm release:

helm uninstall sample-app --kubeconfig "$KUBECONFIG" --kube-context "$KUBE_CONTEXT"

Or stop fogstack while keeping named data volumes:

./engine/fog down

Only use ./engine/fog down --volumes --yes after inspecting or backing up data; it permanently removes fogstack's Postgres, Redis, emulator, and OpenSearch volumes. See the Runbook for the safe recovery ladder.