Skip to main content
[ PIER ]

Dockerfile

Pega un Dockerfile (o apunta a Git repo) — Pier construye y envía.

Application #docker#build#dockerfile

Trae tu propio Dockerfile y Pier construye la imagen, corre el contenedor y lo cablea. Pega el Dockerfile inline o apunta a un Git repo conteniendo uno. Útil cuando necesitas control de build completo — paquetes de sistema exóticos, builds multi-stage, entrypoints custom — que auto-builders (Railpack) no pueden expresar.

Desplegar con Pier

  1. 1 Abre el panel de Pier y haz clic en Add service.
  2. 2 Elige Dockerfile en la lista de plantillas.
  3. 3 Elige la versión, asigna un nombre al servicio y Pier provisionará automáticamente el contenedor, el almacenamiento y los puertos.
  4. 4 Vincula un dominio si quieres HTTPS. Traefik genera el certificado de Let's Encrypt automáticamente.

¿Qué es la plantilla Dockerfile?

Trae tu propio Dockerfile. O pégalo directamente en la UI Pier (bueno para contenedores inline diminutos) o apunta a un repositorio Git conteniendo uno (bueno para todo lo que vas a iterar). Pier construye la imagen con BuildKit, corre el contenedor, lo adjunta a su red Traefik-fronted para HTTPS, y gestiona env / volúmenes / logs / ciclo de vida.

Usa esta plantilla cuando necesitas control explícito sobre el build — builds multi-stage, base images distroless, paquetes de sistema, entrypoints custom, build-time secrets — que auto-builders como Railpack no exponen. Dockerfiles hand-tuned consistentemente ganan a auto-builders en tamaño de imagen, control de capa y superficie de revisión de seguridad para la app específica que apuntan.

Cómo lo despliega Pier

Proveés contenido Dockerfile (textarea) o Git URL. Pier clona (si modo Git) y corre docker buildx build con BuildKit en el host, produciendo una imagen OCI stored localmente. El contenedor inicia con tus puertos, env vars y volúmenes configurados.

Caché de capas BuildKit persiste entre builds — builds incrementales típicos terminan en segundos. Build secrets (npm tokens, auth de registry privado) van junto vía el mecanismo de secret mount de BuildKit sin hornearse en la imagen final.

Adjunta un dominio custom en Pier para HTTPS vía Traefik. Click Redeploy para triggear un rebuild (o cablea un Git webhook para push-to-deploy).

Cuándo NO usar Dockerfile

Para “tengo source, sin Dockerfile, quiero contenedor” — usa Railpack. Para “tengo imagen pre-built en un registry” — usa Docker Image. Para “tengo stack multi-contenedor” — usa Docker Compose. Para servicios Pier nativos con backups gestionados y version upgrades (PostgreSQL, Gitea, Grafana, …), elige la plantilla dedicada. Dockerfile es la respuesta correcta cuando necesitas control completo sobre cómo se construye tu app single-container.

Características clave

Pega-inline o Git URL

Dos modos de input — pega un Dockerfile directo en la UI, o dale a Pier un Git repo URL y construye desde el Dockerfile en el root del repo (o path especificado).

Control de build completo

Builds multi-stage, ARG / ENV / COPY / RUN — cualquier cosa que Docker pueda hacer, esta plantilla construye.

BuildKit-powered

Caché de capas entre rebuilds, etapas paralelas, build secrets. Iteración más rápida que classic Docker build.

Build args + env vars

Pasa ARGs build-time y ENV runtime separadamente. Build secrets quedan fuera de la imagen final.

HTTPS vía Traefik

Adjunta un dominio en Pier; el contenedor corriendo se fronts con Let's Encrypt TLS automáticamente.

Redeploy por webhook

Cuando apuntado a un Git repo, configura un webhook para que cada push triggee rebuild y redeploy.

Casos de uso

Cuando Railpack no es suficiente

Necesitas un paquete de sistema, base image custom, build multi-stage o truco que Railpack no auto-detecta. Escribe el Dockerfile.

