GUI-DGT-003 Guía de despliegue de LinkBridge

v 4.0

Objetivo

Esta guía proporciona una metodología paso a paso para la creación, configuración y despliegue de instancias de software y bases de datos en Amazon Web Services (AWS), asegurando la coherencia y la optimización en el despliegue de aplicaciones.

Notas introductorias

Este documento está diseñado para desarrolladores y administradores de sistemas que estén preparados para desplegar aplicaciones backend y frontend utilizando servicios de AWS, nvm para la gestión de Node.js, y Vercel para el frontend.

Diagrama

Diagrama de despliegue

Contenido

1. Creación de la instancia

1.1 Lanzamiento de una instancia EC2

Para crear y lanzar una nueva instancia EC2, inicia sesión en AWS utilizando la región de North Virginia (us-east-1). Ingresa al dashboard de instancias EC2 utilizando el buscador superior. Una vez dentro, utiliza el botón “Launch instance” para iniciar con la creación de la instancia.

1.2 Configuración de creación

Al clickear este botón, se te mostrará la interfaz de configuración de creación de una instancia EC2, donde se te pedirá llenar correctamente los siguientes parámetros.

• Nombre: Es el nombre de tu instancia. Se recomienda agregar uno descriptivo y que te ayude a identificar fácilmente tu instancia.
• AMI (Amazon Machine Image): Es el sistema operativo que se instalará en tu instancia. Asegúrate de seleccionar ubuntu en esta opción.
• Tipo de instancia: Es la capacidad de procesamiento y memoria que contendrá nuestra instancia. Selecciona t2.micro en esta opción.
• Key pair: Esta es una llave única que genera AWS para permitirnos conectarnos a nuestra instancia a través de un túnel SSH. Selecciona el botón “Create new key pair” para crear una nueva llave. Agrega un nombre descriptivo a esta llave, selecciona ED25519 como tipo de llave y .pem como formato. Al crear la key pair, se descargará a tu ordenador, se recomienda guardarla en la ruta C:\Users\<Tu usuario> (para Windows) o su equivalente en otros sistemas operativos para facilitar los pasos posteriores.
• Configuraciones de red: Debes crear un nuevo grupo de seguridad con las siguientes reglas:

• Almacenamiento: Selecciona 30 GiB gp2 para el almacenamiento de la instancia.

Al terminar con la anterior configuración, puedes seleccionar el botón “Launch instance” para crear y lanzar la instancia.

2. Configuración de la instancia

Ahora es necesario configurar la instancia para poder realizar correctamente el despliegue de nuestra aplicación. Ingresa a la instancia recién creada desde el dashboard EC2. Dentro, se te mostrarán todos los detalles de tu nueva instancia. Selecciona la opción “security” y posteriormente da click en el id de tu security group.

Tras seleccionar esta opción, se te mostrarán los detalles de tu grupo de seguridad. Selecciona la opción “Edit inbound rules”.

Agrega las siguientes reglas de seguridad:

Las cuales permitirán el tráfico hacia nuestra instancia desde cualquier ip, en los puertos 22 (SSH), 5432 (PostgreSQL), 443 (HTTPS) 80 (HTTP).

3. Conexión a la instancia

Para conectarse a la instancia, utilizaremos un túnel SSH, junto con la llave .pem que se nos generó anteriormente. Dentro de la interfaz de detalles de tu instancia, selecciona la opción “Connect”.

Se te mostrarán las opciones posibles para realizar una conexión a tu instancia. Selecciona “SSH Client” como método de conexión y sigue los siguientes pasos:

1. Abre una terminal de powershell.
2. Localiza la carpeta donde se encuentra la “key.pem” y dirígete a ella:

cd <dir/to/key.pem>

3. Utiliza el comando chmod 400 Key.pem para asegurar que la llave de acceso no sea visible públicamente.
4. Copia y pega en powershell el comando de conexión utilizando el DNS de tu instancia. Ejemplo:

ssh -i “<nombreKey>.pem” ubuntu@<DNS>.compute-1.amazonaws.com

