README.md

ZIO Blog App

A sample full-stack application written with ZIO 2, Scala 3 and ScalaJS/Laminar. This project is used to explore the development experience of using Scala 3 for the full stack and deploying to Kubernetes.

• Original repo: https://github.com/zio/zio-petclinic (Scala 2)
• Original video: https://www.youtube.com/watch?v=3lopiYfWmdQ (Awesome!)
• Then updated to Scala 3: https://github.com/kyledinh/zio-petclinic-scala-3 (blogapp branch) then used as template to create this Blog App
• Here's the Onboarding Video, but at 5 minutes in, it shows what the app does: https://youtu.be/GnQqMgYiG3E?t=287

Changes from the original repo with:

• Update from Scala 2 to Scala 3.2.2
• Docker for Postgres Database
• Backend API for Blog App
• Frontend with Scala.js/Laminar (Apply a different predesigned theme)
• Use a standard Bootstrap 5 theme
• Update Tests
• Developer Tools/Guides
• Deploy with Kubernetes
• Build pipeline
• Metrics

---

Table of Contents

• About this project
• Quick Guide to localdev
• Developer Guide
  • Onboarding Guide | Onboarding Video
  • Build Kubernetes Guide | Build Kubernetes Video
  • Backend Guide
  • Frontend Guide
  • Troubleshooting Guide
• Architecture Guide
• Markdown Guide

---

Software Versions

Software	Version	Install
JVM	openjdk 17.0.4	https://sdkman.io/install
Scala	3.2.2	https://www.scala-lang.org/download
sbt	1.8.2	https://www.scala-sbt.org/download.html
Zio	2.0.2	https://zio.dev/getting_started
ScalaJS	1.13.1	https://www.scala-js.org/
Laminar	15.0.1	https://laminar.dev/
Postgres	14	https://hub.docker.com/_/postgres
Docker Desktop	4.3.x	https://www.docker.com/products/docker-desktop

---

Quick Guide to localdev with Docker

Requires Docker to be running

Setup

• make check
• make setup

Run the local database, start backend server in Terminal 1

Start the database

• make postgres-up
• make postgres-init-migrate (do this only on first time to seed the database)
• make postgres-down (to stop and remove the database container)

To run the backend API server (With sbt server)

• make backend-compile
• make backend-up

Run the frontend in a separate Terminal 2

• make frontend-up
• make frontend-compile (once up, just recompile and vite will reload the webpage)
• open http://localhost:3000

Check processes that are running

• make status (see that the SBT Server is running)
• make postgres-check (see what's in the database)

Port number for services

Service	Default Port	Environment Var	Usage
frontend	:3000		http://localhost:3000/
backend	:4000	BLOGAPPBACKEND_PORT	http://localhost:4000/scrawls
postgres	:5432	DATABASE_URL	postgres://$username:$password@$host:$port/$dbname

---

Deploy to Kubernetes Cluster

This project example will use the my Docker Hub public account at https://hub.docker.com/u/kyledinh

Build the Docker images

• make docker-build - builds the backend and frontend images
• make docker-push - customize your DOCKER_HUB_REPO in Makefile to you account
• View the Docker Hub Repo

Setup for Kubernetes Local Stack

• cd kubernetes change directory to work with the desktop-demo.sh which is a safe script, designed to work ONLY with the desktop context in the demo namespace
• ./desktop-demo.sh init will create the demo namespace
• ./desktop-demo.sh up will create/update the deployments to the desktop Kubernetes Cluster
• ./desktop-demo.sh init-db will perform the initial database migration to the postgres container

Command to View/Edit the Kubernetes Stack

• ./desktop-demo.sh info will get you info on the environment and all deployed service, pods, config maps, etc...
• ./desktop-demo.sh log <search-pattern> will find the pod by search pattern and print the log
• ./desktop-demo.sh ex <search-pattern> will start a bash session for a pod that matches the search pattern

---

Check the Postgres DB in the Docker container

• use: make postgres-check

---

Screenshots

using the Simplex Bootstrap Theme:

Or you can view screenshots with the custom Medio CSS theme, this version is preserved in the "medio" branch:

• Board Page Screenshot
• People Page Screenshot
• Medio Page Screenshot

---

Project Outline

A good starting point to understand this repo is with the Makefile. It will have the most common commands to check, setup, compile and build the project.

.
├── LICENSE
├── Makefile                   Commands to build/develop this project 
├── README.md
├── backend                    Scala code for RESTful api 
│   └── src
│       ├── main
│       └── test
│
├── build.sbt                  Dependency manager 
├── docker                     Scripts to build Docker images 
├── docker_pg_vol              Docker volume for Postgres DB
├── frontend                   Scala code that generates `main.js` for the webserver
│   ├── src
│   │   └── main
│   └── target
│       └── scala-3.1.3        main.js will be generated here
│
├── html                      Javasript webserver using vite/Node
│   ├── index.html
│   ├── main.js
│   ├── main.scss
│   ├── medio/                 CSS/JS UI Template folder, "Medio" custom theme
│   ├── node_modules/
│   ├── package.json
│   ├── postcss.config.js
│   ├── simplex/               CSS/JS UI Template folder, "Simplex" Bootstrap theme
│   ├── tailwind.config.js
│   ├── vite.config.js
│   └── yarn.lock
│
├── kubernetes                 Files to deploy to Kube Cluster (locally) 
├── project                    The only project directory to be concerned with
│   ├── build.properties       sbt version  
│   └── plugins.sbt            plugins
│
├── sem-version                x.x.x
└── shared                     Scala code shared by backend and frontend, models 
    └── src
        ├── main
        └── test

Response HTML Tempate

• Simplex Bootstrap 5 Them - from Bootswatch
• Medio - from Untree.co