hatsuportal

Development environment installation (Windows)

• Install Git for windows (https://gitforwindows.org/)
  • use recommended options during installation
• Install docker (https://www.docker.com/get-docker)
  • You'll need to create a Docker ID
• Install node and npm for windows (https://nodejs.org/en/download/current/)
  • Take current version, not the LTS
• Install yarn for windows (https://yarnpkg.com/lang/en/docs/install/#windows-stable)
  • Take latest version
• Install Visual Code Studio (https://code.visualstudio.com/download)
  • Install plugin TSLint https://marketplace.visualstudio.com/items?itemName=eg2.tslint
  • Set your VSCode settings to "tslint.autoFixOnSave": true and "editor.formatOnSave": true
  • Please also use "editor.tabSize": 2 and "editor.detectIndentation": false to always force indentation with 2 spaces

Running development environment

• Navigate to project root
• Run sh install.sh (installs node packages for all projects, needed so that volume mount won't override projects and delete node_modules folders and runs docker-compose up)
• (on windows run docker-volume-watcher, see http://blog.subjectify.us/miscellaneous/2017/04/24/docker-for-windows-watch-bindings.html for more info)
• http://localhost/docs/ should now answer with swagger documentation
• http://localhost:8080/ should now answer with PostgreSQL Adminer. (see credentials from docker-compose.yml)
• http://localhost should now answer with React UI
• DISCLAIMER: note that in the API project, nodemon only updates dependency changes trough the ./src/server.ts inclusion hierarchy (see nodemon.json file), but does not run for example commands like tsoa swagger or tsoa routes. To make sure all changes are deployed to server, run yarn build, docker-compose down and finally docker-compose up to generate all files and deploy them to the server.

Destroying development environment

• Navigate to project root
• Run sh uninstall.sh (removes node_modules folders, kills and destroys all docker containers, deletes all images and removes all not used volumes.
• DISLAIMER: If you have other docker projects on your machine, this will destroy them too!!

Using SwaggerUI

• Navigate to http://localhost/docs/
• Open any of the API descriptions and press the Try it out button on the right side.
• SwaggerUI will generate a placeholder request for you. Pressing the Execute button will send the request.
• Some of the API requests require a Json Web Token https://jwt.io/ and will respond with 401 Unauthorized without a proper jwt in the client cookies.
• Login to the application using the login POST request (find it in the API listing under Auth)
• Both test users jykajee and Mister Thane use the password root
• Login response will set a cookie named token which then will be be sent to server on all subsequent requests
• Use logout POST request (also under Auth) to remove the cookie

Docker cheatsheet

• docker ps lists all running docker containers
• docker image ls lists all downloaded images
• docker volume ls lists all the volumes
• docker rm <container id> deletes a container
• docker rmi <image id> deletes an image
• docker kill $(docker ps -q) kills all running containers
• docker rm $(docker ps -a -q) deletes all stopped containers
• docker rmi $(docker images -q) deletes all images
• docker volume prune removes all dangling volumes
• docker build -t <friendlyname> builds a docker image with specified name
• docker run -p <hostport>:<containerport> <friendlyname> run a docker image and publish a port to host
• docker stop <container ID> stops the container (find the id with docker ps)
• docker exec -it <container ID> /bin/bash
  • or for windows with git bash you need to start the container with winpty docker run -p <hostport>:<containerport> <friendlyname> and then access using winpty docker exec -it <container ID> bash (more information here https://willi.am/blog/2016/08/08/docker-for-windows-interactive-sessions-in-mintty-git-bash/)
• docker-compose up -d starts the containers and detaches from run command after finished
  • on windows, remember to share the drive that you are developing on, with docker
• docker-compose down stops all running containers
• docker-compose restart <worker> restarts a single container within docker-compose

Troubleshooting

$ docker-volume-watcher
WARNING:root:No mounts match container name pattern * and host directory pattern *

• SOLUTION: you have not started docker-compose with docker-compose up