GeoOaxacaHub

Servicio Centralizado de Geolocalización Gubernamental

Sistema de información geográfica (GIS) construido con Laravel 12, PostgreSQL/PostGIS y Docker, diseñado para gestionar datos de geolocalización a nivel gubernamental.

---

📋 Tabla de Contenidos

• Características
• Stack Tecnológico
• Requisitos Previos
• Instalación
• Configuración
• Uso
• Estructura del Proyecto
• API
• Desarrollo
• Licencia

---

✨ Características

• 🗺️ Gestión de Datos Geoespaciales: Soporte completo para geometrías PostGIS (puntos, líneas, polígonos)
• 🔐 Autenticación Robusta: Laravel Jetstream con Livewire, autenticación de dos factores
• 🚀 API RESTful: Laravel Sanctum para autenticación de API y tokens personales
• 🐳 Infraestructura Dockerizada: Entorno de desarrollo completamente containerizado
• 📊 Base de Datos Espacial: PostgreSQL 16 con PostGIS 3.4
• 🛠️ Herramientas GIS: Integración con clickbar/laravel-magellan para manejo de geometrías

---

🛠 Stack Tecnológico

Backend

• Framework: Laravel 12.48.1 (PHP 8.5)
• Base de Datos: PostgreSQL 16.4
• Extensión GIS: PostGIS 3.4 (GEOS, PROJ, STATS)
• Autenticación: Laravel Jetstream 5.4.0 + Sanctum 4.2.4
• GIS Library: clickbar/laravel-magellan 2.0.1

Frontend

• Stack: Livewire 3.7.6
• Build Tool: Vite 7.3.1
• CSS Framework: Tailwind CSS (incluido con Jetstream)

Infraestructura

• Containerización: Docker + Docker Compose
• Servidor Web: Laravel Sail (Nginx + PHP-FPM)
• Imagen Base: postgis/postgis:16-3.4-alpine

---

📦 Requisitos Previos

Antes de comenzar, asegúrate de tener instalado:

• Docker Desktop (Windows/Mac) o Docker Engine (Linux)
  • Descargar Docker Desktop
• Git (para clonar el repositorio)
• Composer (opcional, para desarrollo local sin Docker)

Verificar Instalación

docker --version
# Docker version 28.4.0 o superior

docker compose version
# Docker Compose version v2.x.x o superior

---

🚀 Instalación

1. Clonar el Repositorio

git clone <repository-url> GeoOaxacaHub
cd GeoOaxacaHub

2. Configurar Variables de Entorno

Copia el archivo de ejemplo y ajusta las configuraciones:

cp .env.example .env

Edita .env y actualiza las siguientes variables:

APP_NAME=GeoOaxacaHub
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=pgsql
DB_HOST=pgsql
DB_PORT=5432
DB_DATABASE=geooaxacahub
DB_USERNAME=sail
DB_PASSWORD=password

3. Iniciar Docker Desktop

En Windows, ejecuta desde PowerShell:

Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"

O inicia Docker Desktop manualmente desde el menú de inicio.

4. Levantar los Contenedores

docker compose up -d

Este comando:

• Descarga las imágenes necesarias (primera vez)
• Crea los contenedores para Laravel y PostgreSQL/PostGIS
• Inicia los servicios en segundo plano

5. Instalar Dependencias (si es necesario)

Si clonaste el repositorio sin vendor/:

docker compose exec laravel.test composer install
docker compose exec laravel.test npm install

6. Generar Application Key

docker compose exec laravel.test php artisan key:generate

7. Ejecutar Migraciones

docker compose exec laravel.test php artisan migrate

Esto creará todas las tablas necesarias y habilitará la extensión PostGIS.

8. Crear Usuario Administrador

Ejecuta el seeder para crear el usuario administrador predeterminado:

docker compose exec laravel.test php artisan db:seed --class=AdminUserSeeder

Credenciales de acceso:

• Email: geoadmin@gmail.com
• Password: Geo#Admin

⚠️ Importante: Cambia estas credenciales en producción por seguridad.

9. Compilar Assets Frontend

docker compose exec laravel.test npm run build

Para desarrollo con hot-reload:

docker compose exec laravel.test npm run dev

---

⚙️ Configuración

Acceder a la Aplicación

Una vez que los contenedores estén corriendo:

• Aplicación Web: http://localhost
• Base de Datos: localhost:5432
  • Usuario: sail
  • Contraseña: password
  • Base de datos: geooaxacahub (o según .env)

Usuario Administrador

El proyecto incluye un usuario administrador predeterminado creado mediante seeder:

Credenciales:

