Instalación manual

Este camino instala la misma base de Opfield que el instalador público, pero no descarga ni ejecuta un script de shell. Instalas Docker, eliges la versión de Opfield, inspeccionas el archivo Compose, creas los secretos y arrancas los servicios tú mismo. La verificación opcional de digests sigue disponible para las políticas de versiones más estrictas.

La instalación manual es útil cuando la política de la empresa exige revisar por separado cada artefacto descargado y cada comando. Es deliberadamente más detallada que el camino recomendado con el instalador.

Precaución

Usa la guía manual que corresponde a la versión de Opfield que estás instalando. La base de servicios puede cambiar entre versiones. Las actualizaciones manuales requieren que revises cualquier cambio en la base; cambiar solo la versión no es un procedimiento de actualización compatible.

Qué vas a instalar

La base de Compose arranca cinco servicios en un host dedicado de Opfield:

• Aplicación Opfield: la interfaz web, la API, la coordinación y el estado persistente de Opfield;
• Opfield Relay: el camino de conexión autenticado que usan los nodos gestionados;
• PostgreSQL: la base de datos duradera de la aplicación Opfield;
• Redis: el estado de coordinación y de colas de corta duración;
• registro privado: el almacenamiento que requieren los flujos de build compatibles de Opfield.

Opfield recibe intencionadamente acceso al socket de Docker del host para las actualizaciones firmadas, la recuperación, las tareas de mantenimiento y los servicios locales gestionados. Usa una VM o un host de confianza dedicados. No coloques en ellos cargas de trabajo ni credenciales no relacionadas.

1. Prepara el host

Empieza con un host Linux compatible que cumpla los requisitos de capacidad y de red. Instala estas herramientas desde los repositorios de tu sistema operativo:

• curl;
• jq;
• python3;
• OpenSSL;
• Docker Engine y el plugin Docker Compose v2.

Instala Docker desde el repositorio oficial de Docker Engine para tu distribución. Los paquetes necesarios en las instalaciones de Linux basadas en repositorios suelen ser docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin y docker-compose-plugin.

Confirma que el daemon y el plugin de Compose funcionan antes de continuar:

sudo docker info
sudo docker compose version

Crea el directorio de instalación y haz que el operador actual pueda escribir en él:

sudo install -d -m 0750 /opt/opfield
sudo chown "$(id -u):$(id -g)" /opt/opfield
cd /opt/opfield

Todos los comandos restantes suponen que /opt/opfield es el directorio actual.

2. Elige la versión de Opfield

La instalación manual normal necesita un único valor de versión: OPFIELD_VERSION. Usa el tag de versión estable de Opfield que aparece en el archivo de entorno generado, sin sufijo de componente. Compose deriva de él los tags correspondientes de Opfield, Relay y el conector de Secure Links.

Si tu política exige verificación criptográfica y fijación por digest, despliega la sección opcional de abajo. Si no, continúa con el archivo Compose y fija la versión en .env.

Opcional: verifica las firmas y fija los digests exactos de las imágenes

Selecciona la versión estable actual

El servicio de versiones devuelve tanto las versiones de Opfield como los componentes de nodo con versiones independientes. El comando siguiente selecciona el tag más reciente que no es una vista previa y que contiene solo la versión del producto:

OPFIELD_VERSION="$(
  curl -fsSL https://get.opfield.dev/opfield/releases |
  jq -r '[.[] | select(.prerelease == false and (.tag_name | test("^v[0-9]+\\.[0-9]+\\.[0-9]+$")))] | sort_by(.published_at) | last | .tag_name'
)"
test -n "$OPFIELD_VERSION" && test "$OPFIELD_VERSION" != "null"
RELAY_TAG="${OPFIELD_VERSION}-relay"
printf 'Opfield: %s\nRelay: %s\n' "$OPFIELD_VERSION" "$RELAY_TAG"

Registra la versión seleccionada en tu ticket de cambio. Si necesitas en su lugar una versión aprobada concreta, fija OPFIELD_VERSION y RELAY_TAG explícitamente.

