https://github.com/tomtapia/cloud-run-microservice-template
Microservice template for GCP Cloud Run
https://github.com/tomtapia/cloud-run-microservice-template
Last synced: 3 months ago
JSON representation
Microservice template for GCP Cloud Run
- Host: GitHub
- URL: https://github.com/tomtapia/cloud-run-microservice-template
- Owner: tomtapia
- License: mit
- Created: 2024-07-24T22:50:10.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-03-21T15:20:22.000Z (3 months ago)
- Last Synced: 2025-03-21T15:30:32.289Z (3 months ago)
- Language: TypeScript
- Size: 420 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Cloud Run Microservice Template
[](https:\/\/github.com\/tomtapia\/cloud-run-microservice-template\/actions)
[](https:\/\/github.com\/tomtapia\/cloud-run-microservice-template\/blob\/main\/LICENSE)
## Microservice Template for GCP Cloud Run
This project is a template for creating microservices on Google Cloud Platform's Cloud Run using the NestJS framework. It leverages the powerful features of NestJS for building efficient, reliable, and scalable server-side applications while providing a structured logging mechanism with Pino.
## Table of Contents
- [Cloud Run Microservice Template](#cloud-run-microservice-template)
- [Microservice Template for GCP Cloud Run](#microservice-template-for-gcp-cloud-run)
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Project Structure](#project-structure)
- [Layer Responsibilities](#layer-responsibilities)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running the Application](#running-the-application)
- [Development Mode](#development-mode)
- [Watch Mode](#watch-mode)
- [Production Mode](#production-mode)
- [Testing](#testing)
- [Contributing](#contributing)
- [Support](#support)
- [License](#license)
## Features
- **NestJS**: Progressive Node.js framework for building efficient and scalable server-side applications.
- **Structured Logging**: JSON formatted logger using Pino, parsable by Cloud Logging, with automatic correlation of container logs to a request log.
- **Cloud Run**: Serverless containerized applications that automatically scale.
- **Environment Configuration**: All external variables are loaded at the start of the project through the `.env` file.
## Project Structure
This project follows a **Clean Architecture** approach, organizing the code into three main layers: `domain`, `application`, and `infrastructure`. Each layer has a distinct responsibility to ensure separation of concerns, testability, and maintainability.
```bash
├── src # Main application source code
│ ├── domain # Domain layer: core business logic, entities, and contracts
│ │ ├── models # Core domain models/entities
│ │ ├── repositories # Abstract repository interfaces (contracts)
│ │ └── services # Domain services (pure business logic, no side effects)
│ ├── application # Application layer: use cases, DTOs, and application services
│ │ ├── use-cases # Application-specific business logic
│ │ ├── dto # Data Transfer Objects used between layers
│ │ └── services # Application-level services orchestrating use cases
│ ├── infrastructure # Infrastructure layer: technical implementations, framework integrations
│ │ ├── api-clients/ # HTTP clients for external APIs (REST, GraphQL, etc.)
│ │ ├── cache/ # Cache adapters (e.g., Redis, in-memory)
│ │ ├── database/ # DB configuration, ORM integration, custom repository implementations
│ │ ├── env # Loads and validates environment variables from .env
│ │ │ └── index.ts # Entry point for accessing environment configs
│ │ ├── http # HTTP adapter using NestJS (controllers, middleware, filters, views)
│ │ │ ├── controllers # REST API controllers (public-facing endpoints)
│ │ │ │ ├── home.controller.ts # Root/home endpoint
│ │ │ │ └── metadata.controller.ts # Exposes service metadata
│ │ │ ├── filters # Global filters for handling HTTP exceptions
│ │ │ │ └── http-exception.filter.ts
│ │ │ ├── middleware # Global HTTP middleware (e.g., security, compression)
│ │ │ │ ├── compression.middleware.ts
│ │ │ │ └── helmet.middleware.ts
│ │ │ ├── public # Public static assets
│ │ │ │ ├── favicon.ico
│ │ │ │ └── favicon.webp
│ │ │ └── views # View templates for rendering HTML (if applicable)
│ │ │ └── metadata.hbs
│ │ ├── ioc # Inversion of Control (dependency injection modules)
│ │ │ ├── app.module.ts # Main NestJS application module
│ │ │ └── infrastructure.module.ts # Infrastructure-specific providers and bindings
│ │ └── logger # Structured logging using Pino, compatible with Cloud Logging
│ │ ├── gcp.logger.ts # Logger configuration for GCP
│ │ ├── index.ts # Logger entry point
│ │ └── request.logger.ts # Middleware or interceptor for per-request logging
│ │ ├── messaging/ # Pub/Sub, Kafka, or other message brokers integration
│ │ ├── security/ # Authentication, authorization strategies and utilities
│ │ ├── storage/ # File storage (local, GCS, S3, etc.)
│ │ ├── cqrs/ # CQRS handlers for command and query logic
│ │ ├── commands/ # Command handlers (create, update, delete operations)
│ │ └── queries/ # Query handlers (read-only operations)
│ └── main.ts # Application entry point (starts the NestJS app)
├── test # End-to-end or integration tests
│ └── app.e2e-spec.ts # Basic E2E test for application startup
├── .dockerignore # Files and folders to ignore during Docker image build
├── .eslintrc.js # ESLint config for code quality and style
├── .gcloudignore # Files to exclude during Google Cloud deployment
├── .gitignore # Git ignored files
├── .prettierrc # Prettier configuration for code formatting
├── Dockerfile # Docker build configuration for Cloud Run
├── LICENSE # Project license
└── README.md # Project documentation (you are here!)
```
### Layer Responsibilities
- **`domain/`**: Pure business logic. No framework or infrastructure-specific code. Should be reusable and testable in isolation.
- **`application/`**: Application workflows (use cases). Coordinates domain logic and maps inputs/outputs.
- **`infrastructure/`**: Implements contracts from domain, handles external services (HTTP, DB, logging, etc.).
## Prerequisites
- Enable the Cloud Run API via the [console](https:\/\/console.cloud.google.com\/apis\/library\/run.googleapis.com) or CLI:
```bash
gcloud services enable run.googleapis.com
```
- Create a `.env` file in your local with the minimal parameters.
```bash
GOOGLE_CLOUD_PROJECT=
APP_NAME=
APP_DESCRIPTION=
API_VERSION=
PORT=
```
## Installation
Clone the repository:
```bash
git clone https://github.com\/tomtapia\/cloud-run-microservice-template.git
cd cloud-run-microservice-template
```
Install dependencies:
```bash
npm install
```
## Running the Application
### Development Mode
```bash
npm run start
```
### Watch Mode
```bash
npm run start:dev
```
### Production Mode
```bash
npm run start:prod
```
## Testing
To run tests:
```bash
npm run test
```
To run end-to-end tests:
```bash
npm run test:e2e
```
## Contributing
We welcome contributions! Please see the [contributing guidelines](CONTRIBUTING.md) for more details.
## Support
Please use the issue tracker for bug reports, feature requests, and submitting pull requests.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
¡Aquí tienes la sección lista en formato Markdown para que la pegues directamente en tu `README.md` o en la documentación del proyecto!