Variables de entorno

Las variables de entorno son la forma estándar de pasar configuración a tu aplicación en Kubiy. Esto incluye conexiones a bases de datos, API keys, flags de comportamiento y cualquier valor que cambie entre entornos.

Cómo configurar variables

Las variables se configuran en el wizard de deploy (Step 2) y también se pueden editar después desde la configuración de la app.

1. En la sección Environment Variables, haz clic en Add variable
2. Escribe el nombre de la variable (sin el prefijo $, solo el nombre)
3. Escribe el valor
4. Repite para cada variable necesaria

Los cambios en variables de entorno requieren un nuevo deploy para aplicarse.

Variables inyectadas por Kubiy

Kubiy siempre inyecta las siguientes variables en el proceso de tu aplicación. No necesitas definirlas — están disponibles automáticamente:

Variable	Valor	Disponible en
PORT	Puerto asignado al proceso	Todos los runtimes
APP_PORT	Alias de PORT	Todos los runtimes
KUBIY_DEPLOY_ID	ID único del deploy actual	Todos los runtimes
KUBIY_APP_ID	ID único de la aplicación	Todos los runtimes
ASPNETCORE_URLS	http://127.0.0.1:{PORT}	Solo .NET

aviso

No definas PORT o APP_PORT en tus variables de entorno — Kubiy las sobreescribirá con el valor correcto.

Cómo leer variables en cada runtime

Node.js

const port = process.env.PORT || 3000
const databaseUrl = process.env.DATABASE_URL
const apiKey = process.env.API_KEY

// Con validación
if (!process.env.DATABASE_URL) {
  throw new Error('DATABASE_URL is required')
}

Python

import os

port = int(os.environ.get('PORT', 8000))
database_url = os.environ['DATABASE_URL']  # falla si no existe
api_key = os.environ.get('API_KEY', '')     # devuelve '' si no existe

# Con python-dotenv (solo para desarrollo local)
# from dotenv import load_dotenv
# load_dotenv()

Go

import "os"

port := os.Getenv("PORT")
if port == "" {
    port = "8080"
}

databaseURL := os.Getenv("DATABASE_URL")
apiKey := os.Getenv("API_KEY")

.NET

// Vía Environment directamente
var port = Environment.GetEnvironmentVariable("PORT") ?? "5000";
var dbUrl = Environment.GetEnvironmentVariable("DATABASE_URL");

// Vía IConfiguration (recomendado en ASP.NET Core)
// Las env vars se cargan automáticamente en IConfiguration
var dbUrl = builder.Configuration["DATABASE_URL"];
var connectionString = builder.Configuration.GetConnectionString("Default");

En ASP.NET Core, las variables de entorno sobreescriben los valores de appsettings.json automáticamente cuando el nombre de la variable usa __ como separador de sección:

# Esta variable:
ConnectionStrings__Default=Server=...

# Sobreescribe esta sección en appsettings.json:
{
  "ConnectionStrings": {
    "Default": "..."
  }
}

Variables de entorno y secrets

Buenas prácticas

Haz:

• Almacena todos los secretos como variables de entorno en Kubiy
• Usa nombres descriptivos y en mayúsculas con guiones bajos (DATABASE_URL, STRIPE_SECRET_KEY)
• Documenta qué variables requiere tu app en el README del proyecto

No hagas:

• No subas .env files con secretos al repositorio
• No hardcodees API keys, passwords o URLs de base de datos en el código
• No uses console.log o print para imprimir el valor de variables que contienen secretos

Ejemplo de configuración típica

# Base de datos
DATABASE_URL=postgresql://user:password@host:5432/dbname

# Autenticación
JWT_SECRET=tu-clave-secreta-muy-larga
SESSION_SECRET=otra-clave-secreta

# Servicios externos
STRIPE_SECRET_KEY=sk_live_...
SENDGRID_API_KEY=SG....
S3_BUCKET=mi-bucket
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

# Comportamiento de la app
NODE_ENV=production
LOG_LEVEL=info
ALLOWED_ORIGINS=https://miapp.com

Desarrollo local

Para desarrollo local, usa un archivo .env (que no debes subir al repositorio). Agrega .env a tu .gitignore:

# .gitignore
.env
.env.local
.env.production

Puedes usar librerías como dotenv (Node.js), python-dotenv (Python), o godotenv (Go) para cargar el .env solo en desarrollo:

// Node.js — solo en desarrollo
if (process.env.NODE_ENV !== 'production') {
  require('dotenv').config()
}

# Python — solo en desarrollo
import os
if os.environ.get('ENV') != 'production':
    from dotenv import load_dotenv
    load_dotenv()

En producción (Kubiy), las variables de entorno ya están disponibles directamente y no necesitas dotenv.

Variables con valores multilínea

Si una variable contiene un valor multilínea (por ejemplo, un certificado PEM o una clave privada RSA), Kubiy las maneja correctamente. Introduce el valor con saltos de línea en el campo de texto.

consejo

Para certificados y claves privadas, considera codificarlos en Base64 para evitar problemas con saltos de línea:

# Localmente, codifica el archivo
base64 -w 0 private_key.pem

# En la app, decodifica
import base64, os
key = base64.b64decode(os.environ['PRIVATE_KEY_B64']).decode()

Precedencia de variables

Si defines una variable en Kubiy con el mismo nombre que una variable inyectada por el sistema, el comportamiento es:

• PORT, APP_PORT, ASPNETCORE_URLS: Kubiy siempre sobreescribe con el valor correcto
• KUBIY_DEPLOY_ID, KUBIY_APP_ID: Kubiy siempre sobreescribe
• Cualquier otra variable: el valor que defines en Kubiy es el que recibe la app

Actualizando variables sin redeploy

Actualmente, los cambios en variables de entorno requieren un nuevo deploy para que la aplicación los reciba. Kubiy no tiene hot-reload de variables.

Si necesitas cambiar una variable de entorno:

1. Ve a la configuración de la app
2. Edita o agrega la variable
3. Lanza un nuevo deploy

Acceso a variables de entorno en el Build Command

Las variables que configuras en Kubiy también están disponibles durante el build. Puedes usarlas en tu Build Command:

# Usando una variable definida en Kubiy durante el build
npm ci && NEXT_PUBLIC_API_URL=$API_URL npm run build

aviso

Las variables que contienen secretos estarán disponibles durante el build. El código del build Command puede imprimirlas en logs si no tienes cuidado. Evita hacer echo o imprimir valores de variables secretas en el Build Command.