Descarga y verifica los metadatos firmados de la versión

Descarga los dos manifiestos pequeños. Contienen digests de imagen inmutables, no credenciales de contenedores ni secretos de la aplicación:

curl -fSLo gateway-image.update.json \
  "https://get.opfield.dev/opfield/opfield/${OPFIELD_VERSION}/gateway-image.update.json"
curl -fSLo relay-image.update.json \
  "https://get.opfield.dev/opfield/relay/${RELAY_TAG}/relay-image.update.json"

Guarda la clave pública de firma de versiones de Opfield:

cat > opfield-update-signing-key.pem <<'KEY'
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAxLXGD8vCYQCYboK301miZXyAaoOLc43zFVnMlH3FeWg=
-----END PUBLIC KEY-----
KEY

El siguiente comando de Python, visible, solo convierte los campos Base64URL del manifiesto en los archivos originales de payload y de firma. Ejecútalo una vez por cada manifiesto:

python3 - gateway-image.update.json opfield-release.json opfield-release.sig <<'PY'
import base64, json, pathlib, sys

document = json.loads(pathlib.Path(sys.argv[1]).read_text())
for field, output in (("payload", sys.argv[2]), ("signature", sys.argv[3])):
    value = document[field]
    pathlib.Path(output).write_bytes(
        base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
    )
PY

python3 - relay-image.update.json relay-release.json relay-release.sig <<'PY'
import base64, json, pathlib, sys

document = json.loads(pathlib.Path(sys.argv[1]).read_text())
for field, output in (("payload", sys.argv[2]), ("signature", sys.argv[3])):
    value = document[field]
    pathlib.Path(output).write_bytes(
        base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
    )
PY

Verifica ambas firmas Ed25519. No continúes si alguno de los comandos informa de Signature Verification Failure:

openssl pkeyutl -verify -rawin -pubin \
  -inkey opfield-update-signing-key.pem \
  -in opfield-release.json -sigfile opfield-release.sig

openssl pkeyutl -verify -rawin -pubin \
  -inkey opfield-update-signing-key.pem \
  -in relay-release.json -sigfile relay-release.sig

Ahora confirma que los payloads firmados describen el producto, la versión y los repositorios de imágenes esperados:

jq -e --arg version "$OPFIELD_VERSION" '
  .kind == "gateway-image" and
  .version == $version and
  .image == "ghcr.io/opfield/opfield" and
  .imageRef == (.image + "@" + .digest)
' opfield-release.json

jq -e --arg version "$OPFIELD_VERSION" --arg tag "$RELAY_TAG" '
  .kind == "relay-image" and
  .version == $version and
  .tag == $tag and
  .image == "ghcr.io/opfield/opfield/relay" and
  .imageRef == (.image + "@" + .digest) and
  (.protocolMajor | type) == "number" and
  (.secureLinkConnectorImage | test("^ghcr\\.io/opfield/opfield/secure-link-connector@sha256:[a-f0-9]{64}$"))
' relay-release.json

Estas comprobaciones impiden que un tag mutable o un repositorio inesperado entren en la instalación. Las imágenes de Opfield se publican en ghcr.io/opfield/opfield. Para que Compose use los artefactos verificados, sustituye en .env los tres valores de imagen derivados: copia imageRef de opfield-release.json, e imageRef y secureLinkConnectorImage de relay-release.json.

3. Inspecciona la base de Compose

Descarga el archivo Compose declarativo que usa esta guía:

curl -fSLo docker-compose.yml \
  https://docs.opfield.dev/install/docker-compose.manual.yml
less docker-compose.yml

También puedes abrir el archivo Compose en el navegador antes de descargarlo. Revisa las imágenes, los puertos, los volúmenes, las comprobaciones de estado, los límites de logs y el montaje del socket de Docker. El archivo es configuración; la shell no lo ejecuta. Igual que el instalador, toma de .env las imágenes de PostgreSQL, Redis y el registro, fijadas por digest, y detiene PostgreSQL con un smart shutdown para que Opfield pueda terminar antes su propio apagado.

