{"id":17197664,"url":"https://github.com/ffoysal/kioshi","last_synced_at":"2026-02-18T02:35:22.160Z","repository":{"id":44134919,"uuid":"189816283","full_name":"ffoysal/kioshi","owner":"ffoysal","description":"Simple REST API using NodeJS, ExpressJS, MongoDB, deploy using Docker Compose, AWS using Terraform, Kubernetes on AWS using KOPS, K8s-Application","archived":false,"fork":false,"pushed_at":"2023-03-03T00:32:43.000Z","size":5116,"stargazers_count":1,"open_issues_count":16,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-30T13:00:44.759Z","etag":null,"topics":["aws","docker","docker-compose","expressjs","kubernetes-deployment","mongodb","mongoose","nodejs","rest-api","rest-cli","terraform"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ffoysal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-02T07:15:51.000Z","updated_at":"2022-05-07T03:00:45.000Z","dependencies_parsed_at":"2025-04-06T06:31:33.273Z","dependency_job_id":"677ca5b8-e550-456e-b514-cf4a8b95dc8b","html_url":"https://github.com/ffoysal/kioshi","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ffoysal/kioshi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ffoysal%2Fkioshi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ffoysal%2Fkioshi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ffoysal%2Fkioshi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ffoysal%2Fkioshi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ffoysal","download_url":"https://codeload.github.com/ffoysal/kioshi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ffoysal%2Fkioshi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29566402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T00:47:08.760Z","status":"online","status_checked_at":"2026-02-18T02:00:09.468Z","response_time":162,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","docker","docker-compose","expressjs","kubernetes-deployment","mongodb","mongoose","nodejs","rest-api","rest-cli","terraform"],"created_at":"2024-10-15T01:57:01.578Z","updated_at":"2026-02-18T02:35:22.138Z","avatar_url":"https://github.com/ffoysal.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CircleCI](https://circleci.com/gh/ffoysal/kioshi/tree/master.svg?style=svg)](https://circleci.com/gh/ffoysal/kioshi/tree/master)\n\n# Documentation Index\n\n- [Overview](#Overview)\n- [Api Architecture](#Architecture)\n- [Run app locally](#Run-locally)\n- [Run Test](#Run-Test)\n- [Sanity Test](#Sanity-for-Any-Deployment)\n- [Build Container \u0026 Run](#Build-Container)\n- [Run using docker-compose](#Run-using-docker-compose)\n- [Cloud Deployment](#Cloud-Deployments)\n  - [Kubernetes Deployment (kops)](#Kubernetes-with-kops)\n  - [Helm Deployment](#Helm-Deployment)\n  - [AWS Deployment (terraform)](#AWS-Terraform)\n- [CLI for API](#CLI-for-Api)\n- [K8s-Application](k8s-application/README.md)\n\n# Overview\n\nKioshi is a simple REST api which has only one purpose is to manage messages. The user will be able to create a message using `\u003curi\u003e/messages` endpoint and should get the details about the messages. Specifically if a message is palindrome or not. The app has followed RESTful design pattern. The design tries to comply with the HTTP code for various operations. The successful operations and returned HTTP code has been described into the following table\n\n| Operations | HTTP Verb | HTTP Returned Code | Comments |\n| ---------- | --------- | ------------------ | -------- |\n| Create message | POST `/messages` | 201 | request body `{\"message\":\"racecar\"}`, response body null, response header `Location:/messages/124fghk` |\n| Get a message details | GET `/messages/124fghk` | 200 | response body will have message details |\n| Update a message | PATCH `/messages/124fghk` | 204 | request body `{\"message\":\"kayak\"}`, no response body |\n| Delete a message | DELETE `/messages/124fghk` | 204 | no response body|\n| List messages | GET `/messages` | 200 | response has list of messages in the body|\n\nThe details api documentation would be found at the endpoint `\u003curi\u003e/docs`\n\n**CircleCi has been integrated and there is a `test` stage and code coverage report stored as artifact.**\n\n## Architecture\n\nThe api is implemented using NodeJS, ExpressJS, MongoDB. The high level architecture of the app is as follows\n\n![alt text](diagram/app.jpg)\n\n- **Router**: It is a expressjs component that routes to various controller method based on request path.\n- **Controller**: It is responsible to call proper service method and model based on the request\n- **Service**: All the business logics are implemented in here.\n- **Model**: Represents data model and handle database operations.\n\n### In this guide all the commands and implementations are done on ubuntu\n\n## Run locally\n\nTo run the app locally, pre-requisites\n\n- Install `NodeJS`\n- Install `npm`\n- Install `MongoDB` or use mongo db docker container `docker run -d -p 27017:27017 --name mongodb mongo:4.0.4`\n\n\n\nOnce the pre-requisites are done, follow the steps in order\n```\ngit clone https://github.com/ffoysal/kioshi.git\n```\n```\ncd kioshi/server\n```\n```\nnpm install\n```\nIt will download and install all the package dependency\n\n_Make sure mongodb is running in `localhost` at port `27017`. If the DB is running somewhere else then export env as_\n\n```\nexport MONGODB_URI=mongodb://\u003cDB-HOST\u003e:\u003cPORT\u003e/mms-db\n```\n\n```\nnpm start\n```\nIt will open the port `3000` on `localhost`\n\nFor server health status http://localhost:3000/health\n\nFor api docs http://localhost:3000/docs\n\nFor api operation http://localhost:3000/messages\n\n## Run Test\n\nThe test are written using `mocha`, `chai` and `supertest`  framework. During test app does not need real mongo db server instead it uses `mongodb-memory-server`.\n\nTo run the test \n\n```\ngit clone https://github.com/ffoysal/kioshi.git\ncd kioshi/server\n```\n```\nnpm test\n```\nIt will generate a mocha test report in console and generate a code coverage report using `nyc` framework.\n\n## Sanity for Any Deployment\n\nTo quickly verify if a deployment has done successfully a file called `sanity.js` is provided into `server` folder. After finishing the deployment change the `baseURL` variable in `sanity.js` file and run `mocha sanity.js` it will verify all the api operations. If `mocha` command not found, install it `npm install mocha -g`\n\n## Build Container\n\nIn order to deploy in the cloud easily a `Dockerfile` is provided to make docker container.\n\nTo build the container\n```\ngit clone https://github.com/ffoysal/kioshi.git\ncd kioshi\n```\n```\ndocker build . -t kioshi\n```\n\nIt will create a docker image named `kioshi`. This container can be run by passing mongo db url as environment like this\n\n```\ndocker run --rm -p 3000:3000 -e MONGODB_URI=mongodb://\u003cDB_HOST\u003e:27017/mms-db --name kioshi_app kioshi\n```\n\n_Note: change `DB_HOST` for your db._ DONT PUT `localhost` if your db is running in localhost. Instead use actual IP of the localhost as the app is running inside container.\n\n\nAccess the app\n\ndocumentation: http://localhost:3000/docs\n\nhealth check: http://localhost:3000/health\n\napi: http://localhost:3000/messages\n\n## Run using docker-compose\n\npre-requisites are\n\n- [docker](https://docs.docker.com/install/) must be installed\n- [docker-compose](https://docs.docker.com/compose/install/) must be installed\n\nFollow the steps in order\n\n```\ngit clone https://github.com/ffoysal/kioshi.git\n```\n```\ncd kioshi\n```\n```\ndocker-compose up\n```\n_It will download mongodb docker container and start it. The app container will be built and start the app container._\n\nThe app will be running at port `3000` on `localhost`\n\nFor server health status http://localhost:3000/health\n\nFor api docs http://localhost:3000/docs\n\nFor api operation http://localhost:3000/messages\n\n# Cloud Deployments\n\nTo make the cloud deployment easier the build system push the latest application docker image to docker hub. Have a look at the [Docker Registry](https://hub.docker.com/r/ffoysal/kioshi). Kubernetes or AWS ECS can easily pull the docker images from that pulic registry.\n\n## Kubernetes with kops\n\nWe will use `kops` to deploy kubernetes cluster in **AWS**. Assuming [kops](https://github.com/kubernetes/kops) has been installed on your development machine as well as `aws-cli` and `kubectl`.\n\n### Create an S3 bucket\n\nAs `kops` uses S3 bucket to store the state and configuration of your Kubernetes cluster:\n\n```\naws s3api create-bucket \\\n    --bucket kioshi-k8s-store \\\n    --region us-east-1\n```\n\n_This bucket name may not be available please replace your bucket name here._\n\n### Set environement vriables for easy life\n\n```\nexport NAME=kioshi.com.k8s.local\nexport KOPS_STATE_STORE=s3://kioshi-k8s-store\n```\n\n### Create Cluster Config\n\nThis will create cluster with micro instances. So production please follow the recomanded size in [here](https://github.com/kubernetes/kops)\n```\nkops create cluster \\\n  --name=${NAME} \\\n  --zones=us-east-1a \\\n  --node-count=2 \\\n  --node-size=t2.micro \\\n  --master-size=t2.micro\n```\n\n### Build the cluster\n\n```\nkops update cluster ${NAME} --yes\n```\nYou will see the output like this. But the cluster creation has not been completed yet.\n\n```\nCluster is starting.  It should be ready in a few minutes.\n```\n\n### Verify Cluster\n\nCluster creation will take couple of minitues. Validate if the cluster creation is done using the command\n```\nkops validate cluster\n```\nThe above command will produce all the node info as well as\n```\nYour cluster kioshi.com.k8s.local is ready\n```\n\n### Check all nodes are ready\n\n```\nkubectl get nodes\n```\nRunning the above command will produce something like\n```\nNAME                            STATUS   ROLES    AGE   VERSION\nip-172-20-37-130.ec2.internal   Ready    master   3h    v1.11.9\nip-172-20-40-220.ec2.internal   Ready    node     3h    v1.11.9\nip-172-20-52-48.ec2.internal    Ready    node     3h    v1.11.9\n```\nif not wait until output looks like that.\n\n### Deploy The Service\n\nTo checkout and deploy the service do the following commands in order\n```\ngit clone https://github.com/ffoysal/kioshi.git\n```\n```\ncd kioshi/kubernetes\n```\n```\nkubectl apply -f .\n```\n\nVerify if pods are in running state, if not pelase wait and check again\n```\nkubectl get pods\n```\nwill produce something like\n```\nNAME                                 READY   STATUS    RESTARTS   AGE\nkioshi-deployment-647558c554-5vvw8   1/1     Running   1          1h\nkioshi-deployment-647558c554-sd67m   1/1     Running   1          1h\nmongo-788bf5f674-2hmqh               1/1     Running   0          1h\n```\nDon't worry about `RESTART` colloumn. The app restart if db is not available. DB should be available eventually.\n\nTo list all the servicees please do\n```\nkubectl get service\n```\noutput will be\n```\napi     LoadBalancer   100.71.140.141   \u003curi\u003e.us-east-1.elb.amazonaws.com   80:31619/TCP   3h\nkubernetes   ClusterIP      100.64.0.1       \u003cnone\u003e                                                                    443/TCP        3h\nmongo        ClusterIP      100.68.179.157   \u003cnone\u003e                                                                    27017/TCP      1h\n```\nThe `api` service can be accessed by this url `\u003curi\u003e.us-east-1.elb.amazonaws.com`\n\nThe supported paths by the app are \n\nhealth check: `\u003curi\u003e.us-east-1.elb.amazonaws.com/health`\n\napi documentation: `\u003curi\u003e.us-east-1.elb.amazonaws.com/docs`\n\napi: `\u003curi\u003e.us-east-1.elb.amazonaws.com/messages`\n\n\nAll the supported operations and examples are provided in `/docs` path.\n\nThe api endpoint are in the path `/messages`\n\nTo verify the apis please use `curl` or `postman`\n\n_Note: `try out` button in swagger ui will not work for this deployment._\n\n### Delete Cluster\n\nTo cleanup, delete the kubernetes cluster\n```\nkops delete cluster --name=${NAME} --yes\n```\n\n## AWS Terraform\n\nThe high level architecture for AWS deployment is below. MongoDB container is running in EC2 instance and app container is running in ECS Fargate.\n![alt text](diagram/aws.jpg)\n\n_Note: for simplicity all security groups, target group, ECS service are not shown in the diagram_\n\nThe `terraform` code is written in the version of `0.11.7`. Please download the [terraform 0.11.7](https://releases.hashicorp.com/terraform/0.11.7/) for your OS. Assumming the AWS credentials are stored in `$HOME/.aws/credentials` with default profile. And the infrastructure will be created in `us-east-1` region.\n\nFollow the steps below in order to deploy the infrastructure in AWS.\n```\ngit clone https://github.com/ffoysal/kioshi.git\n```\n```\ncd kioshi/terraform\n```\n```\nterraform init\n```\n\n_Note: It will load all the terraform moudles._\n\n```\nterraform plan\n````\nit will show how many resources and what resources will be created. Currently 32 resources will be created. And the output for the above command will have something like this\n\n```\nPlan: 32 to add, 0 to change, 0 to destroy.\n```\n\n```\nterraform apply -auto-approve\n```\nit will start creating AWS resourcess. It will take couple of miniutes. When finished the last lines will be something like this\n```\nApply complete! Resources: 32 added, 0 changed, 0 destroyed.\n\nOutputs:\n\nalb = mms-kio-alb-124578.us-east-1.elb.amazonaws.com\n```\n\n_Note: for every deployment this number `124578` in the URL is different_\n\ngo to http://mms-kio-alb-124578.us-east-1.elb.amazonaws.com/health\nIt will return `503` as because MongoDB is running on EC2 instance which has not been ready state yet. Detail logs can be found at cloudwatch log group `mms-kio-ecs`. Wait 2/3 minutes the app will be ready.\n\n\nhealth check: http://mms-kio-alb-124578.us-east-1.elb.amazonaws.com/health\n\napi documentation: http://mms-kio-alb-124578.us-east-1.elb.amazonaws.com/docs\n\napi: http://mms-kio-alb-124578.us-east-1.elb.amazonaws.com/messages\n\nTo test REST api client tools would be [postman](https://www.getpostman.com/) or `curl` or use [mms-cli](#CLI-for-Api)\n\nTo cleanup the resources\n\n```\nterraform destroy -auto-approve\n```\n\nIt will take couple of miniutes to finish. It will delete all the resources created for the deployemnt.\n\n## Helm Deployment\n\nSetup kubernetes cluster by following [Kubernetes Deployment (kops)](#Kubernetes-with-kops). Dont use `kubectl` to deploy the pods.\n\nInstall [Helm](https://helm.sh/docs/using_helm/#installing-helm). I found this is enough for installation\n\n```\ncurl -LO https://git.io/get_helm.sh\nchmod 700 get_helm.sh\n./get_helm.sh\n```\n\nThe above script will take the latest helm and install it.\n\nverify helm is installed\n```\nhelm version\n```\n\nwill show output something like this\n\n```\nClient: \u0026version.Version{SemVer:\"v2.14.1\", GitCommit:\"5270352a09c7e8b6e8c9593002a73535276507c0\", GitTreeState:\"clean\"}\nServer: \u0026version.Version{SemVer:\"v2.14.1\", GitCommit:\"5270352a09c7e8b6e8c9593002a73535276507c0\", GitTreeState:\"clean\"}\n```\n_Note: `Server` will not be shown unless finish `helm init` first._\n\nSince we are using `KOPS` with `AWS` to create kubernetes cluster we need to setup a service account and associate that account with the cluster role `cluster-admin`  in the cluster for `tiller`.\n\n```\nkubectl create serviceaccount -n kube-system tiller\nkubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller\n```\n\nInitialize `helm` with the service account named `tiller`\n\n```\nhelm init --service-account tiller\n```\n\nNow verify helm again\n```\nhelm version\n```\n\nNow follow the steps to deploy this service\n\n```\ngit clone https://github.com/ffoysal/kioshi.git\ncd kioshi/helm\nhelm install mms/\n```\n\nFollow the on screen message for details after the above command.\n\nTo delete the service, first get the helm released name `helm list` then do `helm delete \u003cRELEAE_NAME\u003e`\n\n\n\n## CLI for Api\n\nA custom cli (`mms-cli`) tool has been implemented for this REST api. The `mms-cli` suppport operations (create, get, update, delete, list) and make api calls to the REST server. The cli tool is implemented using `go` and the code is located [here](./mms-cli).\n\nDownload the latest release of cli for your OS from [here](https://github.com/ffoysal/kioshi/releases)\n\n\n### Example CLI Run in Ubuntu\n\nDownload package for linux and extract it. There is an executable file `mms-cli_linux_amd64`\n\nFor easy to use rename file \n```\nmv mms-cli_linux_amd64 mms-cli\n```\nMake the file executable\n\n```\nchmod +x mms-cli\n```\nMove the file to `/usr/local/bin`\n```\nmv mms-cli /usr/local/bin\n```\n\nThe CLI tool help is self explenetory.\n\n`mms-cli` try to find api server from the environment variable `MMS_URI`. So running it without setting environment variable will show the output\n\n```\nPlease export the environment variable MMS_URI (.i.e. export MMS_URI=http://localhost:3000)\nIt is the URI where the REST api server is running\n```\nexport the environement variable \n```\nexport MMS_URI=http://localhost:300\n```\nassuming the api is running on local host.\nthen run \n```\nmms-cli\n```\nThe output will be like this\n```\n\n\tmms-cli is a client tool for rest api Message Management Service (mms).\n\tYou can create, get, delete, update, list messages.\n\nUsage:\n  mms-cli [command]\n\nAvailable Commands:\n  create      Create a message\n  delete      Delete a message\n  get         Get a message details\n  help        Help about any command\n  list        List all the message\n  update      Update a message\n\nFlags:\n  -h, --help   help for mms-cli\n\nUse \"mms-cli [command] --help\" for more information about a command.\n```\n\n# Issues/Comments/Suggestions\n\nif you find an issues or have any question, comments, suggestions please create an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fffoysal%2Fkioshi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fffoysal%2Fkioshi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fffoysal%2Fkioshi/lists"}