• Email: geoadmin@gmail.com
• Password: Geo#Admin

Para acceder:

1. Navega a http://localhost/login
2. Ingresa las credenciales anteriores
3. Accederás al dashboard de administración

💡 Tip: Puedes crear usuarios adicionales desde la interfaz de registro o mediante Tinker:

docker compose exec laravel.test php artisan tinker

$user = App\Models\User::create([
    'name' => 'Nuevo Usuario',
    'email' => 'usuario@ejemplo.com',
    'password' => bcrypt('password'),
    'email_verified_at' => now(),
]);

Verificar PostGIS

Conecta a la base de datos y verifica la extensión:

docker compose exec pgsql psql -U sail -d geooaxacahub -c "SELECT PostGIS_Version();"

Salida esperada:

            postgis_version
---------------------------------------
 3.4 USE_GEOS=1 USE_PROJ=1 USE_STATS=1

---

💻 Uso

Comandos Artisan

Ejecuta comandos de Laravel dentro del contenedor:

# Sintaxis general
docker compose exec laravel.test php artisan [comando]

# Ejemplos
docker compose exec laravel.test php artisan route:list
docker compose exec laravel.test php artisan db:show
docker compose exec laravel.test php artisan make:model Location -m

Acceso a la Base de Datos

# Conectar a PostgreSQL
docker compose exec pgsql psql -U sail -d geooaxacahub

# Listar tablas
\dt

# Ver extensiones instaladas
\dx

# Salir
\q

Logs

# Ver logs de Laravel
docker compose exec laravel.test php artisan pail

# Ver logs de Docker
docker compose logs -f laravel.test
docker compose logs -f pgsql

---

📁 Estructura del Proyecto

GeoOaxacaHub/
├── app/
│   ├── Http/
│   │   └── Controllers/     # Controladores de la aplicación
│   ├── Models/              # Modelos Eloquent (con soporte PostGIS)
│   └── ...
├── database/
│   ├── migrations/          # Migraciones (incluye PostGIS)
│   │   └── 2026_01_23_230427_enable_postgis_extension.php
│   └── seeders/
├── resources/
│   ├── views/               # Vistas Blade/Livewire
│   └── js/                  # Assets JavaScript
├── routes/
│   ├── web.php              # Rutas web
│   └── api.php              # Rutas API (Sanctum)
├── compose.yaml             # Configuración Docker (PostGIS)
├── .env                     # Variables de entorno
└── README.md

---

🔌 API

Autenticación

GeoOaxacaHub usa Laravel Sanctum para autenticación de API.

Generar Token Personal

docker compose exec laravel.test php artisan tinker

$user = App\Models\User::find(1);
$token = $user->createToken('api-token')->plainTextToken;
echo $token;

Usar el Token

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost/api/user

Endpoints Disponibles

Método	Endpoint	Descripción
GET	/api/user	Obtener usuario autenticado
POST	/api/locations	Crear nueva ubicación (ejemplo)
GET	/api/locations	Listar ubicaciones

---

🧑‍💻 Desarrollo

Crear Modelos con Geometrías

Ejemplo de modelo con columna geométrica:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Clickbar\Magellan\Database\Eloquent\HasPostgisColumns;

class Location extends Model
{
    use HasPostgisColumns;

    protected $fillable = ['name', 'coordinates'];

    protected array $postgisColumns = [
        'coordinates' => [
            'type' => 'geometry',
            'srid' => 4326, // WGS 84
        ],
    ];
}

Migración con Geometría

Schema::create('locations', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->geometry('coordinates', 'POINT', 4326);
    $table->timestamps();
});

Trabajar con Geometrías

use Clickbar\Magellan\Data\Geometries\Point;

// Crear ubicación
$location = Location::create([
    'name' => 'Palacio de Gobierno',
    'coordinates' => new Point(17.0654, -96.7236, 4326),
]);

// Consultar por proximidad (ejemplo)
$nearby = Location::query()
    ->whereRaw('ST_DWithin(coordinates, ST_MakePoint(?, ?), ?)', 
        [-96.7236, 17.0654, 1000])
    ->get();

Detener el Entorno

# Detener contenedores (mantiene datos)
docker compose stop

# Detener y eliminar contenedores (mantiene volúmenes)
docker compose down

# Eliminar todo (incluyendo volúmenes de base de datos)
docker compose down -v

Tests

docker compose exec laravel.test php artisan test

---

📄 Licencia

Este proyecto está licenciado bajo la MIT License.

---

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

---

📞 Soporte

Para reportar problemas o solicitar características, por favor abre un issue.

---

Desarrollado con ❤️ para el Gobierno de Oaxaca