Hiis ZIO API seed project

Description

This is a seed template for scala microservice applications. This should serve as a base template for most if not all scala microservice applications at hiis. It made up of the following main components

ZIO (zio, zio-http, etc)
Authentication and authorization
Docker build
Sbt Mdoc for documentation
Scala formatting (scalafix, scalafmt)

Structure

This structure is standard across most microservice code bases at Hiis and should be maintained if possible.

docs contains the project documentation and should be regularly updated.
zio-microservice-docs contains the project generated docs (such as scala docs) and website contains entire documentation static site. See mdoc and mdoc with docusaurus to learn more.
modules/core should contain all core project components such as models and common code.
modules/application should contain the main zio application.
modules/it should contain the integration test code for the main application.
Dockerfile contains build information on how to build the docker image based on the application.

How to run

Make sure you have sbt and java 17 installed the type sbt run on commandline and open http://localhost:8080/docs/ on your browser

Building application (SBT assembly & Docker)

To build the fat jar using sbt assembly simply run the command sbt build with your desired configurations set up in application.conf
To build the docker image simply run sbt build-docker with your desired configurations set up in application.conf. Make sure you change the docker user in build.sbt

How to build jar file

run sbt build the jar file will be created and located in modules/application/target/scala-2.13/zio-microservice-seed.jar
This jar file can be executed on any java platform running java 17

How to run the jar file

run java -jar /modules/application/target/scala-2.13/zio-microservice-seed.jar and open the browser at http://localhost:8080/docs

Deploy to Render

Create a Git repository on Github for the project
Create an account on Render. Link your Render account to your Github account.
Build the jar file using the command specified above. Then copy the jar file from ./modules/application/target/scala-2.13/zio-microservice-seed.jar to ./dist/zio-microservice-seed.jar
Push it to your git repository
Create a new web service on Render and select the repository
Add an environment variable called PORT with value 8080.

Deploy on Fly(Preferred)

Signup on Fly and download Flyctl(Command line tool)
In the projects root directory run flyctl auth login to login
Run fly launch to generate the fly.toml file. See https://fly.io/docs/languages-and-frameworks/dockerfile/
Run fly deploy to deploy the project. Wait for the deployment to complete this will take a while

Development

Clone the project
Make sure you have sbt installed in your computer.
Import the project in your preferred sbt supported IDE (we recommend Intellij Idea, the community version will suffice)
Make sure all external dependencies are up and running (See External dependencies section above)
Start coding and testing.
Pull request are welcomed.

Contributing

This project is open to contributions be it through issues or pull request. Have a look at our contribution guide before you get started.

License

MIT

icemc / shipping-api