Nota: En powershell, deberás ubicarte en el directorio en el que hayas guardado tu key.pem. Tras ejecutar este comando, se nos conectará por primera vez a la instancia, por lo que deberemos teclear “yes” para almacenar nuestros datos de sesión.

De esta manera, tu dispositivo será guardado como dispositivo confiable para posteriores conexiones, y te habrás conectado con éxito a la instancia.

Tras conectarse a la instancia, ejecuta los siguientes comandos:

sudo apt update

sudo apt upgrade -y

sudo apt install nodejs wget npm nginx certbot -y

Si te pide reiniciar los servicios, selecciona todos con la tecla espacio y luego “Ok”

Después, debes instalar node.js y npm utilizando nvm para asegurar que instales las versiones correctas. Comienza instalando nvm utilizando el comando:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

Para que nvm funcione correctamente dentro de nuestra instancia, ejecuta los siguientes comandos:

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Habiendo hecho esto, podremos instalar node.js y npm en las versiones correctas. Utiliza el comando:

nvm install --lts

Después, es necesario instalar el manejador de paquetes pnpm y el daemon del proyecto utilizando el comando:

npm install -g pnpm pm2

4. Despliegue del proyecto

Clonación de repositorios

Iniciaremos clonando el repositorio de git, donde se ubica todo el código fuente del backend. Para ello ejecutamos los siguientes comandos:

Para la rama main:

git clone https://github.com/Black-Dot-2024/Zeitgeist-Backend.git

Para la rama staging:

git clone -b staging https://github.com/Black-Dot-2024/Zeitgeist-Backend.git Staging-Zeitgeist-Backend

Una vez realizado esto, debemos ingresar a la carpeta de cada proyecto, utilizando los comandos:

cd Zeitgeist-Backend

cd Staging-Zeitgeist-Backend

Dentro de estas carpetas, es necesario ejecutar el comando para instalar las dependencias del proyecto desde el manejador de módulos que tenemos. Esto se hace mediante los siguientes comandos:

pnpm install

pnpm install prisma --save-dev

pnpm install @prisma/client

Despliegue de backend usando pm2

Ahora necesitamos crear el archivo .env dentro del directorio de nuestros repositorios Backend, Este archivo contiene todas las variables de entorno necesarias para el correcto funcionamiento del backend. Para ello, deberás crear el archivo mediante el editor de texto ‘nano’, y copiar y pegar el texto mostrado debajo.

Para la carpeta Zeitgeist-Backend:

nano .env
NODE_ENV="development"
HOST="localhost"
#Production
PORT=4000
#Production Database
DATABASE_URL=<Reemplazar por URL>

Para la carpeta Staging-Zeitgeist-Backend:

nano .env
NODE_ENV="development"
HOST="localhost"
#Staging
PORT=4001
#Staging Database
DATABASE_URL=<Reemplazar por URL>

Una vez configurado el .env, genera los modelos de Prisma, ejecutando:

pnpm run prisma:generate

Para iniciar el servidor de desarrollo y correr el Backend del proyecto, ejecuta el comando:

pnpm run dev

Para compilar el proyecto y utilizar un ambiente productivo, ejecuta el comando:

pnpm run build

Finalmente, inicializa la aplicación con el siguiente comando:

pm2 start dist/index.js --name "production”

Para verificar que el servicio se haya levantado correctamente, puedes ejecutar el comando:

pm2 status

Así se desplegará en la terminal información acerca del status de las instancias configuradas.

Despliegue de frontend usando vercel

1. Entra a la plataforma de Vercel: https://www.vercel.com/

2. Crea tu cuenta, preferentemente enlazando con tu cuenta de github

3. Cuenta ya hayas creado tu cuenta de usuario ahora debes de crear un proyecto. En la sección del dashboard debes de pulsar el botón de “Add New…”:

4. Luego selecciona la opción de “Project”:

5. Luego debes de importar un repositorio desde tu cuenta de git:

6. Debes de pulsar en donde dice “Import”

7. Luego puedes configurar el proyecto:

