cloud-native-app

Cloud Native App

Cloud Native App automates the process of bootstrapping a repository. It generates a project structure with everything you need to start coding right away.

Features

• Project Scaffolding — Generates complete project structure with hexagonal architecture
• OIDC Authentication — Pre-configured OpenID Connect setup with Keycloak
• HTMX-Ready Templates — Server-rendered HTML with HTMX for interactivity
• Event-Driven Architecture — Kafka integration for messaging between services
• Testing Infrastructure — Test setup with assertion helpers and testdata patterns
• CI/CD Ready — GitHub Actions workflows and Justfile task runner

Technologies Used

• Go — Primary programming language
• HTMX — Frontend interactivity without JavaScript frameworks
• Keycloak — Identity and access management (OIDC)
• Apache Kafka — Event streaming platform
• cloud-native-utils — Shared utilities library
• Just — Command runner for development tasks

Project Motivation

The motivation behind Cloud Native App is to provide a practical example of implementing a cloud-native application that adheres to best practices. The project aims to:

1. Automate the process of setting up a new repository.
2. Provide a project structure that follows best practices.
3. Offer a reference implementation for features like CI/CD, testing, and documentation.
4. Inspire developers to adopt cloud-native patterns in their projects.

Project Setup and Run Instructions

Follow these steps to set up and run the Cloud Native App:

Prerequisites

1. Install the latest version of Go.
2. Install the latest version of Just.
3. Include $HOME/bin in your $PATH.

Installation

Clone the repository and install the cloud-native-app binary into $HOME/bin:

just install

Usage

Change to your target directory and create a new demo module:

cloud-native-app demo

Navigate into the newly created demo directory and start the HTTP service on port 8080:

cd demo
just run-service

Start Kafka and Keycloak

Start Kafka and Keycloak on your local machine by running the following commands:

podman run --restart=always --name keycloak -d -p 127.0.0.1:8180:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.3.4 start-dev
podman run  --restart=always --name kafka -d -p 127.0.0.1:9092:9092 apache/kafka:latest

Setup Keycloak

We need to configure Keycloak to work with our application. Follow these steps:

1. Open the Keycloak admin console in your browser: http://localhost:8180/auth/admin
2. Log in with the admin credentials you provided during the Keycloak setup.
3. Create a new realm local for your application.
4. Create a new client demo for your application.
5. Set the redirect URI to http://localhost:8080/auth/callback.
6. Configure the client to use the appropriate authentication flow and scopes.
7. Create new credentials (client_id, client_secret) for the client.
8. Create a new user test with name test test for your application.
9. Create a password for the user test.
10. Replace the OIDC configuration to use the credentials from Keycloak.

OIDC_CLIENT_ID="demo"
OIDC_CLIENT_SECRET="8d6Gb5ZDNY2qlvFxCRNmPh3gozKtidRQ"

Visit the UI

Open the UI in your browser:

http://localhost:8080/ui

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License — see the LICENSE file for details.