Descripción • Uso • Contribuir • Recursos
Este repositorio contiene el código fuente para la plataforma comunitaria de Open Source UC. La plataforma permite que integrantes de la organización creen perfiles y obtengan logros, entre otras cosas.
- En algunos casos, se opta por utilizar métodos
PUTyPATCHen reemplazo dePOSTpara actualizar recursos, ya que se considera que es más semántico. Por ejemplo, en el caso de aprobar una solicitud de logro, se utilizaPATCH /requests/:id/en vez dePOST /achievements/:id/approve. - Se optó por no implementar un skill tree completo en React (dado a dificultades con el manejo de estado), en vez optando por una vista de grilla de logros, por esta entrega.
- A pesar de no ser necesario, se implementó un sistema de autenticación en base a OAuth de GitHub y autorización mediante JSON Web Tokens.
- Se optó por usar Prisma como ORM en vez de Sequelize.
El repositorio contiene un Dev Container de VSCode, que prepara un entorno de desarrollo listo con PostgreSQL, dependencias y herramientas avanzadas de debugging para tanto el frontend como el backend.
Para usarlo, debes tener instalada de la extensión de Dev Containers. Luego, puedes abrir el proyecto en VSCode, abrir el archivo devcontainer.json y presionar el botón de Reopen in Container en la esquina inferior derecha de la ventana.
Una vez abierto en el contenedor, se instalará PostgreSQL en el entorno y se instalarán las dependencias de tanto el front, como el back, al igual que se ejecutará la creación de tablas y la carga de datos de prueba (seed) de la base de datos. En caso de no estar usando el contenedor, esto puede hacerse manualmente de la siguiente manera:
# Instalar dependencias
cd backend && npm install && npx prisma migrate reset
cd ../frontend && npm install
Una vez instaladas las dependencias y preparada la base de datos, es necesario configurar las variables de entorno. Para esto, hay que crear un archivo .env en la carpeta backend, en base al .env.template. Es necesario proveer el ID y secreto de GitHub para hacer funcionar el OAuth localmente, al igual que un secreto JWT (aleatorio) que gestione la emisión de tokens.
Para obtener tokens de GitHub (en caso de que no se te hayan otorgado de antemano), puedes seguir este tutorial. Para desarrollo local, es necesario configurar http://127.0.0.1:3000/api/auth/callback como Authorization Callback URL.
El secreto JWT puede ser generado de la siguiente manera (usando OpenSSL, aunque cualquier otro generador de tokens aleatorios sirve):
# Generar un secreto aleatorio
openssl rand -hex 32Finalmente, configurado el entorno, se puede ejecutar el proyecto de la siguiente manera mediante las tareas incluidas de VSCode (en la pestaña Run and Debug), o bien ejecutar manualmente:
# Ejecutar el backend:
cd backend && npm run dev
# En otro terminal, ejecutar el frontend:
cd frontend && npm startEn caso de querer generar migraciones despues de un cambio de schema o de pullear nuevas migraciones, es necesario correr: npx prisma migrate dev. Esto sirve para tanto crear nuevas migraciones automáticamente en base a modificaciones en el schema, como para aplicar migraciones que hayan sido creadas por otros miembros del equipo.
Para utilizar una seed en la base de datos, primero debemos eliminar el contenido ya existente, corriendo npx prisma migrate reset. Luego, podemos correr npx prisma db seed para cargar los datos de prueba. (Es posible que el primer comando haga seed automáticamente)
Si es que la variable NODE_ENV está definida como development (puesta por defecto en el contenedor), se puede acceder a las rutas de debugging de autorización, que permiten asumir el rol de cualquier usuario, con tal de probar las distintas rutas. Por ejemplo:
- Para acceder como Fernando (coordinador): http://localhost:3000/api/auth/debug/login?username=fernandosmither
- Para acceder como Agustín (miembro): http://localhost:3000/api/auth/debug/login?username=agucova
Las entidades en el proyecto se encuentran modeladas usando un schema de Prisma, que puede ser encontrado en backend/prisma/schema.prisma. Este schema se compila continuamente para generar el cliente de Prisma y un archivo de especificación DBML que permite, entre otras cosas, generar diagramas del esquema de la base de datos. Este archivo se encuentra en backend/prisma/schema.dbml.
Adicionalmente, Prisma provee un "Studio" que permite inspeccionar los datos en la base de datos. Para abrirlo, se puede correr npx prisma studio.
Fuera del entorno de desarrollo, todo el proceso de deployment a producción ocurre de forma automática. Esto ocurre mediante dos procesos paralelos:
- Con cada commit, Cloudflare Pages se encarga de construir y desplegar el frontend en modo estático (
npm run build). - Con cada push a la rama
main, Fly.io se encarga desplegar el backend (npm start), corriendo migraciones (prisma deploy) según sea necesario.
La configuración de Fly.io se encuentra definida en backend/fly.toml, y la imagen del entorno se encuentra definida en backend/Dockerfile.
El servicio de backups se encuentra implementado de forma análoga a la webapp principal, teniendo una carpeta backend y frontend en backup_ms. Se disponen de comandos de lanzamiento en VSCode para ejecutar el servicio de backups, y por defecto se puede acceder a la webapp en localhost:5173 (la URL de producción es backup.osuc.dev.
El servicio permite almacenar backups de la tabla AchievementsOnMembers, que establece que miembros tienen que logros, y está implementado de una forma flexible, pudiendo funcionar con cualquier tabla con pequeñas modificaciones.
El deployment del servicio ocurre en paralelo de la app principal, estando alojado en Fly.io (api-backup.osuc.dev) y Cloudflare Pages (backup.osuc.dev). Cloudflare Pages hace deployment via Github Actions usando wrangler-cli, con tal de bypassear una limitación en la plataforma (no tener dos sitios en un mismo repo).
Todos los endpoints del servicio, y sus webhooks complementarios en el back-end, se encuentran documentados y testeados en Postman.
Los endpoints de la API se encuentran ejemplificados en Postman.
El workflow es PR a development -> Revisar preview y checks -> Asignar reviewers -> Aprobación -> Merge a development
La información detallada sobre cómo contribuir se puede encontrar en contributing.md.
Utiliza las issues para informar cualquier bug o solicitud.
Además de este repo, se incluyen algunos recursos adicionales: