Skip to content

USAGE.md

Latest commit

 

History

History
143 lines (114 loc) · 4.69 KB

USAGE.md

File metadata and controls

143 lines (114 loc) · 4.69 KB

spelltext - usage

requirements:

  • go >=1.23.0 toolchain
  • docker 28.3.2 (tested on build rev. 578ccf6)
  • helm 3.19.0 (goVersion: 1.24.7)
  • (opt) minikube 1.35.0 (compatible with 1.33.0)

contents

client

(as of 25th sept.): to run a single client, simply run:

$ set CLIENT_USERNAME=john_doe

$ cd $PROJECT_DIR/client
$ go run client.go --username=$CLIENT_USERNAME

server

configuration

the spelltext server apps provide a way to be configured via the YAML configuration file, found here. if you wish to have two separate configurations (e.g. config.dev.yml, config.prod.yml), you can do so as such:

  1. create your configuration file (e.g. config.new.yml):
$ cd $PROJECT_ROOT
$ export $CONFIG_FILE=config.new.yml
$ touch $CONFIG_FILE
  1. edit the Dockerfiles:
# change this
ENV CONFIG_FILE=./config.yml

# to this:
ENV CONFIG_FILE=./config.new.yml

docker

using the composefile you can seamlessly deploy a simple service composition:

# navigate to project root dir
$ cd $PROJECT_ROOT

# start up `docker compose`
$ docker compose up --watch --force-recreate --build 

# ...
$ docker compose logs --follow # or simply -f

# make sure to docker compose down (can cause duplicated stdout if not done)
$ docker compose down -v --remove-orphans

kubernetes

deployed using the provided charts in the repo and hosted packages.

# start up minikube (or k3s, microk8s, gke, ...)
$ minikube start

# navigate to project root dir
$ cd $PROJECT_ROOT

$ helm install spelltext k8s/spelltext -f k8s/spelltext/values.yaml -n spelltext --create-namespace 

# (confirm) set current kubectl namespace to 'spelltext'
$ kubectl config set-context --current --namespace=spelltext

# for local development, port-forward nats from inside the cluster, since client requires direct connection
$ kubectl port-forward pods/spelltext-nats 4222:4222 # keep the terminal open

# tunnel to your kubernetes control node (minikube in this example)
$ minikube tunnel # keep the terminal open

example - accessing pods/servers

  • via exposing service external-ip and minikube tunnel:
# start the tunnel
$ minikube tunnel

# select the service you want to dial 
# use chart/templates/TEMPLATE.yaml:.spec.selector.matchLabels.app, e.g. 'chatserver'
$ export SERVICE_NAME=chatserver

$ kubectl get deployments $SERVICE_NAME
> NAME         READY   UP-TO-DATE   AVAILABLE   AGE
> chatserver   2/2     2            2           7m54s

# expose the deployment via a loadbalancer
$ kubectl expose deployment chatserver --type=LoadBalancer --name=chatserver-lb

# external-ip is displayed now, with the help of 'minikube tunnel' command
$ kubectl get svc
> NAME            TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)           AGE
> chatserver      ClusterIP      10.106.245.161   <none>          50051/TCP         16m
> chatserver-lb   LoadBalancer   10.108.13.46     10.96.184.178   50051:32671/TCP   4m33s

example - cleaning up

cleanup:

$ helm uninstall spelltext
$ kubectl delete ns spelltext

# remove persistent volumes via kubectl 
$ kubectl get pv
# WARNING: only use '--all' when it is safe to do so
$ kubectl delete pv <pv-name>

# terminate the nats port-forward terminal
# terminate the minikube tunnel terminal
$ minikube stop

logs (grafana/promtail/loki)

grafana is configured to be accessed via NodePort by default, however you will still need to access it somehow (using minikube):

$ kubectl get svc
# NAME                                          TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)             AGE
# spelltext-grafana                             NodePort       10.100.152.148   <none>        80:31934/TCP        5m39s

$ minikube tunnel
$ minikube service spelltext-grafana --namespace=spelltext

# get grafana auth credentials:
$ kubectl get secret
# NAME                                 TYPE                 DATA   AGE
# spelltext-grafana                    Opaque               3      6m58s

$ kubectl get secret spelltext-grafana -o jsonpath="{.data.admin-user}" | base64 --decode # should always be 'admin'

$ kubectl get secret spelltext-grafana -o jsonpath="{.data.admin-password}" | base64 --decode