Referencia de Stack JSON

El archivo stack.json es el nucleo de cada proyecto en Swisblade. Define tus servicios, sus dependencias y como se conectan. Colocalo en la raiz de tu repositorio.

Formato

{
  "name": "my-project",
  "services": {
    "service-name": {
      "type": "app",
      "source": { "repo": "github.com/you/repo.git", "ref": "main" },
      "runtime": "node",
      "port": 3000,
      "public": true,
      "needs": ["postgres", "redis"],
      "connects_to": ["worker"],
      "requires_env": ["API_KEY", "STRIPE_SECRET"]
    }
  }
}

Campos de nivel superior

Campo	Tipo	Requerido	Descripcion
`name`	string	Si	Nombre del proyecto. Se usa para display y generacion de slug.
`version`	number	No	Version del esquema (para uso futuro).
`services`	object	Si	Mapa de nombre de servicio a definicion de servicio.

Definicion de servicio

Cada clave en services es un nombre de servicio (usado para DNS, nombres de variables de entorno y logging). Los nombres de servicio deben ser alfanumericos en minusculas con guiones.

Campos comunes

Campo	Tipo	Default	Descripcion
`type`	string	—	`"app"`, `"custom"` o `"database"`. Requerido.
`port`	number	—	Puerto interno en el que escucha el servicio.
`connects_to`	string[]	`[]`	Otros servicios con los que este se comunica.
`requires_env`	string[]	`[]`	Variables de entorno que deben existir en la boveda antes de desplegar. Opcional.

Servicios de aplicacion (`type: "app"`)

Los servicios de aplicacion se compilan desde tu codigo fuente.

Campo	Tipo	Requerido	Descripcion
`source`	object	Si	`{ repo, ref }` para repos git, o `{ path }` para monorepos locales.
`source.repo`	string	—	URL del repositorio Git (por ejemplo, `github.com/you/api.git`). Requerido para source remoto.
`source.ref`	string	—	Branch, tag o commit SHA a desplegar. Requerido para source remoto.
`source.path`	string	—	Ruta relativa al directorio del servicio. Requerido para source local.
`runtime`	string	Si	`"node"`, `"python"` o `"java"`. Se usa para auto-instrumentacion.
`port`	number	Si	Puerto en el que tu aplicacion escucha dentro del contenedor.
`public`	boolean	No	Exponer este servicio con una URL publica HTTPS.
`needs`	string[]	No	Infraestructura compartida a aprovisionar. Ver needs.
`requires_env`	string[]	No	Variables de entorno que el servicio requiere. Se validan contra la boveda antes de desplegar.
`auth`	object	No	Pone un login delante de este servicio. Ver Autenticacion.
`custom_domain`	string	No	Servi este servicio en tu propio dominio, ademas de la URL gratuita. Ver Dominios Propios. Requiere `public: true`.
`image`	string	No	Override: usar esta imagen Docker en lugar de compilar.

Servicios custom (`type: "custom"`)

Imagenes Docker pre-compiladas (por ejemplo, RabbitMQ, Elasticsearch).

Campo	Tipo	Requerido	Descripcion
`image`	string	Si	Imagen Docker (por ejemplo, `rabbitmq:3-management`).
`port`	number	No	Puerto interno.
`protocol`	string	No	Protocolo para generacion de URL (default: `"http"`).
`version`	string	No	Tag de version de la imagen.

Servicios de base de datos (`type: "database"`)

Los servicios de base de datos nombrados corren en la infraestructura compartida de la plataforma con sus propias credenciales. Usalos cuando un servicio necesita una base de datos separada (por ejemplo, una DB de analytics distinta de la principal).

Campo	Tipo	Requerido	Descripcion
`engine`	string	Si	`"postgres"` o `"mysql"`.

{
  "analytics-db": {
    "type": "database",
    "engine": "mysql"
  }
}

Los servicios app se conectan a servicios de base de datos via connects_to. La variable de entorno inyectada sigue el patron DATABASE_URL_{NAME}:

{
  "worker": {
    "type": "app",
    "connects_to": ["analytics-db"]
  }
}

Esto inyecta DATABASE_URL_ANALYTICS_DB=mysql://proj_xxx_analytics_db:password@platform-mysql:3306/proj_xxx_analytics_db.

Cada base de datos nombrada obtiene su propio usuario y esquema, aislados de la base de datos por defecto aprovisionada por needs.

nota

Las bases de datos nombradas cuentan para el limite de bases de datos de tu plan. El tier gratuito permite 2 bases de datos por stack (incluyendo la por defecto de needs).

`needs`

El array needs declara infraestructura compartida que Swisblade aprovisiona y gestiona por ti. Las credenciales de conexion se inyectan automaticamente.

"needs": ["postgres", "redis", "rabbitmq"]

Valor	Que obtienes	Variable de entorno inyectada
`"postgres"`	Base de datos PostgreSQL 16 con usuario dedicado	`DATABASE_URL`
`"mysql"`	Base de datos MySQL 8 con usuario dedicado	`DATABASE_URL`
`"redis"`	Redis 7 con prefijo de clave aislado	`REDIS_URL` + `REDIS_KEY_PREFIX`
`"rabbitmq"`	RabbitMQ vhost con usuario dedicado	`MQ_URL`

