Inicio Rápido
Configura iMirly en tu máquina local en minutos. Esta guía te llevará desde clonar el repositorio hasta ejecutar tanto el backend como la aplicación Android.
Prerrequisitos
Antes de comenzar, asegúrate de tener instaladas las siguientes herramientas:
PostgreSQL
Versión 15 o superior
Java JDK
Versión 21 o superior
Android Studio
Koala (2024.1.1) o más reciente
Nota: El backend requiere Java 21, mientras que la app Android se compila contra SDK 36 con un SDK mínimo de 26 (Android 8.0).
Configuración Paso a Paso
Paso 1: Clonar el Repositorio
Clona el repositorio de iMirly en tu máquina local:
git clone https://github.com/Anyeel/imirly.git
cd imirly
La estructura del proyecto incluye dos directorios principales:
imirly/
├── backend/ # Spring Boot API
├── frontend/ # Aplicación Android
└── docker-compose.yml # Configuración de contenedor PostgreSQL
Paso 2: Configurar la Base de Datos PostgreSQL
Tienes dos opciones para ejecutar PostgreSQL:
El proyecto incluye un archivo docker-compose.yml para una configuración sencilla:
version: '3.8'
services:
db:
image: postgres:15
container_name: imirly_db_container
restart: always
environment:
POSTGRES_USER: user_imirly
POSTGRES_PASSWORD: password_imirly
POSTGRES_DB: imirly_db
ports:
- "5432:5432"
volumes:
- ./postgres_data:/var/lib/postgresql/data
Inicia el contenedor de la base de datos:
docker-compose up -d
Si prefieres una instalación local, crea la base de datos manualmente:
CREATE DATABASE imirly_db;
CREATE USER user_imirly WITH PASSWORD 'password_imirly';
GRANT ALL PRIVILEGES ON DATABASE imirly_db TO user_imirly;
Paso 3: Configurar Propiedades del Backend
Navega al archivo de configuración del backend y verifica los ajustes de conexión a la base de datos:
cd backend/src/main/resources
El archivo application.properties debe contener:
spring.application.name=iMirly
spring.datasource.url=jdbc:postgresql://localhost:5432/imirly_db
spring.datasource.username=user_imirly
spring.datasource.password=password_imirly
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
⚠️ Importante: Si usaste credenciales diferentes al configurar PostgreSQL, actualiza los campos username y password según corresponda.
Paso 4: Iniciar el Backend Spring Boot
Desde el directorio backend/, inicia el servidor usando Maven:
cd backend
./mvnw spring-boot:run
cd backend
mvn spring-boot:run
La aplicación se iniciará en http://localhost:8080.
✅ Seeder Automático: En el primer inicio, el componente DatabaseSeeder pobla automáticamente la base de datos con categorías y subcategorías de servicios. Verás la confirmación en la consola:
=========================================================
🚀 EJECUTANDO SEEDER: Poblando BD vacía... 🚀
=========================================================
✅ BASE DE DATOS INICIALIZADA EXITOSAMENTE! ✅
¿Qué se inicializa?
El seeder crea automáticamente:
- 7 categorías principales: Hogar, Belleza y Estética, Educación, Cuidado, Deportes y Salud, Mascotas, Eventos y Otros
- 50+ subcategorías en todos los tipos de servicios
- Mapeo de iconos para la UI de la app Android
// Ejemplo de DatabaseSeeder.java
CategoriaEntity hogar = crearCategoria("Hogar", "hogar");
crearSubcategoria("Electricista", "hogar_electricista", hogar);
crearSubcategoria("Fontanería", "hogar_fontaneria", hogar);
crearSubcategoria("Limpieza", "hogar_limpieza", hogar);
// ... más subcategorías
Paso 5: Verificar que el Backend está funcionando
Prueba los endpoints de la API para confirmar que el backend está operativo:
# Health check (requiere Spring Actuator)
curl http://localhost:8080/actuator/health
# Probar conexión a base de datos - obtener categorías
curl http://localhost:8080/api/v1/catalog/categorias
Respuesta esperada para categorías:
[
{
"id": "...",
"nombre": "Hogar",
"icono": "hogar"
},
{
"id": "...",
"nombre": "Estética y Belleza",
"icono": "belleza"
}
// ... más categorías
]
Paso 6: Configurar la Aplicación Android
Abre Android Studio e importa el directorio frontend/ como un proyecto.
Actualizar URL Base de la API (si es necesario)
La app Android viene preconfigurada para conectarse al backend local. Verifica el archivo RetrofitClient.kt:
// frontend/app/src/main/java/com/imirly/app/network/RetrofitClient.kt
object RetrofitClient {
private const val BASE_URL = "http://10.0.2.2:8080"
// 10.0.2.2 es la IP especial para que el emulador Android llegue a la máquina host
// Para dispositivos físicos, reemplaza con la IP local de tu computadora (ej: "http://192.168.1.100:8080")
}
⚠️ Importante: La IP 10.0.2.2 solo funciona para emuladores Android. Si pruebas en un dispositivo físico, reemplázala con la dirección IP de tu red local.
Sincronizar Dependencias Gradle
Abrir Proyecto
Android Studio detectará los archivos build.gradle.kts y te pedirá sincronizar
Sincronizar Gradle
Haz clic en "Sync Now" en la barra de notificaciones, o ve a File → Sync Project with Gradle Files
Esperar Dependencias
Gradle descargará todas las dependencias necesarias incluyendo Retrofit, Jetpack Compose y Navigation
Dependencias clave en app/build.gradle.kts:
dependencies {
// Jetpack Compose para UI
implementation(platform(libs.androidx.compose.bom))
implementation(libs.androidx.compose.material3)
// Retrofit para comunicación con API
implementation("com.squareup.retrofit2:retrofit:2.9.0")
implementation("com.squareup.retrofit2:converter-gson:2.9.0")
// Navigation
implementation("androidx.navigation:navigation-compose:2.8.0")
// ViewModel para gestión de estado
implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.8.4")
}
Paso 7: Ejecutar la Aplicación Android
Seleccionar Dispositivo/Emulador
Crea un Android Virtual Device (AVD) o conecta un dispositivo físico con depuración USB habilitada
Compilar y Ejecutar
Haz clic en el botón verde "Run" (▶️) o presiona Shift + F10
Esperar la Compilación
Gradle compilará el código Kotlin e instalará el APK en tu dispositivo/emulador
La App se Lanza
La aplicación se abrirá en la pantalla de onboarding
Paso 8: Crear tu Primera Cuenta
Una vez que la app esté ejecutándose, prueba el flujo completo:
Navegar a Registro
Desde la pantalla de onboarding, toca "Crear Cuenta"
Completar Formulario de Registro
Ingresa los datos: Nombre, Email, Contraseña, Tipo de Usuario (Cliente o Profesional), Documento de Identidad
Enviar Registro
La app envía una petición POST a /api/v1/auth/register
Recibir Token JWT
Tras el registro exitoso, recibirás un token JWT que se almacena automáticamente
Flujo de registro desde AuthController.java:
@PostMapping("/register")
public ResponseEntity<?> registerUser(@RequestBody RegisterUserRequest request) {
try {
RegisterUserCommand command = new RegisterUserCommand(
request.getNombre(),
request.getEmail(),
request.getRawPassword(),
UserType.valueOf(request.getTipoUsuario().toUpperCase()),
request.getDocumentoIdentidad()
);
User newUser = registerUserUseCase.registerUser(command);
return ResponseEntity.status(HttpStatus.CREATED)
.body("Usuario registrado con ID: " + newUser.getId());
} catch (IllegalArgumentException e) {
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(e.getMessage());
}
}
Paso 9: Explorar Funcionalidades Principales
Con la autenticación completa, explora la plataforma:
Para Proveedores de Servicios (Profesional)
- Crear un Anuncio de Servicio: Navega a la pantalla "Publicar", selecciona categoría y subcategoría, ingresa detalles del servicio, precio y ubicación, envía para crear un anuncio activo
- Gestionar tus Anuncios: Ver todos tus servicios publicados, pausar/reactivar anuncios, editar precios y descripciones
Para Clientes
- Explorar Servicios: Explora categorías en la pantalla de inicio, ver subcategorías y anuncios activos, ver valoraciones y detalles del proveedor
- Solicitar un Servicio: Selecciona un anuncio, envía una solicitud de servicio con detalles, recibe propuestas de presupuesto vía chat
- Aceptar Propuestas: Revisar precios propuestos, aceptar para retener fondos en garantía, seguir la finalización del servicio
Solución de Problemas
El Backend no Inicia
Problema: Error de conexión a PostgreSQL
Caused by: org.postgresql.util.PSQLException: Connection refused
Solución: Verifica que PostgreSQL esté ejecutándose:
# Para Docker
docker ps | grep imirly_db
# Para instalación local
sudo systemctl status postgresql
La App Android no Conecta al Backend
Problema: Error de red o respuestas 404
Soluciones:
- Verifica que el backend esté ejecutándose en el puerto 8080
- Revisa el BASE_URL en RetrofitClient.kt
- Para dispositivos físicos, asegúrate de estar en la misma red WiFi
- Desactiva cualquier VPN que pueda bloquear conexiones locales
Base de Datos Ya Inicializada
Si ves:
✅ La base de datos ya tiene categorías. Saltando Seed.
Esto es normal - el seeder solo se ejecuta una vez. Para volver a ejecutarlo:
-- Conecta a la base de datos y trunca las tablas
TRUNCATE TABLE usuarios, categoria CASCADE;
Luego reinicia el backend.
Referencia Rápida
Puertos Predeterminados
- Backend API: http://localhost:8080
- PostgreSQL: localhost:5432
Credenciales de Base de Datos
- Database: imirly_db
- Username: user_imirly
- Password: password_imirly
Endpoints Clave de la API
- Auth: /api/v1/auth/register, /api/v1/auth/login
- Catálogo: /api/v1/catalog/categorias, /api/v1/catalog/subcategorias
- Anuncios: /api/v1/anuncios
- Contratos: /api/v1/solicitudes
- Mensajes: /api/v1/mensajes
Siguientes Pasos
Ahora que iMirly está ejecutándose localmente, profundiza en la arquitectura: