Variables de Entorno y Secretos

Las variables de entorno son el mecanismo estandar para inyectar configuracion en aplicaciones sin hardcodear valores en el codigo. Dokploy proporciona una interfaz integrada para gestionarlas de forma segura.

Agregar variables a una aplicacion

Desde el panel de Dokploy, navega a tu aplicacion y selecciona la pestana Environment.

Puedes agregar variables de dos formas:

Formato clave-valor

En el editor de variables, escribe una variable por linea con formato CLAVE=valor:

DATABASE_URL=postgresql://user:pass@db:5432/myapp
REDIS_URL=redis://redis:6379
NODE_ENV=production
PORT=3000

Desde archivo .env

Puedes pegar directamente el contenido de un archivo .env en el editor. Dokploy acepta el formato estandar:

# Configuracion de la aplicacion
APP_NAME=mi-app
APP_SECRET=un-secreto-largo-y-aleatorio

# Base de datos
DB_HOST=db
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=password-seguro
DB_NAME=mi_base

Despues de guardar los cambios, Dokploy te preguntara si deseas redesplegar la aplicacion para que las variables tomen efecto.

Tipos de variables: build-time vs runtime

Dokploy distingue entre dos momentos en que las variables estan disponibles.

Variables de runtime

Son las variables por defecto. Estan disponibles cuando el contenedor esta corriendo:

# Disponible solo en runtime
API_KEY=sk-live-abc123
JWT_SECRET=mi-secreto-jwt

Dentro de tu aplicacion accedes a ellas normalmente:

// Node.js
const apiKey = process.env.API_KEY;

# Python
import os
api_key = os.environ.get("API_KEY")

// Go
apiKey := os.Getenv("API_KEY")

Variables de build-time

Si necesitas variables durante la construccion de la imagen (por ejemplo para npm run build que necesita una URL de API), activa la opcion Build Args en la configuracion de la variable.

En un Dockerfile, declaralas con ARG:

FROM node:20-alpine

ARG VITE_API_URL
ARG VITE_APP_NAME

WORKDIR /app
COPY package.json bun.lockb ./
RUN npm install

COPY . .
RUN VITE_API_URL=$VITE_API_URL npm run build

FROM nginx:alpine
COPY --from=0 /app/dist /usr/share/nginx/html

En el panel de Dokploy, agrega la variable y marca la casilla Build para que este disponible como argumento de build.

Variables de entorno para bases de datos

Cuando creas una base de datos en Dokploy, el sistema genera automaticamente las credenciales. Puedes consultarlas en la pestana Environment del servicio de base de datos.

PostgreSQL

Dokploy genera estas variables al crear un servicio PostgreSQL:

POSTGRES_USER=postgres
POSTGRES_PASSWORD=<generado-automaticamente>
POSTGRES_DB=mi_base

La URL de conexion desde otra aplicacion en el mismo proyecto:

DATABASE_URL=postgresql://postgres:<password>@<nombre-servicio>:5432/mi_base

MySQL / MariaDB

MYSQL_ROOT_PASSWORD=<generado>
MYSQL_DATABASE=mi_base
MYSQL_USER=app_user
MYSQL_PASSWORD=<generado>

Redis

REDIS_URL=redis://<nombre-servicio>:6379

Si configuraste contrasena:

REDIS_URL=redis://default:<password>@<nombre-servicio>:6379

Referenciar variables entre servicios

Cuando tu aplicacion necesita conectarse a una base de datos dentro del mismo proyecto, usa el nombre del servicio de Dokploy como hostname.

Por ejemplo, si tienes:

• Aplicacion: mi-api
• Base de datos PostgreSQL: mi-postgres

En las variables de mi-api configura:

DATABASE_URL=postgresql://postgres:password@mi-postgres:5432/mydb

El nombre mi-postgres se resuelve internamente gracias a la red Docker que Dokploy configura por proyecto.

Verificar conectividad

Usa la terminal integrada de Dokploy para verificar que la resolucion de nombres funciona:

# Desde la terminal del contenedor de tu app
ping mi-postgres
nslookup mi-postgres

Variables de entorno en Docker Compose

Para aplicaciones desplegadas con Docker Compose, las variables se gestionan de forma diferente.

Usando la seccion environment

version: "3.8"
services:
  api:
    build: .
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://postgres:pass@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=pass
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

volumes:
  pgdata:

Usando archivo .env con Docker Compose

Dokploy permite definir un archivo .env que Docker Compose lee automaticamente. En la pestana Environment del servicio Compose, agrega las variables:

POSTGRES_PASSWORD=super-secreto
APP_SECRET=otro-secreto

Y referencia en tu docker-compose.yml:

services:
  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

  api:
    build: .
    environment:
      - APP_SECRET=${APP_SECRET}
      - DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@db:5432/app

Usando env_file

Tambien puedes montar archivos .env directamente:

services:
  api:
    build: .
    env_file:
      - .env.production

En este caso, el archivo debe existir en el repositorio o montarse como volumen.

Buenas practicas

No hardcodear secretos

Nunca pongas secretos directamente en el codigo ni en archivos commiteados:

# MAL - en el codigo
const dbUrl = "postgresql://user:password@host:5432/db";

# BIEN - variable de entorno
const dbUrl = process.env.DATABASE_URL;

Agrega .env a tu .gitignore:

.env
.env.local
.env.production

Usar nombres descriptivos

# MAL
DB=postgres://...
S=mi-secreto

# BIEN
DATABASE_URL=postgres://...
JWT_SIGNING_SECRET=mi-secreto

Separar por contexto

Usa prefijos para organizar variables:

# Base de datos
DB_HOST=postgres
DB_PORT=5432
DB_NAME=app

# Cache
CACHE_HOST=redis
CACHE_PORT=6379
CACHE_TTL=3600

# Servicios externos
SMTP_HOST=smtp.ejemplo.com
SMTP_PORT=587
SMTP_USER=[email protected]

Valores por defecto en el codigo

Tu aplicacion debe funcionar con valores por defecto sensatos para desarrollo:

const config = {
  port: parseInt(process.env.PORT || "3000"),
  nodeEnv: process.env.NODE_ENV || "development",
  logLevel: process.env.LOG_LEVEL || "info",
};

Rotar secretos periodicamente

1. Genera el nuevo valor del secreto
2. Actualiza la variable en Dokploy
3. Redespliega la aplicacion
4. Verifica que funciona correctamente
5. Revoca el valor anterior si aplica (API keys, tokens)

---

Anterior: Capitulo 15: Redes y Puertos | Siguiente: Capitulo 17: Roles y Permisos —>