Construcción automática (Railpack)

Construcción automática (Railpack) permite que Pier compile tu proyecto directamente desde un repositorio Git — sin Dockerfile, sin configuración de buildpack, sin andamiaje específico del lenguaje. Pier invoca la CLI de Railpack (el constructor de código abierto de Railway y el sucesor activo de Nixpacks), que se comunica con un demonio moby/buildkit y produce una imagen OCI que Pier ejecuta luego como cualquier otro servicio.

Antes de habilitarla

Requisitos del servidor

La construcción automática es considerablemente más pesada que las otras rutas de despliegue. Compilar código de usuario en el host tiene un perfil de recursos diferente al de ejecutar un contenedor preconstruido:

	Dockerfile / Compose / Imagen de Docker	Construcción automática (Railpack)
RAM mínima	512 MB	4 GB (8 GB para Rust)
Disco libre	unos pocos GB por stack	40+ GB (caché de BuildKit)
Primer despliegue	segundos	1–10 minutos

Si tu VPS tiene menos de 4 GB de RAM, usa en su lugar la fuente Dockerfile o Imagen de Docker — de lo contrario, el formulario de creación de recursos mostrará una advertencia contundente, y la construcción muy probablemente se autoeliminará por OOM o eliminará otro proceso en el host.

Lenguajes compatibles

Railpack detecta automáticamente el tipo de proyecto a partir de archivos marcadores comunes. No se necesita ninguna configuración para ninguno de estos:

Lenguaje / framework	Detectado a partir de
Node.js / Bun / Deno	package.json, bun.lockb, deno.json
Python	requirements.txt, pyproject.toml, Pipfile
Go	go.mod
Rust	Cargo.toml
PHP	composer.json
Java	pom.xml, build.gradle
Ruby	Gemfile
Elixir	mix.exs
Vite / Astro / Create React App	configuración del bundler + directorio de salida de la construcción

Cómo funciona por dentro

1. Clonar — Pier clona la rama configurada en un directorio temporal usando la misma maquinaria git que las demás fuentes Git (pública, clave de despliegue o aplicación de GitHub).
2. Detectar + planificar — railpack build analiza el árbol de código fuente y produce un grafo BuildKit LLB. A diferencia de los Dockerfiles por capas, el grafo es totalmente paralelo — los pasos independientes se ejecutan de forma concurrente, y el almacenamiento en caché es direccionable por contenido en lugar de línea por línea.
3. Construir — BuildKit ejecuta el grafo contra el contenedor del demonio iniciado por install.sh, produciendo una imagen OCI etiquetada como pier-railpack/<service-id>:<deploy-id>.
4. Ejecutar — Pier sintetiza un pequeño docker-compose.yml que apunta a la nueva imagen y lo entrega a la misma ruta docker compose up utilizada por las construcciones de Dockerfile. Las etiquetas de Traefik, el SSL automático, la asignación de puertos y la red del stack se reutilizan por completo — solo el paso de construcción es nuevo.

Configuración personalizada

Para proyectos que necesitan ajustes, coloca un railpack.json en la raíz del repositorio — Railpack lo detecta automáticamente y Pier no necesita saber de él. Ejemplo:

{
  "providers": ["node"],
  "buildAptPackages": ["libpq-dev"],
  "deploy": {
    "startCommand": "node dist/server.js"
  }
}

La referencia completa se encuentra en railpack.com/configuration/file.

Parámetros de ajuste

Tres variables de entorno (definidas en la unidad de systemd o antes de install.sh) y una pestaña de la interfaz controlan el comportamiento de la construcción automática:

• PIER_RAILPACK_MAX_PARALLEL_BUILDS=N — limita las construcciones concurrentes (valor por defecto 1). También editable desde Configuración → Construcción automática (Railpack) en el panel.
• PIER_BUILDKIT_MEMORY=4g — límite de RAM para el contenedor de moby/buildkit (valor por defecto 4g).
• PIER_SKIP_RAILPACK=1 — omite el aprovisionamiento por completo. La tarjeta permanece en la interfaz, pero los intentos de construcción mostrarán un mensaje claro de “railpack binary not found”.

Solución de problemas

railpack binary not found in PATH El host se instaló con PIER_SKIP_RAILPACK=1, o install.sh no pudo descargar el binario de la versión. Vuelve a ejecutar install.sh sin el indicador de omisión, o instala el binario manualmente desde github.com/railwayapp/railpack/releases en /usr/local/bin/railpack.

build failed (exit 137) — eliminación por OOM Tu construcción superó la RAM disponible. Actualiza el VPS a 4 GB o más (8 GB para Rust), o restringe BuildKit con un PIER_BUILDKIT_MEMORY más bajo para que falle rápido en lugar de privar de recursos a los procesos vecinos. La interfaz de Pier muestra este estado con un banner rojo cuando el host tiene menos de 4 GB.

Construcciones atascadas en cola Pier limita las construcciones paralelas a 1 por defecto para proteger el host. Si varios usuarios despliegan al mismo tiempo, los demás esperan. Aumenta el límite en Configuración → Construcción automática (Railpack) si tu host tiene RAM disponible.

Could not detect language Railpack no encontró un archivo marcador que reconozca. Añade el archivo de bloqueo esperado (p. ej., package-lock.json para proyectos npm), coloca un railpack.json que declare providers, o recurre a la fuente Dockerfile.

Relacionado

• Desde un Dockerfile — control total sobre la construcción, a cambio de tener que escribir uno
• Desde una imagen de Docker — despliega una imagen preconstruida desde cualquier registro, sin construcción en el host en absoluto
• Desde Docker Compose — stacks multiservicio