Local Development

Local development uses dnsmasq for wildcard DNS resolution and hot-reload for all services.

DNS Setup (dnsmasq)

# Install dnsmasq
sudo apt install dnsmasq    # Linux
brew install dnsmasq         # macOS

# Configure wildcard for *.fimula.local
echo "address=/fimula.local/127.0.0.1" | sudo tee /etc/dnsmasq.d/fimula.conf
sudo systemctl restart dnsmasq

Service URLs

Service	URL
Frontend	`http://ubios.fimula.local`
API	`http://api.ubios.fimula.local`
Agno	`http://agno.fimula.local:8001` (internal)
LiteLLM Proxy	`http://ubios.fimula.local:4000`
Dify	`http://dify.fimula.local:5001`
Metabase	`http://metabase.fimula.local:3000`
MinIO	`http://minio.fimula.local:9001`
Mailpit	`http://mail.fimula.local:8025`
Uptime Kuma	`http://ubios.fimula.local:3001`
Dozzle	`http://ubios.fimula.local:8080`

Hot Reload

All three application services support hot reload:

Service	How it works	Trigger
Nuxt (app)	Vite HMR	File save in `app/`
Laravel (api)	Octane auto-reloads	File save in `api/`
Agno (agno)	Uvicorn `--reload`	File save in `services/agno/`

Changes appear within 1–2 seconds. No manual restart needed.

Debugging Per Service

Laravel

# Tinker REPL
docker exec -it ubios_api php artisan tinker

# Tail logs
docker compose -f docker-compose.dev.yml logs -f api

# Check routes
docker exec -it ubios_api php artisan route:list

Nuxt

# Shell access
docker exec -it ubios_app sh

# Check build errors
docker compose -f docker-compose.dev.yml logs -f app

Agno

# Shell access
docker exec -it ubios_agno bash

# Health check
curl http://ubios.fimula.local:8001/health

# Test a query directly
curl -X POST http://ubios.fimula.local:8001/query \
  -H "X-Agno-Key: dev-key" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is our revenue?", "user_id": "test"}'

PostgreSQL

# Direct query
docker exec -it ubios_api bash -c '
  PGPASSWORD=331331331 psql -U postgres -h ubios_postgres -d ubios
'

# Check schema
\d ubios_semantic.entities
\d ubios_config.llm_routing

Info

If you don't want to set up dnsmasq, use the IP Testing approach instead — it works on any machine with just an IP address.