8. Tambien puedes especificar el nombre del proyecto:

9. Igualmente puedes seleccionar con qué “Framework” está hecho el proyecto. Vercel te lo reconoce automáticamente:

10. Aquí puedes especificar si tu proyecto se encuentra desde el “directorio raíz”. Si por ejemplo tu proyecto se encuentra dentro de una carpeta llamada “/proyecto” debes de especificar que tu código se encuentra dentro de esa carpeta, si de lo contrario todo tu código se encuentra desde la raíz solo debes de poner un “/”:

11. Luego debes de especificar qué comandos se necesitan correr para que se pueda compilar tu proyecto:

12. En específico necesitas para este proyecto estos:

13. Luego debes especificar si tu proyecto cuenta con variables de entorno. Lo que debes de hacer es irte a tu carpeta “.env” de tu proyecto y copiar cada clave con su valor correspondiente aquí:

14. Luego debes de darle en donde dice “Deploy”

5. Configuración de despliegue

Utilizaremos nginx para redireccionar el tráfico de los puertos 4000 y 4001 a un dominio específico.

Verificaremos que tengamos instalado nginx dentro de nuestra instancia. Utiliza el comando:

sudo apt install nginx

Después, accede como superusuario a la instancia para comenzar con la configuración. Utiliza el comando:

sudo su -

Accede al directorio raíz utilizando el comando:

cd ..

Utiliza el siguiente comando para ingresar a la carpeta de configuración de nginx:

cd /etc/nginx/sites-available

Crearemos el primer archivo de configuración, usando el comando mostrado debajo, donde "dominio" es el nombre del dominio que desea utilizar.

sudo nano dominio

Para este ejemplo realizaré dos despliegues dentro de la misma instancia, uno para un ambiente de staging y uno para ambiente productivo. Comenzaremos utilizando la ip pública de nuestra instancia de AWS para desplegar nuestro ambiente de staging. El comando sería el siguiente:

sudo nano 34.232.102.32

Dentro del editor de texto nano, pega el siguiente bloque de configuración:

server {
    server_name <dominio>;
    location / {
        proxy_pass http://localhost:<puerto>;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    location ~ /.well-known/acme-challenge {
        allow all;
        root /home/ubuntu/<DirectorioDeProyecto>;
    }
}

Sustituye los valores de dominio (), puerto y directorio de proyecto. Para el ejemplo utilizado en esta guía, el bloque de configuración de texto quedaría de la siguiente manera:

server {
    server_name 34.232.102.32;
    location / {
        proxy_pass http://localhost:4001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    location ~ /.well-known/acme-challenge {
        allow all;
        root /home/ubuntu/Staging-Zeitgeist-Backend;
    }
}

Presiona CTRL + X para salir del editor de texto nano y guarda el archivo. Posiciónate en la carpeta raíz para continuar con el procedimiento. Puedes moverte hacia arriba de directorios utilizando el comando:

cd ..

Finalmente, ahora debemos habilitar la configuración de sitio que acabamos de crear. Utiliza el siguiente comando:

sudo ln -s /etc/nginx/sites-available/<dominio> /etc/nginx/sites-enabled/

Siguiendo el ejemplo, el comando sería:

sudo ln -s /etc/nginx/sites-available/34.232.102.32 /etc/nginx/sites-enabled/

Lo único restante sería comprobar que la configuración realizada sea correcta, utiliza el comando:

sudo nginx -t

Ejecuta los siguientes comandos para reiniciar nginx y que los cambios se ejecuten correctamente.

sudo systemctl stop nginx
sudo systemctl start nginx
sudo systemctl status nginx

Tras reiniciar con éxito nginx, podremos entrar a la url designada dentro de nuestra configuración de nginx.

6 Obtención de certificado SSL

Para obtener un certificado SSL, podemos utilizar la herramienta certbot. Esta herramienta emite un certificado válido y lo renueva de manera automática después de un año. Podemos instalar las dependencias necesarias utilizando el comando:

sudo apt install python3-certbot-nginx

Finalmente, basta con ejecutar el comando

