https://github.com/detivenc/ktortemplatedockerized

A simple web service template for creating an Ktor+PostgreSQL+Docker+JWT app
https://github.com/detivenc/ktortemplatedockerized

docker exposed jwt kotlin ktor kubernetes

Last synced: about 2 months ago
JSON representation

A simple web service template for creating an Ktor+PostgreSQL+Docker+JWT app

• Host: GitHub
• URL: https://github.com/detivenc/ktortemplatedockerized
• Owner: detivenc
• License: mit
• Created: 2024-03-11T21:16:35.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2026-04-23T19:23:15.000Z (about 2 months ago)
• Last Synced: 2026-04-23T21:24:52.884Z (about 2 months ago)
• Topics: docker, exposed, jwt, kotlin, ktor, kubernetes
• Language: Kotlin
• Homepage:
• Size: 2.11 MB
• Stars: 1
• Watchers: 1
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  

    

  



Ktor Template Dockerized




  Plantilla profesional de Ktor lista para producción con Docker, Kubernetes e integración de IA.





  

  

  

  



---

## 🚀 Descripción General

Esta plantilla proporciona una base sólida y escalable para construir backends modernos utilizando **Ktor**. Está diseñada con un enfoque "listo para producción", incluyendo contenerización, integración con bases de datos, seguridad JWT y soporte experimental para agentes de IA mediante **Koog**.

El proyecto utiliza **Amper**, la herramienta de construcción simplificada de JetBrains, para una experiencia de configuración más limpia en comparación con los setups tradicionales de Gradle.

### ✨ Características Principales

- ⚡ **Ktor 3.4.0**: Framework web asíncrono de alto rendimiento para Kotlin.

- 📦 **Docker & Compose**: Contenerización fluida y entorno de desarrollo local listo.

- 🎡 **Helm**: Gestión de despliegues simplificada mediante charts de Helm para Kubernetes.

- 🗄️ **Exposed 1.1.1**: Framework SQL de tipado seguro para Kotlin.

- 🔐 **Seguridad JWT**: Endpoints protegidos mediante autenticación JWT.

- 🤖 **Integración de IA**: Soporte integrado para agentes de IA utilizando la librería Koog.

- 🛠️ **Sistema de Construcción Amper**: Configuración basada en YAML para dependencias y builds.

---

## 📁 Estructura del Proyecto

```text

├── .github/workflows   # Pipelines de CI/CD

├── gradle/             # Catálogo de versiones (libs.versions.toml)

├── ktortemplatedockerized-chart/ # Chart de Helm para despliegue

├── src/

│   ├── Application.kt  # Punto de entrada de la aplicación

│   └── plugins/        # Configuraciones de características de Ktor

│       ├── AI.kt       # Configuración de Agentes de IA

│       ├── Databases.kt# Configuración de Exposed & PostgreSQL

│       ├── Routing.kt  # Definición de endpoints de la API

│       ├── Security.kt # Configuración de JWT & Autenticación

│       └── ...

├── module.yaml         # Configuración de construcción de Amper

├── Dockerfile          # Build optimizado multi-etapa

└── docker-compose.yaml # Stack de desarrollo local

```

---

## 🛠️ Comenzando

### Requisitos Previos

- **JDK 21+**

- **Docker & Docker Compose**

- **Amper** (Incluido mediante el wrapper `./amper`)

### Instalación y Ejecución

1. **Clonar el repositorio:**

   ```bash

   git clone https://github.com/DeTiveNC/ktortemplatedockerized.git

   cd ktortemplatedockerized

   ```

2. **Ejecutar localmente (Desarrollo):**

   ```bash

   ./amper run

   ```

3. **Ejecutar con Docker Compose:**

   ```bash

   docker-compose up --build

   ```

---

## 🔒 Seguridad y Configuración

La aplicación se configura a través de `resources/application.yaml` y variables de entorno.

| Variable      | Descripción                      | Valor por Defecto                           |

|---------------|----------------------------------|---------------------------------------------|

| `DB_URL`      | URL de conexión JDBC             | `jdbc:postgresql://localhost:5432/postgres` |

| `DB_USERNAME` | Usuario de la base de datos      | `postgres`                                  |

| `DB_PASSWORD` | Contraseña de la base de datos   | `postgres`                                  |

| `JWT_SECRET`  | Clave secreta para firma JWT     | `change-this-secret-in-production`          |

> [!IMPORTANT]

> Cambia siempre el `JWT_SECRET` y las credenciales de la base de datos antes de desplegar en un entorno de producción.

---

## 🔌 Endpoints de la API

- **Health:** `GET /health` -> Retorna `{"status": "UP"}`

- **Auth:** `POST /auth/login` -> Retorna un token JWT.

- **Secure:** `GET /secure` -> (Requiere JWT) Saluda al usuario autenticado.

- **AI Chat:** `POST /ai/chat` -> (Requiere JWT) Interfaz con el agente de IA.

---

## 🚢 Despliegue

1. Construye la imagen de Docker:

   ```bash

   docker build -t ktor-app:latest .

   ```

2. Instala el Chart de Helm:

   ```bash

   helm install ktortemplatedockerized ./ktortemplatedockerized-chart

   ```

3. (Opcional) Actualiza el Chart:

   ```bash

   helm upgrade ktortemplatedockerized ./ktortemplatedockerized-chart

   ```

---

## 🤝 Contribuir

¡Las contribuciones son bienvenidas! Siéntete libre de enviar un Pull Request.

1. Haz un Fork del proyecto.

2. Crea tu rama de características (`git checkout -b feature/NuevaCaracteristica`).

3. Realiza tus cambios (`git commit -m 'Añadir NuevaCaracteristica'`).

4. Sube los cambios a tu rama (`git push origin feature/NuevaCaracteristica`).

5. Abre un Pull Request.

---

## 📄 Licencia

Distribuido bajo la **Licencia MIT**. Consulta `LICENSE` para más información.

---



  Hecho con ❤️ por Nicolas Cao