Apps legacy con Dockerfiles hand-tuned

Tu Dockerfile existente refleja años de tuning de build — manténlo, envíalo por Pier.

Control estricto de imagen

Quieres una base image específica (distroless, scratch, Alpine), usuario específico, orden de capa específico — Dockerfile es la única vía.

Builds con secrets

BuildKit secrets mantienen credenciales fuera de la imagen final. La plantilla Dockerfile los soporta; Railpack e Image no.

Contenedores utility single-file

Scripts diminutos, init containers, sidecars — pega un Dockerfile de 10 líneas inline, deploy.

Ejemplos de código

Dockerfile Node.js mínimo (pegar inline) dockerfile 
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
Build Go multi-stage (~10 MB image) dockerfile 
FROM golang:1.23 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /app/server ./cmd/server

FROM gcr.io/distroless/static-debian12
COPY --from=builder /app/server /server
EXPOSE 8080
USER nonroot:nonroot
ENTRYPOINT ["/server"]
Python con paquetes de sistema dockerfile 
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
      ffmpeg libsndfile1 \
  && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
BuildKit secret (token npm registry privado) dockerfile 
# syntax=docker/dockerfile:1
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN --mount=type=secret,id=npm_token \
    export NPM_TOKEN=$(cat /run/secrets/npm_token) && \
    echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc && \
    npm ci --omit=dev && \
    rm ~/.npmrc
COPY . .
CMD ["node", "server.js"]

Comparativa

vs Railpack (este catálogo) Railpack auto-detecta y escribe un build plan por ti. Dockerfile es cuando necesitas control explícito o la detección Railpack no es correcta. Muchos equipos empiezan con Railpack y mueven a Dockerfile servicios específicos que lo necesitan.
vs Docker Image (este catálogo) Docker Image corre una imagen prebuilt. Dockerfile construye una imagen desde source. Usa Image cuando CI construye por ti; Dockerfile cuando quieres que Pier construya.
vs Docker Compose (este catálogo) Compose orquesta múltiples contenedores. Dockerfile construye y corre UN. Usa Compose para stacks multi-servicio (también puede construir desde Dockerfiles per service).
vs Buildpacks (CNB) CNB es el spec detrás de builders style Heroku/Paketo. Railpack es la alternativa moderna más simple en Pier. Dockerfile es el escape hatch de nivel más bajo.

Preguntas frecuentes

¿Construir desde Git repo URL o pegar inline — cuál?
Inline para contenedores diminutos test y one-offs. Git URL para todo lo que vas a iterar — push a repo, redeploy.
¿Qué tan grande puede ser mi context?
El context de build se sube a Pier — manténlo modesto. .dockerignore agresivamente. Contexts grandes lentos los builds.
¿Caché BuildKit?
Caché de capas BuildKit vive en el host Pier. Builds repetidos reusan capas basado en hashes COPY. Típicamente 80%+ cache hit en cambios incrementales de código.
¿Builds multi-arch?
Pier builds para la arquitectura host. Para imágenes multi-arch, build en CI (donde puedes buildx) y ship vía plantilla Docker Image.
¿Base images privadas?
Agrega credenciales de registry en Pier Settings → Registries — se usan para pulls FROM y pushes de imagen.
¿Cómo funcionan los build secrets?
Agrega un secret en UI Pier, referénciálo en el Dockerfile vía --mount=type=secret,id=NAME. BuildKit lo mantiene fuera de las capas finales.
¿Redeploys webhook?
Si usas modo Git URL, genera un webhook URL en Pier y agrégalo a tu Git host. Cada push triggea rebuild y rollout.

Servicios relacionados

Desplegar en tu VPS

Trae tu propio Dockerfile y Pier construye la imagen, corre el contenedor y lo cablea. Pega el Dockerfile inline o apunta a un Git repo conteniendo uno. Útil cuando necesitas control de build completo — paquetes de sistema exóticos, builds multi-stage, entrypoints custom — que auto-builders (Railpack) no pueden expresar.

Desplegar este servicio →