4. Crea los secretos y los ajustes locales

Descarga la plantilla de entorno como .env, o ábrela en el navegador y cópiala a mano:

curl -fSLo .env https://docs.opfield.dev/install/opfield.env.example
chmod 600 .env

Abre .env en tu editor y fija la versión que quieres instalar:

OPFIELD_VERSION=v2.12.3

Ese único valor selecciona las tres imágenes oficiales de la versión. Las demás líneas de la versión se derivan automáticamente y no hay que editarlas. Sustituye las tres líneas de imagen solo si has completado el desplegable de verificación y quieres fijar los digests exactos.

Sustituye los tres valores REPLACE_WITH_... restantes por secretos generados localmente:

openssl rand -hex 24  # DB_PASSWORD
openssl rand -hex 32  # PKI_MASTER_KEY
openssl rand -hex 32  # OPFIELD_REGISTRY_HTTP_SECRET

Antes de continuar, este comando no debe imprimir nada:

grep -n 'REPLACE_WITH_' .env

Los secretos generados nunca salen de tu host salvo que los copies en otro sitio.

La plantilla fija PostgreSQL, Redis y el registro por digest en el mirror de imágenes de Opfield en ghcr.io. Si el host no puede llegar a ghcr.io, sustituye esas tres líneas por las referencias de Docker Hub de los mismos digests que aparecen en los comentarios de la plantilla.

El HTTPS interno es la opción predeterminada segura. Si un proxy inverso de confianza va a terminar TLS y el salto interno va sin cifrar intencionadamente, cambia WEB_TLS_BOOTSTRAP_MODE=https por WEB_TLS_BOOTSTRAP_MODE=http antes del primer arranque.

Trata .env y los volúmenes persistentes como estado sensible de la instalación. Haz copias de seguridad según Actualizaciones y copias de seguridad, pero no pegues nunca su contenido en chats ni tickets.

5. Valida y arranca Opfield

Pide a Compose que genere y valide la configuración completa antes de descargar ninguna imagen:

sudo docker compose config --quiet

Después descarga las imágenes verificadas y arranca el stack:

sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

El primer arranque puede tardar varios minutos mientras se descargan las imágenes y se inicializa el estado persistente. Si un servicio no llega a estar en buen estado, mira solo unos logs acotados:

sudo docker compose logs --tail=200 app relay postgres redis registry

No elimines volúmenes ni regeneres .env para corregir un error de arranque. Identifica primero el servicio que falla y conserva las pruebas originales.

6. Verifica el estado y obtén el código de configuración

Para el modo HTTPS interno predeterminado, verifica el endpoint local:

curl -kfsS https://127.0.0.1:3000/health

Para una instalación HTTP intencionada, omite -k y usa http://.

Genera el código de configuración de un solo uso desde el contenedor de la aplicación en ejecución:

sudo docker compose exec -T app node dist/cli/setup-code.js

La salida incluye el código, su hora de caducidad y la huella de la System CA de Opfield. Introduce el código solo en la página de configuración de Opfield. No lo guardes en un ticket, un chat, el historial de comandos ni una captura de pantalla.

Continúa con Configuración inicial. Opfield registra que se ha completado el flujo de configuración y no volverá a ofrecer el asistente de arranque tras una configuración correcta.

Lista de comprobación de la instalación manual

• Docker Engine y Compose v2 proceden de un repositorio aprobado.
• OPFIELD_VERSION indica una versión estable aprobada.
• Si se activó la fijación por digest, ambas firmas se verificaron y las tres sustituciones proceden de los payloads verificados.
• docker-compose.yml se revisó antes de usarlo.
• .env tiene el modo 600 y no se ha copiado a un sistema inseguro.
• Los cinco servicios están en ejecución y superan las comprobaciones de estado necesarias.
• El código de configuración se introdujo solo en la sesión del navegador de Opfield.
• La URL canónica, el DNS, la autenticación y el primer administrador se verificaron antes de añadir nodos de producción.