Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Distribuidos-Org/ms-alumnos/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the repository, configuring your environment, starting a local PostgreSQL database via Docker Compose, and sending your first create_alumno message over NATS — all in about five minutes. By the end you will have a fully running instance of ms-alumnos ready to accept requests from any NATS publisher.
1

Prerequisites

Make sure the following are available on your machine before you begin:The quickest way to spin up NATS locally is with Docker:
docker run -p 4222:4222 nats:latest
Leave this terminal open (or run with -d to detach). ms-alumnos will connect to nats://localhost:4222 when NATS_SERVERS is set to that address.
2

Install Yarn

If you do not have Yarn installed globally, add it now:
npm install --global yarn
Verify the installation:
yarn --version
3

Clone and install dependencies

Clone the repository and install all Node.js dependencies:
git clone https://github.com/Distribuidos-Org/ms-alumnos.git
cd ms-alumnos
yarn install
Yarn will resolve and cache all packages declared in package.json, including NestJS, TypeORM, the NATS client, bcrypt, and Joi.
4

Configure environment variables

Copy the example environment file and open it in your editor:
cp .env.example .env
The default values work for a standard local setup. The full contents of .env.example are:
PORT=3002
NATS_SERVERS="nats://localhost:4222,nats://localhost:4223"

DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=ms-alumnos-db

DB_HOST=localhost
DB_PORT=5435
Key variables to review:
VariableDefaultNotes
PORT3002Validated at startup by envs.ts but not used to open an HTTP port — the service is NATS-only.
NATS_SERVERSnats://localhost:4222,nats://localhost:4223Comma-separated list of NATS server URLs.
DB_HOSTlocalhostMust match where your Docker container is reachable.
DB_PORT5435Mapped host port for the PostgreSQL container (container internally uses 5432).
If you are only running a single NATS server, you can simplify NATS_SERVERS to just nats://localhost:4222.
5

Start PostgreSQL with Docker Compose

The included docker-compose.yml defines a postgres:15 service that reads its credentials and port directly from your .env file:
docker compose up -d
Docker will pull the postgres:15 image (first run only), create a named volume db_data for persistence, and expose the database on the host port defined by DB_PORT (default 5435). Verify the container is running:
docker compose ps
You should see the db service listed with a running status.
6

Start the microservice

Launch ms-alumnos in watch mode so it reloads on code changes:
yarn start:dev
On successful startup, NestJS logs the NATS servers the service connected to:
[Bootstrap] Alumnos microservice running on NATS servers: nats://localhost:4222, nats://localhost:4223
The service is now listening for NATS message patterns. No HTTP port is opened — all traffic is NATS-only.
7

Send your first message

Use the nats npm package to publish a create_alumno request and inspect the response. Create a temporary file (e.g. test-create.mjs) with the following content:
import { connect, JSONCodec } from 'nats';

const nc = await connect({ servers: 'nats://localhost:4222' });
const jc = JSONCodec();

const response = await nc.request(
  'create_alumno',
  jc.encode({
    nombre: 'Juan',
    apellidoPaterno: 'García',
    dni: '12345678',
    email: 'juan.garcia@example.com',
    contrasena: 'secreta123',
  }),
  { timeout: 5000 }
);

console.log(jc.decode(response.data));
await nc.drain();
Run it with Node.js:
node test-create.mjs
A successful response will print the newly created student record returned by the service (with the password field omitted or hashed, depending on your response DTO).
The create_alumno pattern shown above is just the starting point. See the full Create Alumno message reference for a complete list of accepted fields, validation rules, and possible error responses.

Build docs developers (and LLMs) love

Get started for freeTalk to us