sudo certbot --nginx -d <dominio>

Donde <dominio> es el dominio que hayas configurado utilizando nginx. Si realizaste tu configuración correctamente, deberás obtener un mensaje de éxito tras ejecutar este comando y también deberías ahora poder acceder a través de HTTPS a tu sitio.

7. PostgreSQL

Paso 1: Instalar PostgreSQL

Instala PostgreSQL y sus componentes complementarios ejecutando:

sudo apt install postgresql postgresql-contrib -y

Paso 2: Configurar PostgreSQL para Permitir Conexiones Remotas

Por defecto, PostgreSQL está configurado para aceptar conexiones sólo desde el mismo equipo. Para permitir conexiones remotas, necesitaremos hacer algunos cambios en la configuración. Esto nos va a permitir acceder desde un cliente local, para hacer revisiones de la base de datos.

1. Editar postgresql.conf:

Abre el archivo de configuración con un editor de texto:

sudo nano /etc/postgresql/14/main/postgresql.conf

2. Encuentra la línea que dice #listen_addresses = 'localhost' y cámbiala a listen_addresses = '*'. Esto hará que PostgreSQL acepte conexiones en todas las interfaces de red.

3. Editar pg_hba.conf

Ahora, necesitas configurar el método de autenticación para las conexiones remotas:

sudo nano /etc/postgresql/14/main/pg_hba.conf

4. Agrega o modifica una línea al final del archivo para permitir conexiones con contraseña desde cualquier dirección IP:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             0.0.0.0/0               md5

5. Reiniciar PostgreSQL:

Reinicia el servicio de PostgreSQL para aplicar los cambios:

sudo systemctl restart postgresql

Paso 3: Verificar la Configuración

Verifica que PostgreSQL está escuchando en todas las interfaces y el puerto correcto (5432 por defecto):

sudo netstat -plntu | grep postgres

Paso 4: Conectar a PostgreSQL

Ahora puedes conectarte a PostgreSQL utilizando el usuario predeterminado (postgres) y empezar a configurar tus bases de datos y usuarios.

sudo -u postgres psql

Dentro de la consola de psql, ejecuta el siguiente comando para cambiar la contraseña del usuario postgres:

ALTER USER postgres WITH ENCRYPTED PASSWORD '<consultar_env_file>';

Para obtener la contraseña, consulta con un desarrollador para que la proporcione. Paso 4: Crear un Usuario Administrador A continuación, crearás un nuevo usuario que tenga privilegios de administrador.

1. Crear el usuario:

Todavía dentro de la consola psql, crea el nuevo usuario, que llamaremos admin, y establece su contraseña:

CREATE USER admin WITH PASSWORD '<consultar_env_file>';

2. Otorgar privilegios de superusuario:

Para dar al usuario admin privilegios de superusuario, ejecuta:

ALTER USER admin WITH SUPERUSER;

3. Esto le otorgará al usuario admin todos los privilegios necesarios para administrar la base de datos

Dentro de la consola de psql, puedes crear usuarios y bases de datos:

CREATE DATABASE zg_staging_db;
GRANT ALL PRIVILEGES ON DATABASE zg_staging_db TO admin;
CREATE DATABASE zg_production_db;
GRANT ALL PRIVILEGES ON DATABASE zg_production_db TO admin;

Sal de psql con

\\q

Control de cambios

Versión	Cambio realizado	Análisis	Autor	Revisor(es)	Fecha de cambio
v 1.0	1° iteración guia de despliegue	N/A	Ian Joab Padrón Corona	Armando Rosas	15/04/2024
v 2.0	Ajuste de formato	Se modificó el contenido de la guía de acuerdo a la plantilla porque el documento tenía información no requeridas	Yuna Chung	Ricardo Fernández	24/04/2024
v 3.0	Agregar nuevas secciones	Se agrego la parte de despliegue usando vercel y la sección de PostgreSQL	Diego Perdomo	Arturo Díaz	2/05/2024
v 4.0	Se agregó la sección de certbot		Arturo Díaz	Daniel Hurtado	13/05/2024