Cada servicio obtiene sus propias credenciales, aisladas de otros proyectos. Tambien puedes usar la forma de objeto para nombres personalizados:

"needs": [{ "type": "postgres", "name": "analytics-db" }]

`connects_to`

Declara la comunicacion servicio a servicio dentro del mismo proyecto. Swisblade inyecta la URL interna del servicio destino como variable de entorno.

{
  "api": {
    "type": "app",
    "connects_to": ["worker", "notifications"]
  }
}

Esto inyecta:

WORKER_URL=http://worker:8080
NOTIFICATIONS_URL=http://notifications:3000

Las URLs usan el DNS interno de Docker: los servicios pueden comunicarse entre si por nombre dentro del mismo proyecto.

Cuando connects_to apunta a un servicio type: "database", se inyecta un string de conexion en su lugar:

{
  "api": { "type": "app", "connects_to": ["analytics-db"] },
  "analytics-db": { "type": "database", "engine": "postgres" }
}

Esto inyecta DATABASE_URL_ANALYTICS_DB=postgresql://... con credenciales dedicadas.

`requires_env`

Validacion pre-deploy opcional. Lista los nombres de variables de entorno que deben existir en la boveda del proyecto antes de que comience el despliegue. Si falta alguna, el deploy falla inmediatamente con un error claro.

"requires_env": ["STRIPE_KEY", "WEBHOOK_SECRET"]

Todas las variables almacenadas en la boveda se inyectan automaticamente en todos los servicios al momento del despliegue — no necesitas declararlas en stack.json. El campo requires_env es una red de seguridad: asegura que las variables criticas esten presentes antes de que los contenedores arranquen.

Si no declaras requires_env, el deploy procede sin verificar. Si falta una variable, tu aplicacion fallara en runtime en lugar de en tiempo de despliegue.

Consulta Variables de Entorno para mas detalles sobre la gestion de la boveda.

Ejemplo completo

Un proyecto multi-servicio con una API, worker, base de datos, cache y cola de mensajes:

{
  "name": "ecommerce",
  "services": {
    "api": {
      "source": { "repo": "github.com/myorg/api.git", "ref": "v2.1.0" },
      "type": "app",
      "runtime": "node",
      "port": 3000,
      "public": true,
      "needs": ["postgres", "redis"],
      "connects_to": ["worker"],
      "requires_env": ["STRIPE_KEY", "WEBHOOK_SECRET"]
    },
    "worker": {
      "source": { "repo": "github.com/myorg/worker.git", "ref": "v1.4.0" },
      "type": "app",
      "runtime": "node",
      "port": 8080,
      "needs": ["rabbitmq"],
      "connects_to": ["analytics-db"]
    },
    "analytics-db": {
      "type": "database",
      "engine": "mysql"
    }
  }
}

Ejemplo monorepo

Si todos tus servicios viven en un mismo repositorio, usa source.path en lugar de source.repo:

{
  "name": "monorepo-app",
  "services": {
    "api": {
      "source": { "path": "packages/api" },
      "type": "app",
      "runtime": "java",
      "port": 3000,
      "public": true,
      "needs": ["postgres"]
    },
    "worker": {
      "source": { "path": "packages/worker" },
      "type": "app",
      "runtime": "java",
      "port": 3000,
      "needs": ["rabbitmq"]
    }
  }
}

Cada path es relativo a la raiz del proyecto. Cada directorio de servicio debe contener su propio Dockerfile (o ser auto-detectable por Nixpacks).

Visual Builder NUEVO

No quieres escribir JSON a mano? Usa el Visual Builder en el dialogo de Crear Proyecto. Te permite:

Agregar servicios app (elige runtime, puerto, repo git)
Agregar contenedores (especifica una imagen Docker directamente)
Agregar servicios de base de datos (PostgreSQL o MySQL)
Activar infraestructura (Postgres, MySQL, Redis, RabbitMQ) con nombres personalizados opcionales
Conectar servicios via connects_to
Declarar variables de entorno requeridas (requires_env) para validacion pre-deploy
Activar acceso publico por servicio

El builder muestra los limites de tu plan en tiempo real (servicios y bases de datos por stack) y valida tu configuracion sobre la marcha. Genera exactamente el mismo stack.json que escribirias manualmente, sin perder ninguna funcionalidad.

Edicion desde el dashboard

Tambien puedes editar stack.json directamente desde el dashboard en Configuracion del Proyecto -> Stack Contract. Los cambios activan un nuevo despliegue automaticamente.

Validacion

Swisblade valida tu stack.json antes de cada despliegue:

Todas las URLs de source.repo deben ser accesibles (con PAT si son privadas)
Todas las referencias en connects_to deben apuntar a servicios definidos en el mismo archivo
Todos los valores de needs deben ser tipos soportados
Todas las variables listadas en requires_env deben existir en la boveda del proyecto antes de desplegar

Formato​

Campos de nivel superior​

Definicion de servicio​

Campos comunes​

Servicios de aplicacion (type: "app")​

Servicios custom (type: "custom")​

Servicios de base de datos (type: "database")​

needs​

connects_to​

requires_env​

Ejemplo completo​

Ejemplo monorepo​

Visual Builder NUEVO​

Edicion desde el dashboard​

Validacion​