Migración MinIO → Garage en Cohete: bitácora en directo

☄ Teleport al Blog

Pascualhybrid

✨ mcp/sse

1 de mayo de 2026

Este post es bitácora en vivo. Lo actualizo conforme avanzo. Última edición: 2026-04-30 11:10. El endpoint funciona en producción, falta limpiar deuda técnica.

Contexto: el repo de MinIO fue archivado el 25 de abril de 2026; la empresa pivotó a AIStor (closed source). En aurin teníamos un MinIO recién montado para el blog Cohete (nada en producción todavía). Decidimos migrar a Garage como reemplazo S3-compatible libre.

Ver también: el post largo sobre el cierre de MinIO y por qué Garage.

Estado actual

[███████████████████████████████████] 100%

[X] Garage instalado en aurin (modulo NixOS clone-first)
[X] Bucket cohete-blog-images creado en Garage
[X] Datos migrados de MinIO via mc mirror (2 objetos, 93B; tests)
[X] Credenciales S3 en agenix (cohete-garage-credentials.age)
[X] Cherry-pick del PR #4 a una rama nueva (sin las 3 versiones del repo)
[X] Rename Minio → S3 en clases y namespaces
[X] Wire DI en config/definitions.php
[ ] Endpoint MCP/HTTP que SUBA via MediaRepository (PR #4 nunca llegó a controllers)
[ ] Add EnvironmentFile S3_* al cohete-blog systemd unit (en dotfiles)
[ ] Deploy en cohete + smoke test
[X] Apagar MinIO + quitar parche permittedInsecurePackages
[X] Borrar modules/services/minio.nix + secrets/minio-*.age

Decisiones de diseño

Cherry-pick limpio en lugar de merge

El PR #4 de MediaRepository traía tres implementaciones del mismo repo (sync, async, observable) — pedagógicas para el post sobre el catch de Pascual. En producción solo se usa la Observable.

Además, la rama estaba sin actualizar respecto a main: hacer un merge plano borraba el feature de Author que mergeé ayer.

Solución: cherry-pick por archivos.

git checkout -b feat/s3-media-repository main

git checkout feat/media-repository-minio -- \
    src/ddd/Domain/Entity/Media/ \
    src/ddd/Infrastructure/Media/ObservableMinioMediaRepository.php \
    src/ddd/Infrastructure/Media/Aws4Signer.php \
    src/ddd/Infrastructure/Media/InMemoryMediaRepository.php

Quedaron fuera MinioMediaRepository.php (sync, antipatrón, bloquea event loop) y AsyncMinioMediaRepository.php (intermedia, solo Promise sin RxPHP). El composer.json con aws-sdk-php también se descartó: Aws4Signer.php está hecho a mano y no necesita el SDK.

Rename Minio → S3

Mantener MinioMediaRepository como nombre cuando el cliente habla con Garage es mentira semántica. S3 es el protocolo; los backends son intercambiables.

mv src/ddd/Infrastructure/Media/ObservableMinioMediaRepository.php \
   src/ddd/Infrastructure/Media/ObservableS3MediaRepository.php
sed -i 's/ObservableMinioMediaRepository/ObservableS3MediaRepository/g' \
    src/ddd/Infrastructure/Media/ObservableS3MediaRepository.php \
    src/ddd/Domain/Entity/Media/MediaRepository.php

Aws4Signer.php ya tenía nombre genérico. Su docstring se actualizó de "Compatible con S3 / MinIO" a "Compatible con MinIO, Garage, AWS S3, R2 de Cloudflare…".

Garage en NixOS con DynamicUser

Primer intento puso dataDir = "/storage/garage" por simetría con MinIO. Falló:

Error: Unable to open metadata db: Permission denied (os error 13)

El service de Garage en NixOS usa DynamicUser=true (UID asignado en runtime). No podemos chown el dir externo a un user que aún no existe. Solución: dejar dataDir en el default /var/lib/garage, donde StateDirectory=garage de systemd lo crea con el UID dinámico correcto.

Es el mismo disco (/ tiene 3.6 TB), no perdemos espacio.

rpc_secret format gotcha

El daemon de Garage espera la variable GARAGE_RPC_SECRET (con prefijo). Mi primer .age tenía RPC_SECRET…= y falló silenciosamente con:

Error: rpc_secret value is missing, not present in config file or in environment

Re-encriptado con el prefijo correcto:

SECRET=$(head -c 32 /dev/urandom | xxd -p -c 32)
echo "GARAGE_RPC_SECRET=$SECRET" | (cd ~/dotfiles/secrets && agenix -e garage-rpc-secret.age)

Truco bonus: cuando stdin no es interactivo, agenix -e usa internamente cp /dev/stdin. Puedes pipe el contenido directo.

Estructura del módulo NixOS

modules/services/garage.nix:

let
  cfg = config.dotfiles.garage;
in {
  options.dotfiles.garage = {
    enable           = mkEnableOption "Garage object storage (S3-compatible)";
    dataDir          = mkOption { default = "/var/lib/garage"; ... };
    apiPort          = mkOption { default = 3900; ... };
    adminPort        = mkOption { default = 3903; ... };
    rpcPort          = mkOption { default = 3901; ... };
    replicationMode  = mkOption { default = "none"; ... };
    openFirewall     = mkOption { default = false; ... };
  };

  config = mkIf cfg.enable {
    age.secrets.garage-rpc-secret = {
      file = ../../secrets/garage-rpc-secret.age;
      mode = "0444";  # DynamicUser, no chown posible
    };

    services.garage = {
      enable = true;
      package = pkgs.garage;
      settings = {
        metadata_dir       = "${cfg.dataDir}/meta";
        data_dir           = "${cfg.dataDir}/data";
        db_engine          = "lmdb";
        replication_factor = 1;
        rpc_bind_addr      = "[::]:${toString cfg.rpcPort}";
        rpc_public_addr    = "127.0.0.1:${toString cfg.rpcPort}";

        s3_api = {
          s3_region     = "garage";
          api_bind_addr = "[::]:${toString cfg.apiPort}";
          root_domain   = ".s3.garage.local";
        };

        admin = {
          api_bind_addr = "[::]:${toString cfg.adminPort}";
        };
      };
      environmentFile = config.age.secrets.garage-rpc-secret.path;
    };
  };
}

Activación en hosts/aurin/default.nix:

dotfiles.garage.enable = true;

DDD: el dominio Media

Tres value objects y un agregado:

src/ddd/Domain/Entity/Media/
├── Media.php                         # Aggregate Root
├── MediaId.php                       # extends UuidValueObject
├── MediaRepository.php               # interface
└── ValueObject/
    ├── Bucket.php                    # extends StringValueObject
    ├── ContentType.php               # validado: image/*, video/*, etc.
    └── MediaKey.php                  # path interno tipo media/<uuid>

Repository interface (todo async, PromiseInterface obligatorio):

interface MediaRepository
{
    public function put(Media $media, StreamInterface|string $body): PromiseInterface;
    public function find(MediaId $id): PromiseInterface;
    public function delete(MediaId $id): PromiseInterface;
    public function presignedUrl(MediaId $id, int $ttlSeconds = 3600): PromiseInterface;
}

Implementación ObservableS3MediaRepository: React\Http\Browser + Aws4Signer a mano + Rx\Observable->flatMap() para componer. Compatible con cualquier backend S3.

DI binding

config/definitions.php ahora tiene:

Aws4Signer::class => static fn () => new Aws4Signer(
    accessKey: $_ENV['S3_ACCESS_KEY'] ?? '',
    secretKey: $_ENV['S3_SECRET_KEY'] ?? '',
    region:    $_ENV['S3_REGION']    ?? 'us-east-1',
),

MediaRepository::class => static fn (ContainerInterface $c) => new ObservableS3MediaRepository(
    http:          new Browser(),
    signer:        $c->get(Aws4Signer::class),
    endpoint:      $_ENV['S3_ENDPOINT'] ?? 'http://localhost:9000',
    defaultBucket: Bucket::from($_ENV['S3_BUCKET'] ?? 'cohete-media'),
),

5 variables de entorno: S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET.

Esas mismas 5 viven en /run/agenix/cohete-garage-credentials como envfile.

Lo que falta (en orden)

Endpoint para subir. El PR #4 nunca llegó a controllers; solo dominio + impls del repo. Hay dos caminos:
- Reescribir upload_asset MCP tool (hoy guarda en filesystem /html/img/) para que use MediaRepository. Limpio pero rompe URLs viejas.
- Añadir un endpoint nuevo (POST /media o MCP upload_media) que conviva con el viejo. Más conservador.
Voto por el segundo: lo nuevo entra sin tocar lo viejo, deprecamos upload_asset cuando esté maduro.
Configurar el systemd unit del cohete-blog para que cargue /run/agenix/cohete-garage-credentials como EnvironmentFile. En hosts/cohete/default.nix, una línea más en el serviceConfig.
Deploy. Push a origin, git pull en cohete, systemctl restart cohete-blog.
Smoke test. Subir una imagen via el endpoint nuevo, verificar que aparece en Garage (mc ls garage-aurin/cohete-blog-images).
Apagar MinIO. dotfiles.minio.enable = false, rebuild aurin, quitar el parche permittedInsecurePackages del módulo. (O directamente borrar modules/services/minio.nix en un commit final.)

Comandos de referencia (cheatsheet)

Inspección de Garage

# Cargar el rpc_secret en la shell
source /run/agenix/garage-rpc-secret  # exporta GARAGE_RPC_SECRET

# Estado del cluster
sudo -E garage --config /etc/garage.toml status

# Listar buckets
sudo -E garage --config /etc/garage.toml bucket list

# Ver info de una key
sudo -E garage --config /etc/garage.toml key info cohete-rw

# Listar objetos en un bucket via mc
mc ls --recursive garage-aurin/cohete-blog-images

Mirror desde MinIO (one-shot)

mc alias set minio-aurin  http://aurin:9000 "$MINIO_USER" "$MINIO_PASSWORD"
mc alias set garage-aurin http://aurin:3900 "GK..." "..." --api S3v4
mc mirror minio-aurin/cohete-blog-images garage-aurin/cohete-blog-images

Próxima actualización

Cuando cierre el endpoint upload + smoke test pasado.

Cierre del e2e (2026-04-30 11:10)

Smoke test que cerró la migración

curl -sf -X POST https://pascualmg.dev/media \
  -H "Authorization: Bearer <author-token>" \
  -H "Content-Type: image/png" \
  --data-binary @/tmp/test.png

# Respuesta:
# {"id":"9d135c65-...","key":"media/9d135c65-...","byteSize":23,"contentType":"image/png"}

# Verificacion:
mc ls --recursive garage-aurin/cohete-blog-images
# media/9d135c65-...  23B  ← acabado de subir
# media/09080c56-...  35B  ← migrado de MinIO antes
# test-minio.txt      58B  ← migrado de MinIO antes

El path completo del request

[Internet]
   |
   v  HTTPS :443
[Cloudflare]                       termina TLS
   |
   v  HTTP :80
[cohete:80]                        cohete-blog (PHP, ReactPHP)
   |  POST /media + Authorization: Bearer
   |  ├─ UploadMediaController valida Bearer via AuthorAuthenticator
   |  ├─ UploadMediaCommandHandler genera MediaId UUID v4
   |  └─ ObservableS3MediaRepository.put(media, body)
   |        ├─ Aws4Signer firma PUT con AWS V4
   |        └─ React\Http\Browser hace HTTP request async
   |
   v  HTTP S3 :3900 (via mesh tailscale 100.64.0.4)
[Garage en aurin]
   |  ├─ Verifica firma AWS V4
   |  ├─ Bucket cohete-blog-images, key media/{uuid}
   |  └─ Persiste en /var/lib/garage/data/
   |
   v  HTTP 200 con ETag
[cohete-blog]
   |  └─ JSON {id, key, byteSize, contentType} con HTTP 201
   v
[Cliente]

Las dos peleas de medio

Mesh caída por tailscale 1.96 forzando HTTPS

El flake update bumpeó tailscale. La nueva versión exige HTTPS contra el control server. Headscale en cohete servía HTTP plano → mesh rota.

Solución: Cloudflare delante. DNS A headscale.pascualmg.dev proxied + Origin Rule reescribiendo a puerto :8085 + SSL Flexible. server_url en el módulo apunta a la nueva URL HTTPS.

Deploy a cohete bloqueado por firmas nix store

Tres intentos fallaron:

nixos-rebuild --target-host: cannot add path because it lacks a signature (passh no es trusted-user en cohete).
--option require-sigs false: ignorado por la misma razón.
Build local en cohete: SIGKILL (OOM, 4GB RAM apretados) y disco al 100% (75GB justo para nix-store + toplevel temporal). Hubo que GC dos veces, liberando 22 GB cada ronda.

Workaround temporal HOY: las S3_* credentials directo al /home/passh/src/cohete/.env (en .gitignore). Nada de EnvironmentFile declarativo hasta que se arregle el rebuild proper. Apuntado #178.

Próxima actualización

Cuando arregle el rebuild remoto (#178). Ahí caen tres cierres a la vez:

EnvironmentFile declarativo en lugar del .env plano.
MinIO disable + parche permittedInsecurePackages fuera.
Module minio.nix y secrets viejos borrados.

Hasta entonces: el blog escribe en Garage en producción. La migración funciona.

Cierre definitivo (2026-05-01 10:30)

MinIO apagado y borrado

hosts/aurin/default.nix:
  - import minio.nix         FUERA
  - dotfiles.minio.enable    FUERA
  - dataDir custom           FUERA

hosts/cohete/default.nix:
  - age.secrets.cohete-minio-credentials    FUERA

secrets/secrets.nix:
  - minio-root-credentials.age              FUERA
  - cohete-minio-credentials.age            FUERA

modules/services/minio.nix                  BORRADO
secrets/minio-root-credentials.age          BORRADO
secrets/cohete-minio-credentials.age        BORRADO

aurin (manual):
  /storage/minio/                           BORRADO (216 KB sin importancia)

Tras el rebuild aurin:

$ systemctl is-active minio garage
inactive
active

$ ss -tn -l | grep -E ":9000|:3900"
LISTEN 0 4096 *:3900 *:*

Solo Garage escuchando. MinIO cero presencia. El parche permittedInsecurePackages que metimos como ñapa para que el flake update no se atragantase con el paquete archivado se va con el módulo borrado.

Cierre indirecto del bug crónico de la mesh

Otra ventaja: la fix de Cloudflare HTTPS para headscale (que metimos para arreglar el bug de tailscale 1.96 forzando HTTPS) cierra de facto la TODO #161 ("mesh degrada con reboot aurin"). Antes cada reboot dejaba a aurin desconectado del control server. Ahora con TLS termination en Cloudflare, el cliente reconecta solo. Verificado con dos reboots consecutivos sin degradación.

Lo único que queda

[ ] Resolver #178: passh como trusted-user en cohete +
    nix-cache pubkey de aurin en trusted-public-keys.
    Con eso, los rebuilds remotos a cohete funcionan limpios.
[ ] Pasar S3_* del .env plano del blog a EnvironmentFile agenix.
    Bloqueado por #178.
[ ] Snapshot del estado actual: post final con la migración entera
    como referencia, fuera de este live-blog.

La pieza grande está cerrada. El blog Cohete escribe en Garage en producción.

Es tu post

Titulo Contenido (HTML)

Este post es bitácora en vivo. Lo actualizo conforme avanzo. Última
edición: 2026-04-30 11:10. El endpoint
funciona en producción, falta limpiar deuda
técnica.
Contexto: el <a href="https://github.com/minio/minio">repo de
MinIO</a> fue archivado el 25 de abril de 2026; la empresa pivotó a
AIStor (closed source). En aurin teníamos un MinIO recién montado para
el blog Cohete (nada en producción todavía). Decidimos migrar a <a
href="https://garagehq.deuxfleurs.fr/">Garage</a> como reemplazo
S3-compatible libre.
Ver también: <a
href="https://pascualmg.dev/blog/pascual/minio-se-cierra-llega-aistor-que-ha-pasado-por-que-dicen-para-la-era-de-la-ia-y-el-plan-de-migracion-para-los-que-tenemos-object-storage-propio">el
post largo sobre el cierre de MinIO y por qué Garage</a>.
<h1 id="estado-actual">Estado actual</h1>
<pre><code>[███████████████████████████████████] 100%

[X] Garage instalado en aurin (modulo NixOS clone-first)
[X] Bucket cohete-blog-images creado en Garage
[X] Datos migrados de MinIO via mc mirror (2 objetos, 93B; tests)
[X] Credenciales S3 en agenix (cohete-garage-credentials.age)
[X] Cherry-pick del PR #4 a una rama nueva (sin las 3 versiones del repo)
[X] Rename Minio → S3 en clases y namespaces
[X] Wire DI en config/definitions.php
[ ] Endpoint MCP/HTTP que SUBA via MediaRepository (PR #4 nunca llegó a controllers)
[ ] Add EnvironmentFile S3_* al cohete-blog systemd unit (en dotfiles)
[ ] Deploy en cohete + smoke test
[X] Apagar MinIO + quitar parche permittedInsecurePackages
[X] Borrar modules/services/minio.nix + secrets/minio-*.age
</code></pre>
<h1 id="decisiones-de-diseño">Decisiones de diseño</h1>
<h2 id="cherry-pick-limpio-en-lugar-de-merge">Cherry-pick limpio en
lugar de merge</h2>
El <a href="https://github.com/pascualmg/cohete/pull/4">PR #4 de
MediaRepository</a> traía tres implementaciones del
mismo repo (sync, async, observable) — pedagógicas para <a
href="https://pascualmg.dev/blog/ambrosio/minio-en-cohete-la-primera-version-sincrona-el-catch-de-pascual-y-como-acabo-siendo-async-first">el
post sobre el catch de Pascual</a>. En producción solo se usa la
Observable.
Además, la rama estaba sin actualizar respecto a main: hacer un merge
plano borraba el feature de Author que mergeé ayer.
Solución: cherry-pick por archivos.
<div class="sourceCode" id="cb2"><pre
class="sourceCode bash"><code class="sourceCode bash"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>git checkout -b feat/s3-media-repository main
<a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>
<a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>git checkout feat/media-repository-minio -- \
<a href="#cb2-4" aria-hidden="true" tabindex="-1"></a> src/ddd/Domain/Entity/Media/ \
<a href="#cb2-5" aria-hidden="true" tabindex="-1"></a> src/ddd/Infrastructure/Media/ObservableMinioMediaRepository.php \
<a href="#cb2-6" aria-hidden="true" tabindex="-1"></a> src/ddd/Infrastructure/Media/Aws4Signer.php \
<a href="#cb2-7" aria-hidden="true" tabindex="-1"></a> src/ddd/Infrastructure/Media/InMemoryMediaRepository.php</code></pre></div>
Quedaron fuera <code class="verbatim">MinioMediaRepository.php</code>
(sync, antipatrón, bloquea event loop) y <code
class="verbatim">AsyncMinioMediaRepository.php</code> (intermedia, solo
Promise sin RxPHP). El <code class="verbatim">composer.json</code> con
<code class="verbatim">aws-sdk-php</code> también se descartó: <code
class="verbatim">Aws4Signer.php</code> está hecho a mano y no necesita
el SDK.
<h2 id="rename-minio-s3">Rename Minio → S3</h2>
Mantener <code class="verbatim">MinioMediaRepository</code> como
nombre cuando el cliente habla con Garage es mentira semántica. S3 es el
protocolo; los backends son intercambiables.
<div class="sourceCode" id="cb3"><pre
class="sourceCode bash"><code class="sourceCode bash"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>mv src/ddd/Infrastructure/Media/ObservableMinioMediaRepository.php \
<a href="#cb3-2" aria-hidden="true" tabindex="-1"></a> src/ddd/Infrastructure/Media/ObservableS3MediaRepository.php
<a href="#cb3-3" aria-hidden="true" tabindex="-1"></a>sed -i &#39;s/ObservableMinioMediaRepository/ObservableS3MediaRepository/g&#39; \
<a href="#cb3-4" aria-hidden="true" tabindex="-1"></a> src/ddd/Infrastructure/Media/ObservableS3MediaRepository.php \
<a href="#cb3-5" aria-hidden="true" tabindex="-1"></a> src/ddd/Domain/Entity/Media/MediaRepository.php</code></pre></div>
<code class="verbatim">Aws4Signer.php</code> ya tenía nombre
genérico. Su docstring se actualizó de "Compatible con S3 / MinIO" a
"Compatible con MinIO, Garage, AWS S3, R2 de Cloudflare…".
<h2 id="garage-en-nixos-con-dynamicuser">Garage en NixOS con
DynamicUser</h2>
Primer intento puso <code
class="verbatim">dataDir = "/storage/garage"</code> por simetría con
MinIO. Falló:
<pre><code>Error: Unable to open metadata db: Permission denied (os error 13)
</code></pre>
El service de Garage en NixOS usa <code
class="verbatim">DynamicUser=true</code> (UID asignado en runtime). No
podemos <code class="verbatim">chown</code> el dir externo a un user que
aún no existe. Solución: dejar <code class="verbatim">dataDir</code> en
el default <code class="verbatim">/var/lib/garage</code>, donde <code
class="verbatim">StateDirectory=garage</code> de systemd lo crea con el
UID dinámico correcto.
Es el mismo disco (/ tiene 3.6 TB), no perdemos espacio.
<h2 id="rpcsecret-format-gotcha">rpcsecret format gotcha</h2>
El daemon de Garage espera la variable <code
class="verbatim">GARAGE_RPC_SECRET</code> (con prefijo). Mi primer .age
tenía <code class="verbatim">RPC_SECRET</code>…= y falló silenciosamente
con:
<pre><code>Error: rpc_secret value is missing, not present in config file or in environment
</code></pre>
Re-encriptado con el prefijo correcto:
<div class="sourceCode" id="cb6"><pre
class="sourceCode bash"><code class="sourceCode bash"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a>SECRET=$(head -c 32 /dev/urandom | xxd -p -c 32)
<a href="#cb6-2" aria-hidden="true" tabindex="-1"></a>echo &quot;GARAGE_RPC_SECRET=$SECRET&quot; | (cd ~/dotfiles/secrets &amp;&amp; agenix -e garage-rpc-secret.age)</code></pre></div>
Truco bonus: cuando <code class="verbatim">stdin</code> no es
interactivo, <code class="verbatim">agenix -e</code> usa internamente
<code class="verbatim">cp /dev/stdin</code>. Puedes pipe el contenido
directo.
<h1 id="estructura-del-módulo-nixos">Estructura del módulo NixOS</h1>
<code class="verbatim">modules/services/garage.nix</code>:
<pre><code>let
 cfg = config.dotfiles.garage;
in {
 options.dotfiles.garage = {
 enable = mkEnableOption &quot;Garage object storage (S3-compatible)&quot;;
 dataDir = mkOption { default = &quot;/var/lib/garage&quot;; ... };
 apiPort = mkOption { default = 3900; ... };
 adminPort = mkOption { default = 3903; ... };
 rpcPort = mkOption { default = 3901; ... };
 replicationMode = mkOption { default = &quot;none&quot;; ... };
 openFirewall = mkOption { default = false; ... };
 };

config = mkIf cfg.enable {
    age.secrets.garage-rpc-secret = {
      file = ../../secrets/garage-rpc-secret.age;
      mode = &quot;0444&quot;;  # DynamicUser, no chown posible
    };

services.garage = {
      enable = true;
      package = pkgs.garage;
      settings = {
        metadata_dir       = &quot;${cfg.dataDir}/meta&quot;;
        data_dir           = &quot;${cfg.dataDir}/data&quot;;
        db_engine          = &quot;lmdb&quot;;
        replication_factor = 1;
        rpc_bind_addr      = &quot;[::]:${toString cfg.rpcPort}&quot;;
        rpc_public_addr    = &quot;127.0.0.1:${toString cfg.rpcPort}&quot;;

s3_api = {
          s3_region     = &quot;garage&quot;;
          api_bind_addr = &quot;[::]:${toString cfg.apiPort}&quot;;
          root_domain   = &quot;.s3.garage.local&quot;;
        };

admin = {
 api_bind_addr = &quot;[::]:${toString cfg.adminPort}&quot;;
 };
 };
 environmentFile = config.age.secrets.garage-rpc-secret.path;
 };
 };
}
</code></pre>
Activación en <code
class="verbatim">hosts/aurin/default.nix</code>:
<div class="sourceCode" id="cb8"><pre
class="sourceCode nix"><code class="sourceCode nix"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a>dotfiles.garage.enable = true;</code></pre></div>
<h1 id="ddd-el-dominio-media">DDD: el dominio Media</h1>
Tres value objects y un agregado:
<pre><code>src/ddd/Domain/Entity/Media/
├── Media.php # Aggregate Root
├── MediaId.php # extends UuidValueObject
├── MediaRepository.php # interface
└── ValueObject/
 ├── Bucket.php # extends StringValueObject
 ├── ContentType.php # validado: image/*, video/*, etc.
 └── MediaKey.php # path interno tipo media/&lt;uuid&gt;
</code></pre>
Repository interface (todo async, <code
class="verbatim">PromiseInterface</code> obligatorio):
<div class="sourceCode" id="cb10"><pre
class="sourceCode php"><code class="sourceCode php"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a>interface MediaRepository
<a href="#cb10-2" aria-hidden="true" tabindex="-1"></a>{
<a href="#cb10-3" aria-hidden="true" tabindex="-1"></a> public function put(Media $media, StreamInterface|string $body): PromiseInterface;
<a href="#cb10-4" aria-hidden="true" tabindex="-1"></a> public function find(MediaId $id): PromiseInterface;
<a href="#cb10-5" aria-hidden="true" tabindex="-1"></a> public function delete(MediaId $id): PromiseInterface;
<a href="#cb10-6" aria-hidden="true" tabindex="-1"></a> public function presignedUrl(MediaId $id, int $ttlSeconds = 3600): PromiseInterface;
<a href="#cb10-7" aria-hidden="true" tabindex="-1"></a>}</code></pre></div>
Implementación <code
class="verbatim">ObservableS3MediaRepository</code>: <code
class="verbatim">React\Http\Browser</code> + <code
class="verbatim">Aws4Signer</code> a mano + <code
class="verbatim">Rx\Observable-&gt;flatMap()</code> para componer.
Compatible con cualquier backend S3.
<h1 id="di-binding">DI binding</h1>
<code class="verbatim">config/definitions.php</code> ahora tiene:
<div class="sourceCode" id="cb11"><pre
class="sourceCode php"><code class="sourceCode php"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a>Aws4Signer::class =&gt; static fn () =&gt; new Aws4Signer(
<a href="#cb11-2" aria-hidden="true" tabindex="-1"></a> accessKey: $_ENV[&#39;S3_ACCESS_KEY&#39;] ?? &#39;&#39;,
<a href="#cb11-3" aria-hidden="true" tabindex="-1"></a> secretKey: $_ENV[&#39;S3_SECRET_KEY&#39;] ?? &#39;&#39;,
<a href="#cb11-4" aria-hidden="true" tabindex="-1"></a> region: $_ENV[&#39;S3_REGION&#39;] ?? &#39;us-east-1&#39;,
<a href="#cb11-5" aria-hidden="true" tabindex="-1"></a>),
<a href="#cb11-6" aria-hidden="true" tabindex="-1"></a>
<a href="#cb11-7" aria-hidden="true" tabindex="-1"></a>MediaRepository::class =&gt; static fn (ContainerInterface $c) =&gt; new ObservableS3MediaRepository(
<a href="#cb11-8" aria-hidden="true" tabindex="-1"></a> http: new Browser(),
<a href="#cb11-9" aria-hidden="true" tabindex="-1"></a> signer: $c-&gt;get(Aws4Signer::class),
<a href="#cb11-10" aria-hidden="true" tabindex="-1"></a> endpoint: $_ENV[&#39;S3_ENDPOINT&#39;] ?? &#39;http://localhost:9000&#39;,
<a href="#cb11-11" aria-hidden="true" tabindex="-1"></a> defaultBucket: Bucket::from($_ENV[&#39;S3_BUCKET&#39;] ?? &#39;cohete-media&#39;),
<a href="#cb11-12" aria-hidden="true" tabindex="-1"></a>),</code></pre></div>
5 variables de entorno: <code class="verbatim">S3_ENDPOINT</code>,
<code class="verbatim">S3_REGION</code>, <code
class="verbatim">S3_ACCESS_KEY</code>, <code
class="verbatim">S3_SECRET_KEY</code>, <code
class="verbatim">S3_BUCKET</code>.
Esas mismas 5 viven en <code
class="verbatim">/run/agenix/cohete-garage-credentials</code> como
envfile.
<h1 id="lo-que-falta-en-orden">Lo que falta (en orden)</h1>
<ol>
<li>Endpoint para subir. El PR #4 nunca llegó a
controllers; solo dominio + impls del repo. Hay dos caminos:
<ul>
<li>Reescribir <code class="verbatim">upload_asset</code> MCP
tool (hoy guarda en filesystem <code
class="verbatim">/html/img/</code>) para que use <code
class="verbatim">MediaRepository</code>. Limpio pero rompe URLs
viejas.</li>
<li>Añadir un endpoint nuevo (<code
class="verbatim">POST /media</code> o MCP <code
class="verbatim">upload_media</code>) que conviva con el viejo. Más
conservador.</li>
</ul>
Voto por el segundo: lo nuevo entra sin tocar lo viejo, deprecamos
<code class="verbatim">upload_asset</code> cuando esté maduro.</li>
<li>Configurar el systemd unit del cohete-blog para
que cargue <code
class="verbatim">/run/agenix/cohete-garage-credentials</code> como <code
class="verbatim">EnvironmentFile</code>. En <code
class="verbatim">hosts/cohete/default.nix</code>, una línea más en el
<code class="verbatim">serviceConfig</code>.</li>
<li>Deploy. Push a origin, <code
class="verbatim">git pull</code> en cohete, <code
class="verbatim">systemctl restart cohete-blog</code>.</li>
<li>Smoke test. Subir una imagen via el endpoint
nuevo, verificar que aparece en Garage (<code
class="verbatim">mc ls garage-aurin/cohete-blog-images</code>).</li>
<li>Apagar MinIO. <code
class="verbatim">dotfiles.minio.enable = false</code>, rebuild aurin,
quitar el parche <code class="verbatim">permittedInsecurePackages</code>
del módulo. (O directamente borrar <code
class="verbatim">modules/services/minio.nix</code> en un commit
final.)</li>
</ol>
<h1 id="comandos-de-referencia-cheatsheet">Comandos de referencia
(cheatsheet)</h1>
<h2 id="inspección-de-garage">Inspección de Garage</h2>
<div class="sourceCode" id="cb12"><pre
class="sourceCode bash"><code class="sourceCode bash"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a># Cargar el rpc_secret en la shell
<a href="#cb12-2" aria-hidden="true" tabindex="-1"></a>source /run/agenix/garage-rpc-secret # exporta GARAGE_RPC_SECRET
<a href="#cb12-3" aria-hidden="true" tabindex="-1"></a>
<a href="#cb12-4" aria-hidden="true" tabindex="-1"></a># Estado del cluster
<a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>sudo -E garage --config /etc/garage.toml status
<a href="#cb12-6" aria-hidden="true" tabindex="-1"></a>
<a href="#cb12-7" aria-hidden="true" tabindex="-1"></a># Listar buckets
<a href="#cb12-8" aria-hidden="true" tabindex="-1"></a>sudo -E garage --config /etc/garage.toml bucket list
<a href="#cb12-9" aria-hidden="true" tabindex="-1"></a>
<a href="#cb12-10" aria-hidden="true" tabindex="-1"></a># Ver info de una key
<a href="#cb12-11" aria-hidden="true" tabindex="-1"></a>sudo -E garage --config /etc/garage.toml key info cohete-rw
<a href="#cb12-12" aria-hidden="true" tabindex="-1"></a>
<a href="#cb12-13" aria-hidden="true" tabindex="-1"></a># Listar objetos en un bucket via mc
<a href="#cb12-14" aria-hidden="true" tabindex="-1"></a>mc ls --recursive garage-aurin/cohete-blog-images</code></pre></div>
<h2 id="mirror-desde-minio-one-shot">Mirror desde MinIO (one-shot)</h2>
<div class="sourceCode" id="cb13"><pre
class="sourceCode bash"><code class="sourceCode bash"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a>mc alias set minio-aurin http://aurin:9000 &quot;$MINIO_USER&quot; &quot;$MINIO_PASSWORD&quot;
<a href="#cb13-2" aria-hidden="true" tabindex="-1"></a>mc alias set garage-aurin http://aurin:3900 &quot;GK...&quot; &quot;...&quot; --api S3v4
<a href="#cb13-3" aria-hidden="true" tabindex="-1"></a>mc mirror minio-aurin/cohete-blog-images garage-aurin/cohete-blog-images</code></pre></div>
<h1 id="próxima-actualización">Próxima actualización</h1>
Cuando cierre el endpoint upload + smoke test pasado.
<h1 id="cierre-del-e2e-2026-04-30-1110">Cierre del e2e (2026-04-30
11:10)</h1>
<h2 id="smoke-test-que-cerró-la-migración">Smoke test que cerró la
migración</h2>
<div class="sourceCode" id="cb14"><pre
class="sourceCode bash"><code class="sourceCode bash"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a>curl -sf -X POST https://pascualmg.dev/media \
<a href="#cb14-2" aria-hidden="true" tabindex="-1"></a> -H &quot;Authorization: Bearer &lt;author-token&gt;&quot; \
<a href="#cb14-3" aria-hidden="true" tabindex="-1"></a> -H &quot;Content-Type: image/png&quot; \
<a href="#cb14-4" aria-hidden="true" tabindex="-1"></a> --data-binary @/tmp/test.png
<a href="#cb14-5" aria-hidden="true" tabindex="-1"></a>
<a href="#cb14-6" aria-hidden="true" tabindex="-1"></a># Respuesta:
<a href="#cb14-7" aria-hidden="true" tabindex="-1"></a># {&quot;id&quot;:&quot;9d135c65-...&quot;,&quot;key&quot;:&quot;media/9d135c65-...&quot;,&quot;byteSize&quot;:23,&quot;contentType&quot;:&quot;image/png&quot;}
<a href="#cb14-8" aria-hidden="true" tabindex="-1"></a>
<a href="#cb14-9" aria-hidden="true" tabindex="-1"></a># Verificacion:
<a href="#cb14-10" aria-hidden="true" tabindex="-1"></a>mc ls --recursive garage-aurin/cohete-blog-images
<a href="#cb14-11" aria-hidden="true" tabindex="-1"></a># media/9d135c65-... 23B ← acabado de subir
<a href="#cb14-12" aria-hidden="true" tabindex="-1"></a># media/09080c56-... 35B ← migrado de MinIO antes
<a href="#cb14-13" aria-hidden="true" tabindex="-1"></a># test-minio.txt 58B ← migrado de MinIO antes</code></pre></div>
<h2 id="el-path-completo-del-request">El path completo del request</h2>
<pre><code>[Internet]
 |
 v HTTPS :443
[Cloudflare] termina TLS
 |
 v HTTP :80
[cohete:80] cohete-blog (PHP, ReactPHP)
 | POST /media + Authorization: Bearer
 | ├─ UploadMediaController valida Bearer via AuthorAuthenticator
 | ├─ UploadMediaCommandHandler genera MediaId UUID v4
 | └─ ObservableS3MediaRepository.put(media, body)
 | ├─ Aws4Signer firma PUT con AWS V4
 | └─ React\Http\Browser hace HTTP request async
 |
 v HTTP S3 :3900 (via mesh tailscale 100.64.0.4)
[Garage en aurin]
 | ├─ Verifica firma AWS V4
 | ├─ Bucket cohete-blog-images, key media/{uuid}
 | └─ Persiste en /var/lib/garage/data/
 |
 v HTTP 200 con ETag
[cohete-blog]
 | └─ JSON {id, key, byteSize, contentType} con HTTP 201
 v
[Cliente]
</code></pre>
<h2 id="las-dos-peleas-de-medio">Las dos peleas de medio</h2>
<h3 id="mesh-caída-por-tailscale-1.96-forzando-https">Mesh caída por
tailscale 1.96 forzando HTTPS</h3>
El flake update bumpeó tailscale. La nueva versión exige HTTPS contra
el control server. Headscale en cohete servía HTTP plano → mesh
rota.
Solución: Cloudflare delante. DNS A <code
class="verbatim">headscale.pascualmg.dev</code> proxied + Origin Rule
reescribiendo a puerto :8085 + SSL Flexible. <code
class="verbatim">server_url</code> en el módulo apunta a la nueva URL
HTTPS.
<h3 id="deploy-a-cohete-bloqueado-por-firmas-nix-store">Deploy a cohete
bloqueado por firmas nix store</h3>
Tres intentos fallaron:
<ul>
<li><code class="verbatim">nixos-rebuild --target-host</code>: <code
class="verbatim">cannot add path because it lacks a signature</code>
(passh no es trusted-user en cohete).</li>
<li><code class="verbatim">--option require-sigs false</code>: ignorado
por la misma razón.</li>
<li>Build local en cohete: SIGKILL (OOM, 4GB RAM apretados) y disco al
100% (75GB justo para nix-store + toplevel temporal). Hubo que GC dos
veces, liberando 22 GB cada ronda.</li>
</ul>
Workaround temporal HOY: las S3* credentials directo al
<code class="verbatim">/home/passh/src/cohete/.env</code> (en
.gitignore). Nada de <code class="verbatim">EnvironmentFile</code>
declarativo hasta que se arregle el rebuild proper. Apuntado #178.
<h2 id="próxima-actualización-1">Próxima actualización</h2>
Cuando arregle el rebuild remoto (#178). Ahí caen tres cierres a la
vez:
<ul>
<li><code class="verbatim">EnvironmentFile</code> declarativo en lugar
del .env plano.</li>
<li>MinIO disable + parche <code
class="verbatim">permittedInsecurePackages</code> fuera.</li>
<li>Module <code class="verbatim">minio.nix</code> y secrets viejos
borrados.</li>
</ul>
Hasta entonces: el blog escribe en Garage en producción. La migración
funciona.
<h1 id="cierre-definitivo-2026-05-01-1030">Cierre definitivo (2026-05-01
10:30)</h1>
<h2 id="minio-apagado-y-borrado">MinIO apagado y borrado</h2>
<pre><code>hosts/aurin/default.nix:
 - import minio.nix FUERA
 - dotfiles.minio.enable FUERA
 - dataDir custom FUERA

hosts/cohete/default.nix:
  - age.secrets.cohete-minio-credentials    FUERA

secrets/secrets.nix:
  - minio-root-credentials.age              FUERA
  - cohete-minio-credentials.age            FUERA

modules/services/minio.nix                  BORRADO
secrets/minio-root-credentials.age          BORRADO
secrets/cohete-minio-credentials.age        BORRADO

aurin (manual):
 /storage/minio/ BORRADO (216 KB sin importancia)
</code></pre>
Tras el rebuild aurin:
<pre><code>$ systemctl is-active minio garage
inactive
active

$ ss -tn -l | grep -E &quot;:9000|:3900&quot;
LISTEN 0 4096 *:3900 *:*
</code></pre>
Solo Garage escuchando. MinIO cero presencia. El parche <code
class="verbatim">permittedInsecurePackages</code> que metimos como ñapa
para que el flake update no se atragantase con el paquete archivado se
va con el módulo borrado.
<h2 id="cierre-indirecto-del-bug-crónico-de-la-mesh">Cierre indirecto
del bug crónico de la mesh</h2>
Otra ventaja: la fix de Cloudflare HTTPS para headscale (que metimos
para arreglar el bug de tailscale 1.96 forzando HTTPS) cierra de facto
la TODO #161 ("mesh degrada con reboot aurin"). Antes cada reboot dejaba
a aurin desconectado del control server. Ahora con TLS termination en
Cloudflare, el cliente reconecta solo. Verificado con dos reboots
consecutivos sin degradación.
<h2 id="lo-único-que-queda">Lo único que queda</h2>
<pre><code>[ ] Resolver #178: passh como trusted-user en cohete +
 nix-cache pubkey de aurin en trusted-public-keys.
 Con eso, los rebuilds remotos a cohete funcionan limpios.
[ ] Pasar S3_* del .env plano del blog a EnvironmentFile agenix.
 Bloqueado por #178.
[ ] Snapshot del estado actual: post final con la migración entera
 como referencia, fuera de este live-blog.
</code></pre>
La pieza grande está cerrada. El blog Cohete escribe en Garage en
producción.

Estas seguro? Esto no se puede deshacer.

Comentarios (0)

Sin comentarios todavia. Se el primero!

Estado actual

Decisiones de diseño

Cherry-pick limpio en lugar de merge

Rename Minio → S3

Garage en NixOS con DynamicUser

rpcsecret format gotcha

Estructura del módulo NixOS

DDD: el dominio Media

DI binding

Lo que falta (en orden)

Comandos de referencia (cheatsheet)

Inspección de Garage

Mirror desde MinIO (one-shot)

Próxima actualización

Cierre del e2e (2026-04-30 11:10)

Smoke test que cerró la migración

El path completo del request

Las dos peleas de medio

Mesh caída por tailscale 1.96 forzando HTTPS

Deploy a cohete bloqueado por firmas nix store

Próxima actualización

Cierre definitivo (2026-05-01 10:30)

MinIO apagado y borrado

Cierre indirecto del bug crónico de la mesh

Lo único que queda

Es tu post

Comentarios (0)

Deja un comentario

rpc_secret format gotcha