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)
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.
- Make sure you have sbt and java 17 installed the type
sbt run
on commandline and open http://localhost:8080/docs/ on your browser
- To build the fat jar using sbt assembly simply run the command
sbt build
with your desired configurations set up inapplication.conf
- To build the docker image simply run
sbt build-docker
with your desired configurations set up inapplication.conf
. Make sure you change the docker user inbuild.sbt
- 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
- 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
- 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.
This project is open to contributions be it through issues or pull request. Have a look at our contribution guide
before you get started.
MIT