Visión general del proyecto

pkgsite permite implementar un servidor de documentación para paquetes Go en un entorno local, facilitando el acceso rápido a la información de bibliotecas. Este sistema se basa en una arquitectura modular que incluye componentes como el frontend, la base de datos, un worker y un sistema de caché, los cuales interactúan para proporcionar una experiencia de documentación fluida.

Figura 1: Esquema arquitectónico de pkgsite que ilustra la interacción entre los servicios principales.

Requisitos previos y configuración

Instalación de herramientas

Asegúrate de tener instalados los siguientes componentes en tu sistema:

• Git para la obtención del código fuente.
• Docker y Docker Compose para la orquestación de contenedores.
• Go versión 1.25.5 o posterior, según las especificaciones del proyecto.

Obtención del código

Clona el repositorio usando el siguiente comando y accede al directorio:

git clone https://gitcode.com/gh_mirrors/pk/pkgsite
cd pkgsite

Ajuste de variables de entorno

Las configuraciones de entorno, como credenciales de base de datos, se encuentran en el archivo devtools/docker/compose.yaml. Para personalizaciones, modifica las secciones correspondientes en dicho archivo.

Procedimientos de despliegue

Método 1: Despliegue automatizado con Docker Compose

Utiliza el script proporcionado para iniciar todos los servicios de manera conjunta:

./devtools/docker.sh up -d
docker compose -f devtools/docker/compose.yaml ps

Este proceso levanta la base de datos PostgreSQL, el frontend y ejecuta migraciones iniciales automáticamente.

Método 2: Implementaicón manual paso a paso

Para un control más granular, sigue estos pasos secuenciales:

1. Iniciar el servicio de base de datos:``` ./devtools/docker_postgres.sh

2. Crear y actualizar la estructura de la base de datos:``` go run devtools/cmd/db/main.go create go run devtools/cmd/db/main.go migrate

3. Poblar la base de datos con datos iniciales:``` go run ./devtools/cmd/seeddb/main.go -seed seed.txt

4. Lanzar el servidor front end:``` go run ./cmd/frontend -host=0.0.0.0:8080

Confirmación del entorno local

Tras completar el despliegue, accede a http://localhost:8080 mediante un navegador web. Se mostrará una interfaz de documentación con opciones de búsqueda y navegación por paquetes Go.

Figura 2: Captura de pantalla de la página principal del servidor de documentación local.

Funcionalidades destacadas

Documentación accesible sin conexión

El entorno local permite consultar la documentación de paquetes Go sin necesidad de conexión a internet, ideal para entornos con restricciones de red.

Búsqueda optimizada

Incluye un motor de búsqueda que permite encontrar paquetes y símbolos específicos de manera eficiente.

Figura 3: Ejemplo de interfaz de búsqueda en pkgsite con resultados filtrados.

Soporte para múltiples versiones

Facilita la visualización y comparación de ditsintas versiones de paquetes Go, ayudando a identificar cambios en las APIs.

Resolución de incidencias frecuentes

Fallo al iniciar servicios

Verifica el estado de Docker y revisa los registros del frontend para diagnosticar problemas:

docker compose -f devtools/docker/compose.yaml logs frontend

Actualización de datos de documentación

Para refrescar la información de paquetes, ejecuta nuevamente el comando de carga:

go run ./devtools/cmd/seeddb/main.go -seed seed.txt

Resolución de conflictos de puertos

Si el puerto 8080 está ocupado, ajusta el mapeo de puertos en el archivo devtools/docker/compose.yaml, por ejemplo, utilizando el puerto 8081.