Surqo Environment Variables Reference

Surqo’s backend configuration is managed entirely through environment variables loaded by Pydantic Settings (pydantic-settings). On startup, app/config.py reads every variable from the process environment (or a .env file at the project root) and validates them with strict types — a missing required variable raises an error immediately rather than failing silently at runtime. Copy backend/.env.example to backend/.env and fill in the sections below.

Backend
Frontend

LLM Provider

Set LLM_PROVIDER to choose the active AI backend. Groq is the recommended default — it is free up to 14,400 requests per day and delivers sub-second latency with Llama 3.3 70B.

# Primary provider (recommended, free)
LLM_PROVIDER=groq
GROQ_API_KEY=gsk_...
GROQ_MODEL=llama-3.3-70b-versatile
LLM_MAX_TOKENS=1024

# Fallback provider (paid, optional)
ANTHROPIC_API_KEY=sk-ant-...
LLM_MODEL=claude-haiku-4-5-20251001

# Local development (no network needed)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3

Only variables for the active provider need to be populated. The llm_service.py multi-provider router selects the correct client at startup based on LLM_PROVIDER.

Supabase (Database + Auth)

Surqo uses Supabase for both PostgreSQL (via asyncpg) and JWT authentication (ES256, validated against the project’s JWKS endpoint). The SUPABASE_KEY must be the Service Role key, not the anon key.

SUPABASE_URL=https://<project>.supabase.co
SUPABASE_KEY=<service-role-key>
SUPABASE_JWK_X=<jwk-x-coordinate>
SUPABASE_JWK_Y=<jwk-y-coordinate>
SUPABASE_JWK_KID=<key-id>
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/postgres

The three SUPABASE_JWK_* variables are used to reconstruct the ES256 public key in memory at startup (@lru_cache) so JWT verification never makes a network round-trip.

Upstash Redis

Redis serves two purposes: caching Open-Meteo climate responses (TTL 1 h) to avoid redundant API calls, and enforcing the 30-minute alert cooldown between repeated threshold violations per farm.

REDIS_URL=rediss://default:<password>@<host>.upstash.io:6379
CACHE_TTL_CLIMATE=3600
CACHE_TTL_ANALYSIS=3600

The rediss:// scheme (with double s) enables TLS — required by Upstash. The cache service degrades gracefully: if Redis is unreachable the backend continues to work, just without caching.

HiveMQ Cloud (MQTT)

The MQTT consumer subscribes to surqo/farms/+/sensors on startup and processes incoming sensor payloads from ESP32 nodes and the IoT simulator. Leave HIVEMQ_HOST empty to disable the consumer in development.

HIVEMQ_HOST=<cluster>.s1.eu.hivemq.cloud
HIVEMQ_PORT=8883
HIVEMQ_USERNAME=<username>
HIVEMQ_PASSWORD=<password>
MQTT_TOPIC_PREFIX=surqo

Port 8883 is TLS-encrypted MQTT — the same port used by the ESP32 firmware and the IoT simulator.

Resend (Email)

Alert emails are sent through the Resend API when sensor readings cross configured thresholds. The FROM_EMAIL address must be a verified sender domain in your Resend account.

RESEND_API_KEY=re_...
FROM_EMAIL=alertas@surqo.io

Application

APP_ENV=development  # or: production
CORS_ORIGINS=["http://localhost:3000","https://surqo.vercel.app"]
LOGFIRE_TOKEN=       # optional — leave empty to disable structured observability

Setting APP_ENV=production disables the Swagger UI (/docs) and ReDoc (/redoc) endpoints. CORS_ORIGINS accepts a JSON array of allowed origins.

The Next.js frontend reads four public variables from .env.local. All four use the NEXT_PUBLIC_ prefix and are inlined into the client bundle at build time — do not put secrets here.

.env.local

NEXT_PUBLIC_API_URL=https://surqo-api.fly.dev
NEXT_PUBLIC_WS_URL=wss://surqo-api.fly.dev
NEXT_PUBLIC_SUPABASE_URL=https://tu-proyecto.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_...

For local development, replace https://surqo-api.fly.dev with http://localhost:8000 and wss:// with ws://. The NEXT_PUBLIC_SUPABASE_ANON_KEY is the anon/public key from Supabase — safe to expose in the browser because Row Level Security policies enforce access control at the database level.

Where to Obtain Each Credential

Variable	Source
`GROQ_API_KEY`	console.groq.com → API Keys
`ANTHROPIC_API_KEY`	console.anthropic.com → API Keys
`SUPABASE_URL` + `SUPABASE_KEY`	Supabase Dashboard → Settings → API
`SUPABASE_JWK_X` / `SUPABASE_JWK_Y` / `SUPABASE_JWK_KID`	Supabase → Settings → API → JWT Settings → JWKS
`DATABASE_URL`	Supabase → Settings → Database → Session Pooler (IPv4)
`REDIS_URL`	console.upstash.com → Redis → Connect
`HIVEMQ_HOST` / `HIVEMQ_USERNAME` / `HIVEMQ_PASSWORD`	console.hivemq.cloud → Cluster Settings
`RESEND_API_KEY`	resend.com → API Keys

Never commit .env or .env.local files containing real credentials. The repository’s .gitignore already excludes both files. If you accidentally commit a secret, rotate the affected key immediately from its provider dashboard.

Introducción

Arquitectura

Instalación y Configuración

Firmware ESP32

Despliegue

Surqo Environment Variables Reference

LLM Provider

Supabase (Database + Auth)

Upstash Redis

HiveMQ Cloud (MQTT)

Resend (Email)

Application

Where to Obtain Each Credential

Build docs developers (and LLMs) love

Introducción

Arquitectura

Instalación y Configuración

Firmware ESP32

Despliegue

Documentation Index

​LLM Provider

​Supabase (Database + Auth)

​Upstash Redis

​HiveMQ Cloud (MQTT)

​Resend (Email)

​Application

​Where to Obtain Each Credential

Build docs developers (and LLMs) love

LLM Provider

Supabase (Database + Auth)

Upstash Redis

HiveMQ Cloud (MQTT)

Resend (Email)

Application

Where to Obtain Each Credential