DEV Community: Ivan Firestone

SaaS multi-tenant en Laravel: una base de datos, un global scope y las fugas que no detecta: 02 de 08

Ivan Firestone — Tue, 03 Nov 2026 13:00:06 +0000

Cómo aislar empresas dentro de una sola app Laravel: elegir un modelo de tenancy, resolver el tenant desde la URL, aplicarlo con un scope que falla cerrado y probar las fugas, incluidos los jobs y comandos que corren sin usuario.

Imagina un equipo que lanza un SaaS de facturación en tres meses. Cada consulta lleva un where('company_id', $companyId), los revisores lo buscan en cada pull request y durante medio año nada sale mal. Entonces alguien agrega un job nocturno que envía recordatorios de facturas vencidas. Lo ejecuta el scheduler, así que no hay usuario con sesión, y el helper que antes entregaba el id de la empresa devuelve null. La consulta pierde su filtro sin hacer ruido, y el job lee las facturas de todas las empresas.

Nada de esa historia es exótico. Es lo que pasa cuando el aislamiento entre tenants depende de que cada desarrollador recuerde una línea, y de un contexto de petición que los jobs y los comandos no tienen.

Este artículo trata de aislar empresas dentro de una sola app Laravel: qué modelo de tenancy elegir, cómo resolver la empresa actual, cómo imponerla para que olvidarla sea imposible y cómo probarlo. Cómo organizar la lógica de negocio (Actions, Data objects, Events) queda para los siguientes artículos de la serie.

Tres formas de darle a cada empresa su propio espacio

La primera decisión es dónde viven físicamente los datos de cada empresa. Hay tres respuestas habituales.

Modelo	Qué separa a los tenants	Qué cuesta
Base de datos compartida, columna `company_id`	Tu código, opcionalmente respaldado por row-level security en la base de datos	Lo más barato de operar: una migración, un pool de conexiones, un respaldo. El aislamiento es tan bueno como tu disciplina
Un schema por empresa (PostgreSQL)	El schema de la base de datos	Una frontera real, pero cada migración corre una vez por schema y cada petición tiene que cambiar de schema
Una base de datos por empresa	El servidor de base de datos	El aislamiento más fuerte y restauración por empresa, pero las migraciones, las conexiones y la factura crecen con cada cliente nuevo

Para un producto que todavía busca su mercado, yo empezaría con la base de datos compartida. Se parece al argumento de Modular Monolith or Microservices: A Framework for Deciding Without Dogma (en inglés): la opción más barata suele dar la mayor parte del beneficio, siempre que dejes abierta la salida. El precio es que el aislamiento ahora vive en tu código. El resto de este artículo trata de hacer que ese código sea difícil de esquivar.

La URL decide quién es el tenant

La siguiente pregunta: ¿cómo dice una petición a qué empresa pertenece? Un subdominio, una cabecera, la sesión, un segmento de la ruta. La opción tentadora es una columna "empresa actual" en el usuario. Cambias una vez y todas las peticiones posteriores ya lo saben. Se rompe en cuanto alguien abre dos pestañas. La columna guarda una respuesta por usuario, las pestañas piden dos, y gana la última que cambió, para ambas.

Yo prefiero la ruta: /{company-slug}/invoices. La URL es el único estado que pertenece a la petición misma. Sobrevive a los marcadores y a los enlaces compartidos, y pone al tenant en tus logs.

Un middleware resuelve el slug, comprueba la pertenencia y abre el contexto del tenant para el resto de la petición.

class ResolveCompany
{
    public function __construct(private TenantContext $tenant) {}

    public function handle(Request $request, Closure $next): Response
    {
        $user = $request->user() ?? throw new AuthenticationException;

        // Los bindings aún no se han ejecutado, así que esto sigue siendo el slug crudo.
        $company = Company::where('slug', $request->route('company'))->first();

        abort_if(
            $company === null || ! $user->companies()->whereKey($company->id)->exists(),
            404,
        );

        return $this->tenant->runAs($company->id, fn () => $next($request));
    }
}

Devuelvo 404 a quien no es miembro para que la URL no confirme que una empresa existe. Un 403 es más amable con un usuario legítimo que se equivocó al escribir, así que elige uno a conciencia.

Hay una trampa, y es de orden. El route model binding ocurre en SubstituteBindings, y cuando se resuelve {invoice}, esa consulta pasa por los global scopes del modelo. Si el tenant todavía no está definido, el binding corre sin scope. En la lista de prioridad de middleware por defecto de Laravel, ese middleware también está antes de la autenticación, y por eso el código de arriba lee el usuario por su cuenta. Mueve el middleware del tenant antes de los bindings en bootstrap/app.php:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->prependToPriorityList(
        before: \Illuminate\Routing\Middleware\SubstituteBindings::class,
        prepend: \App\Http\Middleware\ResolveCompany::class,
    );
})

Y las rutas:

Route::middleware(['auth', ResolveCompany::class])
    ->prefix('{company}')
    ->group(function () {
        Route::resource('invoices', InvoiceController::class);
    });

El middleware llama a algo llamado TenantContext. Esa es la siguiente pieza, y la que necesitará el job nocturno.

Un solo lugar que sabe cuál es la empresa actual

La solución a la historia del principio empieza con una regla: nadie lee el id de la empresa desde auth()->user(). Todo se lo pregunta a un objeto pequeño, y quien quiera ejecutar código como una empresa tiene que decirlo en voz alta.

final class TenantContext
{
    private ?int $companyId = null;

    public function id(): ?int
    {
        return $this->companyId;
    }

    public function runAs(int $companyId, Closure $callback): mixed
    {
        $previous = $this->companyId;
        $this->companyId = $companyId;

        try {
            return $callback();
        } finally {
            $this->companyId = $previous;
        }
    }
}

Regístralo con scoped, no con singleton:

$this->app->scoped(TenantContext::class);

Según la documentación del container, las instancias scoped se descartan cuando un worker de Octane toma una petición nueva o un worker de colas toma un job nuevo. Un singleton normal arrastraría al tenant anterior a la siguiente unidad de trabajo, que es la misma fuga con otro disfraz. El bloque finally es una segunda línea de defensa para el caso en que el código llame a runAs y lance una excepción.

Un scope que falla cerrado

Ahora la parte que todos escriben primero. Un global scope filtra todas las consultas de un modelo, y un trait puede engancharlo y rellenar company_id al crear. La diferencia con la versión habitual está en qué pasa cuando no hay empresa: lanza una excepción en lugar de omitir el filtro (fail closed).

class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model): void
    {
        $companyId = app(TenantContext::class)->id()
            ?? throw new MissingTenantContext($model::class);

        $builder->where($model->qualifyColumn('company_id'), $companyId);
    }
}

trait BelongsToCompany
{
    public static function bootBelongsToCompany(): void
    {
        static::addGlobalScope(new TenantScope);

        static::creating(function (Model $model): void {
            $model->company_id ??= app(TenantContext::class)->id()
                ?? throw new MissingTenantContext($model::class);
        });
    }
}

Acóplalo a una migración donde la columna no pueda ser nula y la empresa vaya primero en los índices, ya que casi todas las consultas filtran por ella:

$table->foreignId('company_id')->constrained();
$table->string('number');
$table->unique(['company_id', 'number']);

El costo de fallar cerrado es real. Las pantallas de administración, los seeders, los reportes entre todas las empresas y cualquier otra cosa que legítimamente necesite datos sin scope tienen que decirlo con Invoice::withoutGlobalScope(TenantScope::class). Yo lo cuento como una ventaja. Cada consulta sin scope es ahora una línea que puedes buscar con grep en la revisión de código, y la lista debería mantenerse corta.

Un scope también tiene puntos ciegos, y conviene conocerlos antes de confiar en él:

DB::table('invoices') y el SQL crudo nunca ven los scopes de Eloquent.
Las reglas de validación unique y exists consultan la tabla directamente, así que ignoran el scope. Agrega la condición tú mismo: Rule::unique('invoices', 'number')->where('company_id', $companyId).
Cualquier cosa que cruce un modelo que no use el trait es tan segura como ese otro modelo.

El job nocturno, otra vez

Volvamos al job de recordatorios. Con las reglas nuevas no puede correr como estaba escrito, porque nada define la empresa. Así que el job recibe la empresa de forma explícita y un middleware de job abre el contexto a su alrededor. El middleware de jobs, descrito en la documentación de colas, envuelve al job igual que el middleware de rutas envuelve una petición.

class RunsAsCompany
{
    public function handle(object $job, Closure $next): void
    {
        app(TenantContext::class)->runAs($job->companyId, fn () => $next($job));
    }
}

class SendOverdueReminders implements ShouldQueue
{
    use Queueable;

    public function __construct(public int $companyId) {}

    public function middleware(): array
    {
        return [new RunsAsCompany];
    }

    public function handle(): void
    {
        // Invoice::query() ahora está filtrada a $this->companyId
    }
}

El scheduler reparte un job por empresa:

Schedule::call(function () {
    Company::query()->each(
        fn (Company $company) => SendOverdueReminders::dispatch($company->id)
    );
})->dailyAt('02:00');

Tiene un costo: N jobs en lugar de uno. A cambio, una empresa lenta o que falla no bloquea a las demás, los reintentos se quedan dentro de un solo tenant y el tenant es visible en el payload en lugar de esconderse en estado ambiental. Company en sí no usa el trait, porque es el tenant.

Empresas, usuarios y roles

En un producto multiempresa, una persona suele pertenecer a varias empresas. Eso decide dónde vive el rol. Pertenece a la membresía, una tabla pivote company_user con una columna role, y no al usuario. La misma persona puede ser admin en una empresa y viewer en otra, y el middleware ya sabe de qué empresa trata la petición.

La tentación es darle un rango a los roles y comparar números. Funciona durante un tiempo. Los permisos como cadenas simples por rol (invoice:create, invoice:void) envejecen mejor, porque el día que alguien pida un rol que pueda anular facturas pero no editarlas, agregas una fila en lugar de reordenar una jerarquía. Comprueba los permisos con las policies de Laravel, y pasa el rol de la membresía, no una marca a nivel de usuario.

Demuéstralo con un test que intenta filtrar

Un scope que no has atacado es un scope que esperas que funcione. Tres tests cubren la historia hasta aquí, escritos con Pest:

it('nunca devuelve facturas de otra empresa', function () {
    $acme = Company::factory()->create();
    $globex = Company::factory()->create();
    $tenant = app(TenantContext::class);

    $tenant->runAs($globex->id, fn () => Invoice::factory()->create());

    expect($tenant->runAs($acme->id, fn () => Invoice::count()))->toBe(0);
});

it('se niega a consultar sin tenant', function () {
    Invoice::count();
})->throws(MissingTenantContext::class);

it('devuelve 404 para una empresa a la que el usuario no pertenece', function () {
    $other = Company::factory()->create();

    $this->actingAs(User::factory()->create())
        ->get("/{$other->slug}/invoices")
        ->assertNotFound();
});

El segundo test es el que habría atrapado la historia del principio. Cuando estos tests existan, agrega una guarda que liste todas las tablas con una columna company_id y falle si su modelo no usa el trait. Las tablas nuevas son donde nacen las fugas.

Dónde deja de funcionar el schema compartido

Este diseño tiene límites, y es mejor verlos pronto. Un solo tenant grande puede dominar los índices y el pool de conexiones, así que los vecinos ruidosos son una posibilidad real. Restaurar una empresa desde un respaldo significa extraer sus filas de un respaldo de todos. Y algunos clientes, sobre todo los enterprise o regulados, pedirán su propia base de datos por muy bueno que sea tu scope.

El diseño también te deja una salida. Como todas las consultas pasan por un solo contexto y un solo trait, mover a un cliente grande a su propia base de datos más adelante es un refactor mucho más pequeño que en un código lleno de cláusulas where escritas a mano. Ese es el argumento para hacerlo así aunque nunca necesites la salida.

Conclusión

El job nocturno que envió correos a los clientes equivocados no necesitaba un filtro más ingenioso. Necesitaba un sistema donde correr sin empresa sea un error, y donde ese error aparezca en un test mucho antes de que lo vea un cliente. Resuelve el tenant desde la URL, guárdalo en un solo lugar, haz que el scope falle cerrado e intenta filtrar a propósito.

Si quieres una acción para hoy, busca con grep en tu código auth()->user()->company_id y withoutGlobalScopes, y escribe el test "se niega a consultar sin tenant". En el siguiente artículo dejamos atrás el aislamiento y vemos dónde debe vivir la lógica de negocio para que los controladores se mantengan delgados.

Building a Multi-Tenant SaaS in Laravel: The Series I Wish I Had Read First: 01 of 08

Ivan Firestone — Tue, 03 Nov 2026 01:00:07 +0000

This is the article I would have wanted to read before I started building a multi-tenant system. It would have saved me time, a lot of rewritten code, and many hours migrating systems that were already running.

Most of the expensive decisions in a multi-tenant SaaS are cheap on day one and costly on day four hundred. Where the tenant lives in the schema, how a request finds its company, what a background job knows about who it works for: you can get each of them right in an afternoon at the start, or fix them later with a migration, a rewrite and a nervous deploy. I know the second path because I have walked it. This series is what I would do on the first day if I started again, knowing what I know now.

Here is one of those paths. I started multi-tenant, but not multi-user. Adding multi-user later wasn't a feature. It was a rewrite that touched the whole system. And the guards that kept one tenant's data away from another weren't built as well as they should have been. Both problems sit at the foundation, which is why the first article of the series deals with who belongs to which company and how a request finds out.

What This Series Is

It is a set of decisions with reasons attached, written for developers who already build with Laravel and want to design and deliver a multi-tenant SaaS without learning the hard parts the slow way. Every article follows the same fictional product, an invoicing app where the tenant is a Company, so the examples connect from one article to the next.

It is not a package guide, and it is not a framework. You won't find a library to install that solves tenancy for you. You will find the pieces I think are worth building yourself, why, and what each one costs. Where a decision is a judgment call, I say so.

What It Assumes

A few choices are fixed so the series can go deep instead of wide:

One Laravel application and one database, with a company_id column on tenant-owned tables. If you are still deciding between a modular monolith and microservices, that is a different question, and I wrote about how to approach it in Modular Monolith or Microservices: A Framework for Deciding Without Dogma.
Laravel 13 and PostgreSQL in the examples, although most of it applies to other versions and to MySQL. The one article that depends on PostgreSQL says so up front.
A reader with some experience. I don't explain what a middleware or a queue is.

What it leaves out on purpose: a separate database per tenant, single sign-on, and the details of any specific payment provider. Each is worth its own series, and none of them is where a first version usually hurts.

What You'll Find

These are the articles in the order I would read them. Each one stands on its own once you know the tenant context from the first. I update this list as the series is published: a title with a link is already out, and a title without one is still to come.

Multi-Tenant SaaS in Laravel: One Database, a Global Scope, and the Leaks It Doesn't Catch. The foundation: how a request finds its company, a scope that fails closed, and what the scope still misses.
Killing Fat Controllers in Laravel: Actions as the Home for Business Logic. Where the rules live, so a controller, a command and an API share one implementation.
Data Objects, Concerns and Events: The Supporting Cast of a Laravel Action. What feeds an Action, what it shares and what it announces, with the tenant context carried into queued listeners.
From Idea to First Paying Customer: A Delivery Roadmap for a Multi-Tenant Laravel SaaS. The order of work: walls before rooms, one slice early, plan limits, billing webhooks and safe deploys.
Testing Tenant Isolation in Laravel: Leak Tests, Guard Tests and What They Still Miss. How to prove, on every commit, that one company can't see another.
Observability Per Tenant in Laravel: Logs, Metrics and Errors by Company. How to answer "what happened to this company?" without drowning in data.
Row-Level Security in PostgreSQL: A Second Wall for a Multi-Tenant Laravel App. An optional database-level layer behind the application scope, and the cases where it is worth its cost.

How to Read It

Two habits will help. First, treat the code as a starting point. The snippets are small on purpose, and I haven't run them against your schema, your policies or your deploy setup. Second, pay attention to the cost sections. Every pattern here has a price, and the honest question is not "is this good practice?" but "is it worth it for my team, at my size, this year?"

Sometimes the answer is no. A pass-through Action, a Data object for two arguments or a database policy for a prototype are all ways to spend effort you needed elsewhere.

Conclusion

I'm writing this series because the most useful advice I can give my past self is also the advice most teams hear too late: decide the foundations early, make them testable, and keep the rest boring. If you are about to start a multi-tenant product, or you are early enough that the foundations can still change, begin with the tenant context. Everything else in the series is built on it.

Migrar de un sistema legacy a microservicios sin documentación ni control total

Ivan Firestone — Sat, 31 Oct 2026 13:00:07 +0000

Cómo reemplazar un sistema legacy que no puedes leer del todo, cambiar ni apagar: aprende primero su comportamiento real, rodéalo con una fachada strangler y demuestra que los nuevos servicios igualan a los viejos antes de hacer el corte.

Imagina una empresa cuya tienda en línea lleva doce años funcionando sobre una sola aplicación. Los autores originales se fueron hace mucho. El wiki describe una versión del sistema que ya no existe. Un módulo lo escribió un proveedor y llega como una librería compilada de la que nadie tiene el código fuente. Y aun así la tienda procesa pedidos todos los días, y el negocio repite lo mismo que dijo el año pasado: "funciona, no lo rompas".

Entonces alguien escribe "migrar a microservicios" en el roadmap.

Este artículo sigue a esa tienda hipotética por las partes de una migración que los diagramas habituales se saltan: no saber qué hace realmente el sistema, no tener permiso para cambiarlo y tener que superar algo que lleva años probado en batalla. Si todavía estás decidiendo si los microservicios son el destino correcto, empieza por Arquitectura Microservicios y Monolito modular o microservicios: un marco para decidir sin dogmas. Aquí damos la decisión por tomada y preguntamos cómo sobrevivirla.

La reescritura que parecía un plan

El primer instinto es empezar de cero: construir el sistema nuevo al lado del viejo y cambiar cuando esté listo. Tienta porque promete dejar atrás el desorden.

Falla por una razón que no tiene nada que ver con la calidad del código. Mientras se construye el sistema nuevo, el viejo sigue cambiando: correcciones de errores, reglas de precios, un ajuste regulatorio. El objetivo se mueve. El equipo termina manteniendo dos sistemas sin terminar ninguno, y el cambio se convierte en un solo evento grande e irreversible que no se pudo probar con tráfico real.

La alternativa tiene nombre: la higuera estranguladora (strangler fig), descrita por Martin Fowler en Strangler Fig y documentada en el Azure Architecture Center. Como la enredadera que crece alrededor de un árbol, el sistema nuevo envuelve al viejo y lo reemplaza pieza por pieza, mientras el viejo sigue atendiendo a los usuarios. Cada paso es pequeño y reversible. Esa propiedad es la que hace posible todo lo demás en este artículo.

Pero un strangler necesita saber dónde cortar. Y para eso, la tienda primero tiene que responder una pregunta incómoda.

¿Qué hace realmente el sistema viejo?

Sin documentación confiable, la fuente de verdad es el sistema en ejecución. El código te dice lo que puede hacer; producción te dice lo que hace. No son la misma lista.

El equipo empieza escuchando, más o menos en este orden:

Capturar tráfico real. Los logs de acceso, los del API gateway o un proxy delante de la aplicación legacy muestran qué endpoints se llaman, con qué frecuencia y con qué payloads. Los endpoints que nadie llama desde hace un año son candidatos a eliminarse, no a migrarse.
Leer la base de datos como un contrato. Las tablas, las llaves foráneas, los triggers y los procedimientos almacenados suelen guardar reglas de negocio que nunca llegaron al código de la aplicación. Un trigger que descuenta stock cuando se inserta un pedido es una funcionalidad, aunque ningún desarrollador recuerde haberlo escrito.
Listar los consumidores ocultos. Jobs nocturnos, hojas de cálculo que consultan la base de datos directamente, un socio que llama a un endpoint no documentado. Son los clientes que se rompen en silencio.
Escribir pruebas de caracterización. Michael Feathers llama characterization tests (en Working Effectively with Legacy Code) a las pruebas que registran lo que el código hace hoy, bien o mal. Envías entradas conocidas, guardas las salidas, y desde entonces cualquier cambio de comportamiento se hace visible.

Las pruebas de caracterización no dicen que el comportamiento legacy sea correcto. Dicen que es el comportamiento del que dependen hoy tus clientes. Si una rareza es un error o una funcionalidad es una decisión de negocio, y es mucho más barato tomarla antes de la migración que después.

Al final de esta fase la tienda tiene algo que nunca tuvo: una descripción escrita y ejecutable de su propio sistema. Solo ahora puede elegir qué extraer primero.

Cortar donde no puedes editar

Aquí aparece el segundo problema. Supón que la tienda quiere mover los pagos a su propio servicio. El paso obvio es cambiar el código legacy para que llame al servicio nuevo en lugar de a su módulo interno de pagos. Pero el equipo no puede: el módulo es un binario del proveedor, o el proceso de release de la aplicación legacy tarda meses, o nadie se atreve a tocar el archivo.

Cuando no puedes cambiar el interior, trabajas por fuera. Hay tres costuras que no requieren editar el código legacy:

El borde. Pon una fachada, como un reverse proxy o un API gateway, delante de la aplicación legacy. Al principio reenvía todo. Luego, ruta por ruta, envía peticiones específicas al servicio nuevo. Los usuarios ven las mismas URLs; la fachada decide quién responde.
Los datos. Si el servicio nuevo necesita datos que son de la base de datos legacy, no la consultes directamente desde el servicio nuevo. Captura los cambios con change data capture o una exportación estilo outbox y aliméntalos al servicio nuevo, para que el esquema legacy siga siendo un detalle de implementación.
La capa de traducción. El sistema legacy habla su propio dialecto: códigos de estado raros, un registro de cliente con cuarenta columnas, fechas guardadas como texto. Una capa anticorrupción (anti-corruption layer, un término de Domain-Driven Design) traduce entre ese dialecto y el modelo limpio del servicio nuevo. Sin ella, el diseño legacy se filtra a cada servicio nuevo y acabas reconstruyendo el sistema viejo en piezas más pequeñas.

# Reglas ilustrativas de gateway: la fachada es dueña de la decisión de enrutamiento

routes:



path: /api/payments/**
target: payments-service   # nuevo

path: /** target: legacy-app # todo lo demás, sin cambios

La fachada también le da a la tienda su red de seguridad. Si el servicio nuevo de pagos se comporta mal, volver atrás es un cambio de enrutamiento, no un despliegue.

El primer servicio ya corre detrás de la fachada. La siguiente pregunta es la que le importa al negocio: ¿es tan bueno como lo que reemplazó?

Superar a un sistema con doce años de pruebas

Los sistemas legacy tienen una ventaja fácil de subestimar: los ha golpeado cada pedido extraño, cada tormenta de reintentos, cada reporte de fin de mes. El servicio nuevo, en comparación, no ha sido probado en el mundo real. "Código más limpio" no es un argumento que sobreviva al primer incidente.

Por eso la tienda trata la paridad como un requisito con evidencia, en cuatro pasos:

Medir primero la línea base del legacy. Percentiles de latencia, tasa de errores, throughput en el pico y el costo de operarlo. No puedes afirmar que igualas algo que nunca mediste, y un monolito viejo en una red local suele ser más rápido por petición que un sistema distribuido con saltos de red.
Definir "al menos igual de bueno" por capacidad. En pagos importan más la corrección y la idempotencia que la velocidad pura. En la búsqueda de productos importa más la latencia. Escríbelo como objetivos de nivel de servicio (SLO) antes de construir.
Correr en modo sombra. La fachada envía cada petición real al sistema legacy, que responde al usuario, y una copia al servicio nuevo, cuya respuesta solo se registra. Compara las dos respuestas. Las diferencias son errores del servicio nuevo o comportamiento no documentado del viejo, y ambos conviene encontrarlos antes de que afecten a un cliente.
Mover el tráfico gradualmente. Usa feature flags o enrutamiento ponderado: una parte pequeña del tráfico, luego más, vigilando los SLO en cada paso. El camino legacy se mantiene vivo hasta que el nuevo haya aguantado un ciclo de negocio completo, incluidos los momentos incómodos como el cierre de mes.

El modo sombra tiene costos que conviene decir. Las peticiones duplicadas no deben duplicar efectos secundarios, así que una llamada de pago en sombra necesita un modo "dry run" o un sandbox. Y necesitas observabilidad real en ambos lados antes de que nada de esto funcione: trazas, métricas y logs que puedas correlacionar.

Lo que esto te cuesta

Una migración así es más lenta e incómoda que una reescritura en el papel. Sé honesto con la factura:

Dos sistemas a la vez. Durante un buen tiempo operas, parchas y aseguras ambos. El sistema legacy no se abarata mientras lo reemplazas.
Una fachada de apariencia permanente. El gateway y la capa anticorrupción son componentes extra que hay que operar. Algunos sobrevivirán a la migración.
La complejidad de los sistemas distribuidos llega con el primer servicio, como se describe en Arquitectura Microservicios : fallos de red, versionado, monitoreo entre servicios.
No todo debe moverse. Algunos módulos son estables, cambian poco y no tienen problemas de escala. Dejarlos en el núcleo legacy, detrás de la fachada, puede ser el estado final correcto.

Depende del sistema, pero un resultado común es un núcleo legacy más pequeño que se queda, rodeado de un puñado de servicios que se ganaron su independencia.

Conclusión

La tienda del principio creía que su problema era la tecnología vieja. Los problemas más difíciles resultaron ser el conocimiento que faltaba, el acceso restringido y una vara de prueba muy alta. Cada uno tiene una respuesta práctica: aprender el comportamiento real desde producción, trabajar por el borde, los datos y una capa de traducción en lugar de editar lo intocable, y tratar la paridad con el sistema legacy como algo que se mide, no que se supone.

Si enfrentas una migración así, un primer paso concreto es pequeño: pon un proxy delante de la aplicación legacy, reenvía todo y empieza a leer los logs. En una semana aprenderás más sobre tu sistema que lo que el wiki te ha dicho en años.

Construir un SaaS multi-tenant en Laravel: la serie que me habría gustado leer primero: 01 de 08

Ivan Firestone — Fri, 30 Oct 2026 13:00:07 +0000

Por qué escribo una serie sobre diseñar y entregar un SaaS multi-tenant en Laravel: qué haría distinto desde el primer día, qué cubre la serie, a quién va dirigida y cómo leerla.

Este es el artículo que habría querido leer antes de empezar a construir un sistema multi-tenant. Me habría ahorrado tiempo, mucho código reescrito y muchas horas migrando sistemas que ya estaban en marcha.

La mayoría de las decisiones caras en un SaaS multi-tenant son baratas el día uno y costosas el día cuatrocientos. Dónde vive el tenant en el schema, cómo una petición encuentra su empresa, qué sabe un job en segundo plano sobre para quién trabaja: cada una se puede resolver bien en una tarde al principio, o arreglar después con una migración, una reescritura y un deploy con los nervios de punta. Conozco el segundo camino porque lo he recorrido. Esta serie es lo que haría el primer día si empezara de nuevo, sabiendo lo que sé ahora.

Aquí va uno de esos caminos. Empecé multi-tenant, pero no multiusuario. Añadir el multiusuario después no fue una funcionalidad. Fue una reescritura que tocó todo el sistema. Y las guardas que mantienen los datos de un tenant lejos de otro no estaban tan bien construidas como debían. Los dos problemas están en los cimientos, y por eso el primer artículo de la serie trata de quién pertenece a qué empresa y cómo lo descubre una petición.

Qué es esta serie

Es un conjunto de decisiones con sus razones adjuntas, escrito para desarrolladores que ya construyen con Laravel y quieren diseñar y entregar un SaaS multi-tenant sin aprender las partes difíciles por el camino lento. Cada artículo sigue el mismo producto ficticio, una app de facturación donde el tenant es una Company, de modo que los ejemplos conectan de uno a otro.

No es una guía de paquetes, y no es un framework. No encontrarás una librería que instalar que te resuelva el tenancy. Encontrarás las piezas que creo que vale la pena construir tú mismo, por qué, y qué cuesta cada una. Donde una decisión es cuestión de criterio, lo digo.

Qué asume

Unas pocas elecciones están fijadas para que la serie pueda ir en profundidad y no en extensión:

Una aplicación Laravel y una base de datos, con una columna company_id en las tablas que pertenecen a un tenant. Si todavía decides entre un monolito modular y microservicios, esa es otra pregunta, y escribí sobre cómo abordarla en Monolito modular o microservicios: un marco para decidir sin dogmas.
Laravel 13 y PostgreSQL en los ejemplos, aunque casi todo aplica a otras versiones y a MySQL. El único artículo que depende de PostgreSQL lo dice desde el principio.
Un lector con algo de experiencia. No explico qué es un middleware ni una cola.

Lo que se deja fuera a propósito: una base de datos separada por tenant, el single sign-on y los detalles de cualquier proveedor de pagos concreto. Cada uno merece su propia serie, y ninguno es donde suele doler una primera versión.

Qué encontrarás

Estos son los artículos en el orden en que yo los leería. Cada uno se sostiene solo una vez que conoces el contexto del tenant del primero. Actualizo esta lista a medida que se publica la serie: un título con enlace ya está publicado, y un título sin enlace está por llegar.

SaaS multi-tenant en Laravel: una base de datos, un global scope y las fugas que no detecta. El cimiento: cómo una petición encuentra su empresa, un scope que falla cerrado y lo que el scope todavía no ve.
Adiós a los controladores gordos en Laravel: las Actions como hogar de la lógica de negocio. Dónde viven las reglas, para que un controlador, un comando y una API compartan una sola implementación.
Data objects, Concerns y Events: el reparto de apoyo de una Action en Laravel. Qué alimenta a una Action, qué comparte y qué anuncia, con el contexto de tenant llevado a los listeners en cola.
De la idea al primer cliente de pago: una hoja de ruta de entrega para un SaaS multi-tenant en Laravel. El orden del trabajo: muros antes que habitaciones, un slice temprano, límites de plan, webhooks de facturación y deploys seguros.
Probar el aislamiento entre tenants en Laravel: tests de fuga, tests de guarda y lo que aún no detectan. Cómo demostrar, en cada commit, que una empresa no puede ver a otra.
Observabilidad por tenant en Laravel: logs, métricas y errores por empresa. Cómo responder "¿qué le pasó a esta empresa?" sin ahogarte en datos.
Row-Level Security en PostgreSQL: un segundo muro para una app Laravel multi-tenant. Una capa opcional a nivel de base de datos detrás del scope de la aplicación, y los casos en que vale su costo.

Cómo leerla

Dos hábitos ayudarán. Primero, trata el código como un punto de partida. Los fragmentos son pequeños a propósito, y no los he ejecutado contra tu schema, tus policies ni tu configuración de deploy. Segundo, presta atención a las secciones de costos. Cada patrón de aquí tiene un precio, y la pregunta honesta no es "¿es esto una buena práctica?" sino "¿vale la pena para mi equipo, a mi tamaño, este año?".

A veces la respuesta es que no. Una Action de paso, un Data object para dos argumentos o una política de base de datos para un prototipo son formas de gastar un esfuerzo que necesitabas en otro sitio.

Conclusión

Escribo esta serie porque el consejo más útil que puedo darle a mi yo del pasado es también el que la mayoría de los equipos oye demasiado tarde: decide los cimientos pronto, hazlos comprobables y mantén aburrido todo lo demás. Si estás a punto de empezar un producto multi-tenant, o estás lo bastante al principio como para que los cimientos aún puedan cambiar, empieza por el contexto del tenant. Todo lo demás de la serie se apoya en él.

Arquitectura de microservicios

Ivan Firestone — Wed, 28 Oct 2026 13:00:07 +0000

Imagina una tienda en línea pequeña. Un solo código, una sola base de datos, un solo despliegue. Los clientes inician sesión, ven productos, pagan y reciben un correo. Funciona, y durante mucho tiempo nadie lo cuestiona.

Luego la tienda crece y empiezan las preguntas. ¿Por qué un error en la página de productos nos obliga a volver a desplegar el código de pagos? ¿Por qué toda la aplicación se pone lenta cada vez que alguien sube un lote de fotos de productos? En algún momento, alguien dice la palabra: microservicios.

Este artículo sigue a esa tienda. Veremos qué son los microservicios, las pautas que indican cuándo una funcionalidad merece convertirse en uno, qué se gana y cuánto cuesta. No entraremos a fondo en cómo construirlos; esa es una historia para otro día.

¿Qué es realmente un microservicio?

Una arquitectura de microservicios divide una aplicación en servicios pequeños e independientes, cada uno responsable de una capacidad del sistema. En lugar de un solo programa que lo hace todo, la tienda pasa a ser un conjunto de programas que se comunican entre sí, normalmente a través de APIs.

La palabra clave es independiente. Cada servicio se puede desarrollar, desplegar y escalar por separado. Esa independencia es todo el punto, y también es lo que hace difícil la decisión: solo obtienes los beneficios si las piezas son realmente separables.

Entonces, ¿cuáles lo son? Recorramos la tienda para averiguarlo.

¿Qué funcionalidades merecen su propio servicio?

No toda funcionalidad justifica un servicio propio. Estas son seis pautas, y cada una aparece a medida que la tienda crece.

1. La funcionalidad puede valerse por sí sola

El inicio de sesión y los pagos son los primeros candidatos. Ninguno necesita saber cómo se muestran los productos ni cómo se envían los pedidos. Reciben una petición, hacen un trabajo y devuelven una respuesta.

Eso es autonomía funcional: si una funcionalidad puede operar sin estar fuertemente acoplada al resto del sistema, es una buena candidata. La autenticación y la gestión de pagos son ejemplos clásicos.

2. Necesita escalar de forma distinta

Ahora la tienda agrega la subida de imágenes. Cada foto de producto se redimensiona y se comprime, y durante una importación grande del catálogo los servidores se calientan. Pero la página de pago no necesita más potencia que antes.

Escalar toda la aplicación para atender una sola tarea pesada es un desperdicio. Cuando una funcionalidad tiene requisitos de escalado distintos al resto, como un servicio de procesamiento de imágenes que necesita mucho cómputo, un servicio separado te permite escalar solo lo que está bajo presión.

3. Otros sistemas también la necesitan

La tienda lanza una segunda marca con su propio sitio web. Ambas necesitan enviar confirmaciones de pedido y restablecimientos de contraseña por correo. Copiar el código de correo al segundo proyecto funcionaría, hasta el día en que una copia recibe una corrección y la otra no.

Si varios sistemas o aplicaciones usan la misma capacidad, convertirla en un servicio fomenta la reutilización y elimina la duplicación. Un servicio de notificaciones por correo es el ejemplo de siempre.

4. Cambia a otro ritmo

El equipo añade recomendaciones de productos con machine learning. Los modelos se reentrenan y se ajustan constantemente, mientras que el flujo de pago cambia unas pocas veces al año. Atarlos al mismo ciclo de releases frena a uno y pone en riesgo al otro.

Cuando una funcionalidad necesita un ciclo de desarrollo y despliegue distinto al del resto del sistema, debería ser su propio servicio. Un servicio de recomendaciones que necesita actualizaciones frecuentes encaja bien.

5. Corresponde a un dominio de negocio claro

Mira cómo habla el negocio de sí mismo: catálogo, pedidos, pagos, inventario. En el Diseño Guiado por el Dominio (Domain-Driven Design, DDD), estos son subdominios: áreas del negocio con su propio lenguaje y sus propias reglas.

Las funcionalidades que corresponden a un subdominio bien definido son candidatas ideales. Un servicio de inventario en un sistema de comercio electrónico, por ejemplo, refleja cómo el negocio ya piensa.

6. Tiene el tamaño adecuado

Esta es la pauta que la gente olvida. Imagina dividir la tienda tan lejos que "dar formato a un precio" se vuelve un servicio. Ahora cada operación simple requiere una llamada de red, y el sistema es un laberinto.

Un microservicio debe ser lo bastante pequeño para enfocarse en una tarea, pero lo bastante grande para no fragmentar el sistema en exceso. Si una funcionalidad es trivial, o depende mucho de otras, probablemente no merece ser un servicio.

Lo que gana la tienda

Supongamos que la tienda sigue esas pautas y separa las piezas correctas. ¿Qué cambia?

Escalabilidad. El servicio de imágenes escala durante una importación mientras todo lo demás se queda como está.
Flexibilidad tecnológica. El servicio de recomendaciones puede usar el lenguaje y las herramientas más adecuados para machine learning, sin imponérselos al resto del sistema.
Desarrollo y despliegue independientes. Distintos equipos pueden trabajar en distintos servicios al mismo tiempo, lo que acelera el desarrollo y la entrega continua.
Resiliencia. Como los servicios están desacoplados, la caída de uno no tumba necesariamente al resto. Si las recomendaciones se caen, los clientes todavía pueden pagar.
Reutilización. Un servicio bien diseñado, como el de correo, se puede reutilizar en distintos proyectos y contextos.
Mantenimiento más fácil. Corregir un error o actualizar un servicio no implica tocar toda la aplicación.

Lo que paga la tienda

Si esa fuera toda la historia, todos los proyectos empezarían con microservicios. No lo es.

Dividir un sistema convierte llamadas a función en llamadas de red, y un solo código en muchas piezas móviles. La tienda ahora necesita monitoreo avanzado para ver qué pasa entre servicios, un versionado cuidadoso para que un servicio no rompa a otro, y un plan para saber cómo se comunican los servicios cuando algo sale mal.

Esos costos son reales, y caen sobre ti el día que divides. Por eso conviene analizar con cuidado antes de convertir una funcionalidad en un servicio nuevo.

De vuelta a la tienda

La tienda no necesitó microservicios el primer día. Los necesitó cuando funcionalidades específicas empezaron a tirar en direcciones distintas: otra carga, otro ritmo de releases, otros consumidores. Las seis pautas anteriores son una forma de notar ese momento, y de notar cuándo todavía no ha llegado.

Usados con intención, los microservicios permiten que un equipo se concentre en la calidad, la escalabilidad y la agilidad. Usados por moda, solo añaden complejidad. Si todavía estás sopesando los pros y contras, Monolito modular o microservicios: un marco para decidir sin dogmas profundiza en esa decisión.

Malos hábitos en el desarrollo web que debemos evitar

Ivan Firestone — Tue, 27 Oct 2026 13:00:06 +0000

Imagina que acabas de lanzar un sitio web. En tu monitor de 27 pulgadas se ve genial. Luego un amigo lo abre en su teléfono y te manda una captura: el menú se desborda, los botones son diminutos y la mitad de la página exige scroll lateral.

Nada en el código está "mal" de una forma que lance un error. Simplemente el sitio arrastra unos cuantos hábitos silenciosos que lo empeoran para las personas reales, y también para quien lo mantiene. Son fáciles de adquirir, porque cada uno ahorra un poco de tiempo hoy y lo cobra después.

Estos son cinco de los más comunes. Para cada uno veremos cómo muerde y qué hacer en su lugar. Empezamos con el de aquella captura.

1. No pensar en el móvil desde el principio

La mayoría de los usuarios llega a la web desde un teléfono. Tratar el móvil como un añadido, algo donde se encaja el diseño de escritorio al final, es un error crítico. Corregirlo tarde significa deshacer decisiones sobre las que se construyó toda la página.

Un enfoque mobile-first invierte el orden: primero asegúrate de que el sitio funcione y se vea bien en pantallas pequeñas, y luego escala a las grandes.

Qué hacer:

Prototipa primero el diseño móvil y revisa la experiencia en distintos tamaños de pantalla.
Escribe los estilos base para pantallas pequeñas y usa media queries con min-width para mejorar en las grandes.

/* Base: pantallas pequeñas */
.card-list {
  display: grid;
  gap: 1rem;
  grid-template-columns: 1fr;
}

/* Pantallas grandes: mejoras */
@media (min-width: 768px) {
  .card-list {
    grid-template-columns: repeat(3, 1fr);
  }
}

Cuando el diseño aguanta en todas las pantallas, lo siguiente que nota un visitante es si las páginas parecen pertenecer al mismo sitio.

2. Ser inconsistente

Imagina a un visitante navegando por tu sitio. En la página de inicio, el enlace activo es azul. En la de precios, es verde. En el blog, va subrayado y en rojo. Nada está roto, pero el visitante empieza a preguntarse si sigue en el mismo sitio.

El diseño, los enlaces y los estilos inconsistentes confunden a los usuarios y hacen que un producto parezca poco profesional.

Qué hacer:

Define y sigue una guía de estilo que cubra colores, tipografía, botones y enlaces.
Usa un sistema de diseño (Material Design, Bootstrap o uno propio) para mantener la coherencia visual y funcional.
Centraliza los valores de diseño como tokens en lugar de repetirlos:

:root {
  --color-link: #0b5fff;
  --color-link-active: #0a3fb3;
}

a { color: var(--color-link); }
a:active, a[aria-current="page"] { color: var(--color-link-active); }

Cambias el token una vez y todas las páginas lo siguen. Justo lo contrario de lo que pasa con el siguiente hábito.

3. Escribir URLs fijas en el código

Digamos que el sitio tiene cien páginas, cada una enlazando a https://www.mysite.com/.... Entonces cambia el dominio. O alguien necesita una copia de staging para probar un release. De pronto todos los enlaces apuntan al lugar equivocado, y la solución es un buscar y reemplazar en todo el proyecto.

Las URLs fijas en el código fuente hacen que un sitio sea más difícil de mantener y de escalar. Se rompen cada vez que cambia el dominio o cuando trabajas con varios entornos (desarrollo, staging, producción).

Qué hacer:

Prefiere rutas relativas en lugar de absolutas para los enlaces internos y los recursos.
Usa variables de entorno para manejar las URLs que dependen del entorno, como la URL base de una API.

// Mal
fetch("<https://api.mysite.com/users>");

// Mejor
fetch(`${process.env.API_BASE_URL}/users`);

<!-- Mal -->
<a href="<https://www.mysite.com/about>">Acerca de</a>

<!-- Mejor -->
<a href="/about">Acerca de</a>

Hasta aquí vimos hábitos que perjudican a quienes mantienen el sitio. El siguiente perjudica a quienes no pueden ver la página.

4. Omitir el atributo `alt` en las imágenes

Piensa en alguien que usa un lector de pantalla y llega a la página de tu producto. Donde debería haber una foto del producto, el lector dice solo "imagen" o, peor, lee en voz alta un nombre de archivo como IMG_4821.jpg. Lo mismo le pasa a cualquiera cuando una imagen no carga por una mala conexión.

El atributo alt describe una imagen a los usuarios con discapacidad visual y a todos cuando la imagen no carga. Omitirlo hace la página más difícil de usar, y además perjudica el SEO.

Qué hacer:

Da a cada imagen con significado una descripción clara y concisa.
Si una imagen es puramente decorativa, usa un alt="" vacío para que la tecnología de asistencia la salte en lugar de leer un nombre de archivo.

<!-- Informativa -->
<img src="chart.png" alt="Gráfico de barras que muestra el tráfico móvil creciendo 40% interanual">

<!-- Decorativa -->
<img src="divider.svg" alt="">

Los lectores de pantalla dependen tanto de la estructura de la página como de sus imágenes, lo que nos lleva al último hábito.

5. Usar demasiados `div`s

Abre el HTML de una página construida así y encontrarás div dentro de div dentro de div, cada uno con un nombre de clase que intenta decir qué es en realidad el elemento. Para una persona es tedioso. Para un lector de pantalla o un motor de búsqueda, es una página sin puntos de referencia para orientarse.

Recurrir a div cuando existe un elemento semántico específico hace el código más difícil de leer y perjudica la accesibilidad y el SEO. Los lectores de pantalla y los motores de búsqueda dependen de elementos como header, nav, main, section, article y footer para entender la estructura de la página.

Qué hacer:

Usa elementos semánticos para estructurar tu HTML.
Deja div para agrupaciones genéricas, cuando ningún elemento mejor encaje.

<!-- Sopa de divs -->
<div class="header">...</div>
<div class="main">
  <div class="article">...</div>
</div>
<div class="footer">...</div>

<!-- Semántico -->
<header>...</header>
<main>
  <article>...</article>
</main>
<footer>...</footer>

De vuelta a aquella captura

Vuelve a la captura de tu amigo, la del principio. Detrás del menú desbordado puede haber un diseño sin enfoque mobile-first, estilos inconsistentes, una URL fija, una imagen sin descripción y una página hecha solo de divs. Ninguno fue una decisión grande, pero juntos forman un sitio más difícil de usar y más difícil de mantener.

Evitar estos hábitos mejora más que el código: mejora la experiencia de usuario, la accesibilidad y la eficiencia del desarrollo. Incorporarlos desde el inicio hace un sitio más fácil de mantener y más robusto.

Elige un proyecto, revísalo contra esta lista y corrige lo que encuentres.

A Local Development Toolbox with Docker Compose: Databases, Cloud Emulators and Mocks

Ivan Firestone — Mon, 26 Oct 2026 12:00:05 +0000

How to build a reproducible local environment with Docker Compose for databases, MinIO, AWS/Azure/GCP emulators and WireMock, and what trade-offs it has.

Testing integrations against real services is slow, costly and sometimes dangerous. I built a repository, dev-tools, that gathers in one place everything needed to set up a local environment and test without depending on real services:

Local databases and storage with Docker Compose.
AWS, Azure and GCP emulators.
A mock server with WireMock.
Sample data in JSON.

This article explains the idea, how to use it and, above all, its limits.

The Problem

A typical project depends on a database, object storage, sometimes cloud services and third-party APIs. Without a consistent local environment, familiar things happen:

"It works on my machine", because each developer installed different versions.
Tests that depend on someone else's sandbox that goes down or has usage limits.
Real credentials on development machines, an unnecessary risk.
Slow onboarding: days to get the environment working.

The solution is to declare the environment as code and bring it up with one command.

Repository Structure

Each folder is independent: you only use the one you need.

dev-tools/

├── dev-infra/    # Local databases and storage

├── floci/        # AWS / Azure / GCP cloud emulators

├── wiremock/     # Mock server + Postman and Bruno collections

├── demo/         # Sample data in JSON

`dev-infra`: Databases and Storage

A Compose file with MinIO, PostgreSQL, MySQL, Redis, Oracle, MongoDB and SQL Server, with a development user created in each service. Credentials live in a local .env that isn't versioned; only the .env.example template is published.

`floci`: Cloud Emulators

Local emulators for AWS, Azure and GCP with a unified web console, using the images from the open-source Floci project. They let you develop against the S3, DynamoDB, Lambda and other service APIs without a real account or costs.

`wiremock`: Third-Party API Mocks

A WireMock server with an admin interface, sample stubs and Postman and Bruno collections. It's used to simulate external APIs: successful responses, errors, latencies and edge cases that are hard to trigger on the real service.

`demo`: Sample Data

Bilingual JSON catalogs (countries, banks, professions…) to use in seeds, mocks and tests.

How to Use It

git clone https://github.com/ifirestone/dev-tools.git cd dev-tools Local credentials (not versioned) cp dev-infra/.env.example dev-infra/.env Each stack is independent

docker compose -f dev-infra/docker-compose.yml up -d docker compose -f floci/docker-compose.yml up -d docker compose -f wiremock/docker-compose.yml up -d

The three stacks don't share ports, so they can run at the same time. To shut one down:

docker compose -f <folder>/docker-compose.yml down      # keeps data


docker compose -f <folder>/docker-compose.yml down -v   # also deletes data

An example with the AWS emulator:

export AWS_ACCESS_KEY_ID=test export AWS_SECRET_ACCESS_KEY=test export AWS_DEFAULT_REGION=us-east-1

aws --endpoint-url http://localhost:4566 s3 ls

Your application code only changes the endpoint. The rest of the client is the same one you'd use in the real cloud.

Why Mocks in Addition to Emulators

Emulators cover services with a public, stable API. For specific third-party APIs (a payment provider, a corporate platform) there is no emulator, and that's where WireMock helps:

Determinism: the response is always the same, so tests aren't brittle.
Error cases on demand: a 500, a timeout or a malformed response can be simulated in seconds.
Parallel work: you can develop the integration before having access to the provider's sandbox.
Explicit contract: the stubs document how you expect the third party to respond.

Trade-offs and Limits (What You Should Know)

A toolbox like this has costs, and they're worth stating:

Partial fidelity. An emulator doesn't replicate 100% of the real cloud's behavior: permissions, quota limits and edge cases may differ. Use it for development and quick tests, not as a substitute for testing against the real service before production.
Resource consumption. Oracle and SQL Server use a lot of memory. If your machine is tight, bring up only the services you need.
Local development only. None of this is meant for production or for exposure on a shared network. The sample credentials are public.
Docker access. The emulators mount /var/run/docker.sock to support services such as serverless functions, which gives them control over Docker on your machine. Remove that mount in environments where you don't need it.
Images tagged latest. Several services use that tag. If you need reproducibility, pin versions.
Apple Silicon. Some images only exist for x86_64 and run emulated; you'll see a platform warning, not an error.

What I Would Do Differently With More Time

Pin the versions of all images by default.
Add Compose profiles to bring up typical combinations (for example, "just PostgreSQL + MinIO").
Automate health checks to know when each service is ready.

Conclusion

A local environment declared as code speeds up onboarding and eliminates "it works on my machine".
Emulators and mocks let you test integrations without depending on third parties or exposing real credentials.
Use them for development, with clarity about their fidelity and security limits.

The repository is open source (MIT license). If you use it and a service is missing, contributions are welcome.

Skills de IA para analizar logs: cómo estructuré un diagnóstico reproducible

Ivan Firestone — Sun, 25 Oct 2026 12:00:06 +0000

Cómo diseñé un conjunto de skills y agentes para asistentes de IA que detectan la tecnología de un log, piden el contexto que falta y entregan un diagnóstico estandarizado. Diseño, instalación y límites.

Resumen

Analizar logs con un asistente de IA funciona mejor cuando el asistente sigue un procedimiento en lugar de improvisar. Reuní mis instrucciones en ia-tools: una colección de skills y agentes, en español, para Claude Code, Codex y otros entornos compatibles con el estándar abierto Agent Skills.

Este artículo explica cómo están diseñados, por qué los dividí así y qué límites tienen.

El problema

Pegar un stack trace en un chat y preguntar "¿qué está fallando?" da resultados dispares:

El asistente supone la tecnología y la versión sin preguntar.
Cada respuesta tiene un formato distinto, difícil de comparar o de pasar a un ticket.
Los datos sensibles (tokens, credenciales, datos personales) se cuelan sin que nadie los señale.
El diagnóstico ocurre sin conocer el entorno (producción o desarrollo, rol del servidor, versión).

Un buen diagnóstico siempre sigue los mismos pasos. Y si los pasos son siempre los mismos, se pueden escribir una sola vez.

Qué es una skill

Una skill es una carpeta con un archivo SKILL.md: instrucciones que el modelo carga automáticamente cuando la conversación coincide con su description, o que invocas a mano con /nombre. El material de referencia largo vive en references/ y se carga solo cuando hace falta.

Esa carga bajo demanda es la decisión de diseño más importante: no meter todo en el contexto. Una sola skill gigante con reglas para veinte tecnologías consumiría contexto y diluiría las instrucciones.

Cómo está organizado

Una skill principal y varias específicas por tecnología:

log-analyzer: detecta la tecnología del log a partir de sus patrones, pide el contexto que no puede inferir y produce un diagnóstico estandarizado.
Skills por familia técnica: nube (Azure, AWS, GCP), bases de datos (PostgreSQL, Oracle, SQL Server), Docker, .NET, Kafka, Kubernetes y OpenShift, Laravel, PHP, Spring Boot, Quarkus, servidores web, Windows Event Log, MinIO, IBM API Connect y alertas de SRE.

La principal decide qué referencia cargar. Así el asistente trae al contexto solo lo relevante para ese log.

El flujo del diagnóstico

Detectar la tecnología a partir de los patrones del propio log.
Preguntar lo que no puede inferir: entorno, versión, rol del servidor. Diagnosticar sin ese contexto lleva a conclusiones seguras de sí mismas y equivocadas.
Analizar con las referencias específicas de esa tecnología.
Entregar un reporte con estructura fija, para que sea comparable entre incidentes y fácil de adjuntar a un ticket.

Una decisión deliberada: señalar, no ocultar

Las skills no censuran las credenciales, los tokens ni los datos personales que aparecen en el log. Los señalan en rojo en el reporte.

La razón es práctica: si el log contiene un secreto, lo que necesitas es rotarlo, y para eso tienes que saber que está ahí. Ocultarlo en silencio te deja con una falsa sensación de seguridad. El costo es que el reporte puede contener datos sensibles, así que debes revisarlo antes de compartirlo.

Una regla complementaria: no pegues logs de producción en herramientas externas sin la autorización de tu organización.

Agentes: otra pieza distinta

Además de las skills, el repositorio incluye cuatro agentes para Claude Code (roles independientes con instrucciones propias):

Redacción de comunicaciones corporativas.
Conversión de notas o transcripciones en minutas de reunión.
Extracción de decisiones, tareas y riesgos accionables.
Traducción, corrección y ajuste de tono.

Son plantillas genéricas escritas para equipos hispanohablantes; la idea es que las adaptes a tu organización.

Instalación

En Claude Code, como plugin:

/plugin install ia-tools --marketplace ifirestone/ia-tools

Para Codex y otros entornos compatibles, el repositorio incluye un script que enlaza cada skill en tu directorio de skills:

./scripts/link-skills.sh

Como son enlaces simbólicos al repositorio, un git pull mantiene todo al día. Ten en cuenta que el script reemplaza las carpetas existentes con el mismo nombre de skill, así que revísalo antes si ya tienes skills propias.

ChatGPT no tiene un mecanismo nativo para cargar skills: puedes pegar el contenido de un SKILL.md como instrucciones de un Project o de un GPT personalizado y subir las referencias como archivos de conocimiento.

Límites que conviene tener claros

Un diagnóstico es una hipótesis, no un veredicto. El asistente puede equivocarse, sobre todo con logs parciales o sin contexto. Verifica antes de actuar.
La calidad depende del log que le des. Un fragmento sin la línea del error raíz produce conclusiones débiles.
Mantenimiento. Las tecnologías cambian de versión y de mensajes de error; las referencias hay que mantenerlas al día.
Sensibilidad de los datos. Señalar no es proteger. La responsabilidad de no exponer información sigue siendo tuya.

Lo que aprendí al diseñarlo

Un procedimiento fijo vale más que un prompt ingenioso. La consistencia es lo que vuelve útil el diagnóstico.
Preguntar antes de diagnosticar evita la mayoría de las respuestas falsamente seguras.
Dividir por tecnología mantiene el contexto pequeño y las instrucciones precisas.
Escribir en el idioma del equipo reduce la fricción cuando el reporte lo lee gente de operaciones o de soporte.

Conclusión

Las skills convierten una buena práctica de diagnóstico en algo repetible y compartible. No reemplazan el criterio del ingeniero; ahorran el trabajo mecánico del primer análisis.

El repositorio es de código abierto (MIT). Si agregas una skill para otra tecnología, la guía de contribución explica la estructura.

Ocho claves de CA, una de ellas el número 4: lo que enseña el incidente de eMudhra sobre los trust stores

Ivan Firestone — Sun, 25 Oct 2026 02:57:57 +0000

La clave privada de una autoridad certificadora debería ser un número tan grande que adivinarlo llevaría más tiempo que la vida del sol. El 17 de octubre de 2026, un investigador demostró que una de las de eMudhra era el número 4.

No un 4 seguido de unos cientos de dígitos. Solo un 4.

Este artículo trata de lo que eso significa para el código que ejecutas, no para la pestaña del navegador en la que lees esto. Dejo fuera la discusión sobre si eMudhra merece un lugar en los programas de certificados raíz, porque eso les corresponde a quienes gestionan esos programas. Lo que quiero cubrir es la distancia entre "Chrome lo bloqueó" y "mi servicio lo bloquea", porque en esa distancia vivimos casi todos.

Ocho claves que se cuentan con los dedos

Las claves afectadas pertenecían a ocho certificados intermedios, generados en una ceremonia de claves (key ceremony, el acto formal en que se genera y custodia la clave de una CA) en abril de 2025. Seis eran para TLS y dos para firma de código. Las claves privadas resultaron ser enteros pequeños: 4, 56, 66, 115, 155, 156, 230 y 237, según The Register (en inglés). Cualquiera podía recuperarlas a partir de los certificados públicos en menos de un segundo.

Un repaso rápido de por qué importa. Una CA intermedia es la que firma los certificados que tus servidores presentan en la práctica. Quien tenga su clave privada puede emitir un certificado para cualquier dominio, y todo cliente que confíe en esa cadena lo aceptará. Piensa en un sello de lacre cuyo dibujo cualquiera puede redibujar a partir de una foto del sello.

Aquí no se robó nada. iTnews (en inglés) lo dijo bien: no hizo falta robar nada para crear el fallo. eMudhra afirma que un error en su ceremonia de generación de claves hizo que un paso de wrap/unwrap produjera un segundo juego de claves débiles junto a las fuertes que pretendía, y que las débiles fueron las que se enviaron a los programas de certificados raíz de los navegadores. También dice que las CA afectadas no emitieron certificados de entidad final, que las revocó en 14 horas desde que descubrió el problema y que su infraestructura y sus datos no se vieron comprometidos. No puedo verificar esas afirmaciones por mi cuenta. Lo público son los certificados, y si alguien usó las claves en los aproximadamente 18 meses previos al reporte es, hasta donde sé, algo que se desconoce.

Así que esto no fue un hackeo. Fue un mal número a la vista de todos durante año y medio. Lo que lleva a la siguiente pregunta: quién se enteró y con qué rapidez reaccionó el mundo.

Cinco días, cuatro fabricantes

El reporte llegó a los programas de certificados raíz de los navegadores el 17 de octubre. Chrome bloqueó los certificados ese mismo día mediante su mecanismo CRLSet, y Firefox hizo lo mismo con OneCRL. Microsoft siguió el 20 de octubre. iTnews afirma que los dispositivos Apple estaban protegidos desde el 19 de octubre, mientras que el aviso que cito más abajo indica el 22. No pude conciliar ambas fechas.

El reloj de Cloudflare empezó más tarde. Su post del incidente (en inglés) dice que se enteró hacia las 17:00 UTC del 19 de octubre. A partir de ahí el trabajo siguió un orden claro:

Primero, los servicios que usan certificados públicos para autenticar endpoints remotos: proxies que se conectan a orígenes y aplicaciones que llaman a APIs externas.
Después, los trust stores compartidos y las imágenes base, para que todo lo que hereda confianza de ellos recibiera la corrección, seguido de los reinicios y despliegues de imágenes necesarios para activarla.
Las aplicaciones con trust stores propios o personalizados se evaluaron aparte.

La cronología publicada: actualizaciones del cliente WARP a las 02:00 UTC del 20 de octubre, la actualización de cloudflared a las 09:15, y las mitigaciones de CDN y de Zero Trust del lado del servidor desplegadas por completo a las 19:20. Cloudflare reportó que no hubo explotación activa en sus servicios. También subrayó que es un problema de autenticación de certificados, no una debilidad en los algoritmos de cifrado TLS.

Luego vino la frase que más importa para el resto de nosotros: algunos clientes tienen que actuar sobre software o configuraciones de confianza que operan ellos mismos, sobre todo en los servidores de origen. ¿Por qué un borde ya parcheado dejaría algo por hacer?

El navegador tiene un interruptor. Tu servicio no.

Los fabricantes de navegadores lo resolvieron "con solo accionar un interruptor", como lo expresó Cloudflare (leyendo entre lineas), porque los navegadores tienen canales de revocación rápidos como los CRLSets, que empujan un bloqueo a todos los usuarios sin ciclo de actualización. Además, tienen una aplicación que arreglar, no cientos.

Todo lo demás (tu cliente HTTP, tu runtime, tu imagen de contenedor, el bundle de CA que trae una herramienta) tiene su propia idea de en quién confiar. iTnews lo probó en macOS: curl siguió aceptando certificados de la cadena comprometida después del bloqueo de Apple, porque curl comprueba contra su propio archivo en /etc/ssl/cert.pem sin consultar información de revocación. El aviso de Jackson dice que ese mismo archivo alimenta a git, python3, perl, ruby y openssl, los que vienen incluidos en macOS. Dennis Jackson, de Mozilla, quien publica el aviso enlazado más abajo, sugirió quitar dos raíces de ese archivo como solución provisional: la emSign ECC Root CA - G3 de eMudhra y la raíz AAA Certificate Services. Sectigo había hecho la firma cruzada de algunos de los intermedios débiles. Mozilla está retirando ahora la confianza en la raíz emSign por completo, y Chrome se ha comprometido a un camino similar.

Una advertencia sobre esa solución provisional, y esta parte es mi criterio, no el de Jackson. Quitar una raíz muy usada de un bundle compartido no sale gratis. Pruébalo contra los servicios que llamas antes de desplegarlo. El propio aviso trata estos pasos como provisionales y los da por plataforma: macOS, Linux, Windows, Android y los BSD. Califica el enfoque de Linux, dejar de confiar en las raíces mediante la lista de bloqueo de la distribución, como solo para expertos, y advierte que desactivar la raíz AAA Certificate Services en Android puede romper sitios que aún encadenan a ella.

Hay otra razón por la que los navegadores lo tuvieron más fácil, y está en el mismo aviso. Ninguno de los intermedios débiles tiene una entrada correspondiente en los logs de Certificate Transparency (CT), así que los navegadores que exigen CT no podrían haber sido atacados con certificados de estas claves. Los clientes que no exigen CT, entre ellos muchos clientes HTTP de backend, no tuvieron ese colchón. El 22 de octubre Jackson añadió a su verificador dos hosts de prueba "No CT", para ver si un cliente acepta certificados que nunca se registraron.

Imagina un job de backend que llama a la API de un socio desde una imagen de contenedor construida hace seis meses. Abres el sitio del socio en tu navegador, ves el candado y concluyes que todo está bien. El contenedor nunca se enteró del 17 de octubre. Esa es la distancia.

Qué revisar el lunes

Empieza por averiguar quién verifica certificados en tu stack. El consejo de Cloudflare para desarrolladores es mirar por debajo del SDK: un cliente de API puede delegar la verificación en una librería HTTP, en el runtime del lenguaje, en el sistema operativo o en una configuración de confianza propia, así que actualizar solo el SDK puede no cambiar nada.

Luego ve lugar por lugar:

Imágenes base de contenedores. Reconstruye desde una base nueva y vuelve a desplegar. Una imagen nueva en disco no hace nada por un contenedor que sigue ejecutando la anterior.
Trust stores del sistema. En imágenes basadas en Debian puedes al menos ver si las raíces emSign siguen instaladas. Tómalo como punto de partida, no como veredicto, porque la corrección puede estar en un store o verificador actualizado y no en la ausencia de la raíz.
Archivos de CA propios de cada herramienta. Herramientas como curl que traen su propio bundle necesitan su propia actualización.
Configuración de mTLS. Revisa en qué CA confías para verificar certificados de cliente. Confía en las que de verdad usas para emitir, no en un bundle público completo, si tus integraciones lo permiten. Te cuesta flexibilidad cuando un socio cambia de CA.
Certificados de origen. Si usas los modos Full (strict) o Strict de Cloudflare, revisa tus certificados de origen personalizados. Cloudflare dice que Automatic SSL/TLS te avisará si sigues usando los que ya no son de confianza.

# Imagen basada en Debian/Ubuntu: ¿siguen instaladas las raíces emSign? ls /etc/ssl/certs | grep -i emsign Reconstruye desde una imagen base nueva y vuelve a desplegar

docker build --pull --no-cache -t myapp:fixed .

Cuando apliques el parche, puede que empieces a ver errores de certificado en tus paneles. La advertencia de Cloudflare aquí es directa y la comparto: no los resuelvas desactivando la verificación.

# Tentador a las 2 a. m. cuando una llamada empieza a fallar. No lo hagas.


requests.get(url, verify=False)

Esa línea elimina justo la autenticación que la actualización debía restaurar. Averigua qué cadena presenta en realidad la llamada que falla y corrige el trust store.

Por último, prueba por el camino que tu aplicación usa de verdad. El sitio de pruebas de Jackson cubre navegadores y clientes que no son navegadores. Lee con cuidado un fallo, porque la página advierte que un error de red se ve igual que un rechazo de certificado. El aviso que hay detrás también sigue las versiones corregidas en distribuciones de Linux, bundles de CA como certifi, runtimes de lenguajes (entre ellos Node.js, Python y Go) y herramientas como Docker. Algunas son dependencias indirectas, así que revisa tu árbol de dependencias. Trátala como tu tabla de consulta, y trata sus entradas pendientes como abiertas: cuando la leí el 24 de octubre, algunas seguían marcadas como pendientes, por ejemplo RHEL 7 y Bottlerocket. Cloudflare es explícito en que una prueba exitosa en el navegador no demuestra que un servicio en segundo plano esté a salvo, y una prueba con curl tampoco, si la aplicación usa otro verificador.

Si usas Tunnel y WARP como describí en Exponer entornos de desarrollo con Cloudflare Tunnel y WARP sin abrir puertos, actualiza cloudflared a 2026.10.2 y aplica las actualizaciones correspondientes del cliente WARP. El post de Cloudflare lista las versiones corregidas por plataforma.

Lo que costó y lo que deja

El 22 de octubre, eMudhra anunció que sale del negocio global de certificados SSL/TLS. Su comunicado, citado por The Register, dice que ese negocio es cerca del 1 por ciento de sus ingresos globales y que el escrutinio fue desproporcionado respecto a su peso en la empresa. Estima que unos 30.000 certificados necesitan migrarse y dice que los servicios de revocación y de estado seguirán funcionando hasta que todos los certificados emitidos hayan expirado o se hayan reemplazado.

También dice que la infraestructura afectada pasó dos años de auditorías independientes y estaba en las listas de confianza de los navegadores desde mediados de 2025. Si eso es exacto, es la parte incómoda. Las auditorías no detectaron una clave privada que era el número 4.

No creo que la lección sea que una autoridad fue descuidada. La lección es que la mayor parte de nuestro software trata un trust store como una lista estática de raíces, cuando el modelo de amenazas exige que se comporte como un feed de revocación. Cloudflare señala proyectos como upki, de Canonical, que tratan el trust store como algo que debe actualizarse rápido con información de revocación y de certificate transparency. Es una dirección, no algo que puedas instalar el lunes.

Lo que sí puedes hacer el lunes es abrir el archivo. En algún punto de tu stack hay una lista de en quién confías, y nadie la ha mirado desde el día en que se construyó la imagen. El número 4 estuvo a la vista de todos unos 18 meses. La lista probablemente es más vieja.

La misma semana tuvo un fallo muy distinto en el otro extremo de la escala: un parche que se saltó versiones que la gente seguía ejecutando. Escribí sobre su costo en Cuando el parche se salta tu versión: lo que costó PHP2Shell a los gobiernos y lo que añade el EOL.

Fuentes

8 eMudhra certificates are compromised. Here's what you need to know (Cloudflare Blog, en inglés)
Disgraced Indian cert issuer leaves the cert issuing business (The Register, en inglés)
Cloudflare warns fixing botched eMudhra certs goes beyond browsers (iTnews, en inglés)
Advisory and checker for the compromised eMudhra intermediate CAs (Dennis Jackson, we-have-a-problem.com, en inglés)

AI Skills for Log Analysis: How I Structured a Reproducible Diagnosis

Ivan Firestone — Sat, 24 Oct 2026 13:00:07 +0000

Analyzing logs with an AI assistant works better when the assistant follows a procedure rather than improvising. I gathered my instructions in ia-tools: a collection of skills and agents, in Spanish, for Claude Code, Codex and other harnesses compatible with the open Agent Skills standard.

This article explains how they're designed, why I split them this way and what limits they have.

The Problem

Pasting a stack trace into a chat and asking "what's failing?" gives uneven results:

The assistant assumes technology and version without asking.
Each answer has a different format, hard to compare or move into a ticket.
Sensitive data (tokens, credentials, personal data) slips through without anyone flagging it.
Diagnosis happens without knowing the environment (production or development, server role, version).

A useful diagnosis always follows the same steps. If the steps are always the same, they can be written once.

What a Skill Is

A skill is a folder with a SKILL.md file: instructions the model loads automatically when the conversation matches its description, or that you invoke manually with /name. Long reference material lives in references/ and is loaded only when needed.

That on-demand loading is the most important design decision: don't put everything in the context. A single giant skill with rules for twenty technologies would consume context and dilute the instructions.

How It's Organized

One main skill and several technology-specific ones:

log-analyzer: detects the log's technology from its patterns, requests the context it can't infer and produces a standardized diagnosis.
Skills by technical family: cloud (Azure, AWS, GCP), databases (PostgreSQL, Oracle, SQL Server), Docker, .NET, Kafka, Kubernetes and OpenShift, Laravel, PHP, Spring Boot, Quarkus, web servers, Windows Event Log, MinIO, IBM API Connect and SRE alerts.

The main one decides which reference to load. That way the assistant brings into context only what's relevant for that log.

The Diagnosis Flow

Detect the technology from the log's own patterns.
Ask for what it can't infer: environment, version, server role. Diagnosing without that context leads to confident and wrong conclusions.
Analyze using the references specific to that technology.
Deliver a report with a fixed structure, so it's comparable across incidents and easy to attach to a ticket.

A Deliberate Decision: Flag, Don't Hide

The skills do not censor credentials, tokens or personal data that appear in the log. They flag them in red in the report.

The reason is practical: if the log contains a secret, what you need is to rotate it, and for that you have to know it's there. Silently hiding it leaves you with a false sense of security. The cost is that the report may contain sensitive data, so you must review it before sharing.

A complementary rule: don't paste production logs into external tools without your organization's authorization.

Agents: A Different Piece

In addition to the skills, the repository includes four agents for Claude Code (independent roles with their own instructions):

Drafting corporate communications.
Turning notes or transcripts into meeting minutes.
Extracting actionable decisions, tasks and risks.
Translation, proofreading and tone adjustment.

They are generic templates written for Spanish-speaking teams; the idea is that you adapt them to your organization.

Installation

In Claude Code, as a plugin:

/plugin install ia-tools --marketplace ifirestone/ia-tools

For Codex and other compatible harnesses, the repository includes a script that links each skill into your skills directory:

./scripts/link-skills.sh

Since they are symbolic links to the repository, a git pull keeps everything up to date. Keep in mind that the script replaces existing folders with the same skill name, so review it first if you have skills of your own.

ChatGPT has no native mechanism for loading skills: you can paste the content of a SKILL.md as the instructions of a Project or custom GPT and upload the references as knowledge files.

Limits to Keep Clear

A diagnosis is a hypothesis, not a verdict. The assistant can be wrong, especially with partial logs or without context. Verify before acting.
Quality depends on the log you give it. A fragment without the root error line produces weak conclusions.
Maintenance. Technologies change versions and error messages; the references must be kept up to date.
Data sensitivity. Flagging is not protecting. The responsibility of not exposing information is still yours.

What I Learned Designing It

A fixed procedure is worth more than a clever prompt. Consistency is what makes the diagnosis useful.
Asking before diagnosing prevents most falsely confident answers.
Splitting by technology keeps the context small and the instructions precise.
Writing in the team's language reduces friction when the report is read by operations or support people.

Conclusion

Skills turn a good diagnostic practice into something repeatable and shareable. They don't replace the engineer's judgment; they save the mechanical work of the first analysis.

The repository is open source (MIT). If you add a skill for another technology, the contribution guide explains the structure.

Laravel con Docker Compose: cinco errores de infraestructura que vale la pena evitar

Ivan Firestone — Sat, 24 Oct 2026 12:00:06 +0000

Nombres de servicio, healthchecks de Postgres, un scheduler sin tabla de caché, colas y migraciones al desplegar: los errores que aparecen al llevar Laravel a Docker Compose y cómo evitarlos.

Resumen

Llevar una aplicación Laravel a Docker Compose parece trivial hasta que el primer despliegue falla por razones que no están en tu código. Estos son cinco errores de infraestructura que encontré depurando proyectos reales, con el síntoma, la causa y la solución.

1. El nombre del servicio no coincide con `DB_HOST`

Síntoma: la aplicación no puede conectarse a la base de datos: getaddrinfo failed, Connection refused o Name or service not known.

Causa: en una red de Compose, los contenedores se resuelven por el nombre del servicio. Si tu servicio se llama postgres en docker-compose.yml pero el .env dice DB_HOST=db, no hay nada que resolver. Pasa mucho al renombrar servicios o al copiar un .env de otro proyecto.

Solución: que el valor de DB_HOST sea exactamente el nombre del servicio.

services:

  postgres:

    image: postgres:16

  app:

    environment:

      DB_HOST: postgres # el nombre del servicio, no "localhost"

Un clásico relacionado: usar localhost dentro del contenedor. Dentro de un contenedor, localhost es ese mismo contenedor.

2. Healthcheck de Postgres con credenciales distintas a las reales

Síntoma: el contenedor de la base de datos queda unhealthy y los servicios que dependen de él nunca arrancan. En los logs de Postgres: FATAL: role "postgres" does not exist.

Causa: el healthcheck usa un usuario o una base de datos distintos de los configurados en las variables de entorno. Si defines POSTGRES_USER=laravel y tu healthcheck ejecuta pg_isready -U postgres, estás comprobando contra un rol que no existe.

Solución: que el healthcheck use las mismas variables, y escapar el $ para que lo resuelva el contenedor y no Compose:

services:

  postgres:

    image: postgres:16

    environment:

      POSTGRES_USER: ${DB_USERNAME}

      POSTGRES_PASSWORD: ${DB_PASSWORD}

      POSTGRES_DB: ${DB_DATABASE}

    healthcheck:

      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]

      interval: 5s

      timeout: 3s

      retries: 10

app:


    depends_on:


      postgres:


        condition: service_healthy

Con depends_on y service_healthy, la app espera hasta que la base de datos realmente acepta conexiones, no solo hasta que el contenedor existe.

3. El scheduler falla porque la tabla de caché no existe

Síntoma: el scheduler lanza errores relacionados con la tabla cache o cache_locks, sobre todo cuando usas tareas con withoutOverlapping() o onOneServer().

Causa: con CACHE_STORE=database, Laravel guarda la caché y los locks en tablas. Si esas tablas no existen (la migración no se ejecutó o la base de datos es nueva), el scheduler falla al intentar adquirir un lock.

Solución: asegúrate de que la tabla de caché esté migrada. En Laravel 11 o superior:

php artisan make:cache-table


php artisan migrate

(En versiones anteriores el comando era cache:table.) Y ejecuta el scheduler como un proceso propio:

php artisan schedule:work

4. Todos los procesos en un solo contenedor

Síntoma: en desarrollo todo funciona, y en producción las colas se detienen en silencio, los reinicios son impredecibles y no puedes escalar solo los workers.

Causa: en desarrollo es normal usar concurrently para levantar el servidor web, la cola y el scheduler en una sola terminal. Llevar ese patrón a producción mete varios procesos en un contenedor, y Docker solo vigila el proceso principal: si la cola muere, nadie se entera.

Solución: un proceso por contenedor, con la misma imagen y un comando distinto:

services: app: image: myapp:latest command: php-fpm queue: image: myapp:latest command: php artisan queue:work --tries=3 --timeout=90 restart: unless-stopped

scheduler: image: myapp:latest command: php artisan schedule:work restart: unless-stopped

Ventajas: reinicios independientes, escalado de workers por separado, logs separados y señales de parada manejadas por Docker.

5. Las migraciones se ejecutan en cada arranque del contenedor

Síntoma: al desplegar con varias réplicas aparecen errores intermitentes de migración, bloqueos en la base de datos o tablas creadas a medias.

Causa: poner php artisan migrate --force en el entrypoint hace que cada contenedor intente migrar al iniciar. Con varias réplicas, compiten entre sí.

Solución: las migraciones son un paso del despliegue, no del arranque de la aplicación. Ejecútalas una sola vez, como tarea previa en el pipeline de CI/CD o como un servicio de una sola ejecución:

services:


  migrate:


    image: myapp:latest


    command: php artisan migrate --force


    restart: "no"


    depends_on:


      postgres:


        condition: service_healthy

Y haz que app, queue y scheduler arranquen después de que la migración termine con éxito.

Lista de verificación rápida

[ ] DB_HOST coincide con el nombre del servicio, nunca localhost.
[ ] El healthcheck de la base de datos usa las mismas credenciales que el servicio.
[ ] depends_on usa condition: service_healthy.
[ ] La tabla de caché existe si usas CACHE_STORE=database.
[ ] Un proceso por contenedor: web, cola y scheduler separados.
[ ] Las migraciones se ejecutan una vez por despliegue, no en cada arranque.
[ ] Las imágenes tienen una versión fija, no latest.

Conclusión

Casi todos estos errores tienen el mismo origen: asumir que la infraestructura se comporta como tu máquina local. Compose tiene reglas claras (resolución por nombre, orden de arranque, un proceso por contenedor). Conocerlas ahorra horas de depuración.

Si tienes un error recurrente en tu propio despliegue, compártelo en los comentarios: seguro alguien más se lo ha encontrado también.

Exponer entornos de desarrollo con Cloudflare Tunnel y WARP sin abrir puertos

Ivan Firestone — Fri, 23 Oct 2026 17:18:17 +0000

Necesitaba un entorno de desarrollo con despliegues frecuentes, URLs públicas con HTTPS y acceso cómodo a las bases de datos para depurar. Lo que no quería era un servidor en Internet con los puertos 80 y 443 abiertos, esperando a que alguien lo escanee.

Esos requisitos tiran en direcciones opuestas: mientras más fácil el acceso, mayor la exposición. Esta es la historia de la combinación que me funcionó:

Cloudflare Tunnel para publicar las apps sin abrir los puertos 80 y 443.
Traefik como enrutador interno, con labels por aplicación.
Portainer para administrar los contenedores.
Cloudflare One WARP para llegar a la red privada de Docker solo desde mi máquina.

Voy a explicar el diseño, el detalle que rompe Laravel detrás del proxy y, sobre todo, los riesgos.

La idea: que el servidor llame hacia afuera

La forma habitual de publicar una app es abrir un puerto y dejar que el mundo se conecte. El túnel invierte eso:

Internet → Cloudflare (TLS) → túnel (conexión saliente) → Traefik → contenedores

La clave: el conector cloudflared abre la conexión hacia Cloudflare, y no al revés. El servidor no necesita puertos de entrada abiertos. Cloudflare termina el TLS, y dentro del servidor el tráfico va por HTTP hacia Traefik.

Eso resuelve la exposición y los certificados de un solo golpe. Pero un túnel solo lleva el tráfico hasta la puerta; algo tiene que decidir qué contenedor responde.

Elegir el enrutador

Despliego con mucha frecuencia. Con Traefik, cada aplicación declara su enrutamiento con labels en su propio docker-compose, y no hay configuración central que tocar por cada proyecto nuevo.

Antes evalué Dokploy para desarrollo. Es cómodo, pero me pareció pesado en recursos para un servidor pequeño. El camino que elegí (Portainer + Traefik + cloudflared) es más liviano, al precio de escribir a mano los labels de Traefik. Es un intercambio entre comodidad y consumo.

Armar las piezas

La base es una red compartida, Traefik sin HTTPS (de eso se encarga Cloudflare) y cloudflared con el token del túnel:

services: traefik: image: traefik:v3 command: - --providers.docker=true - --providers.docker.exposedbydefault=false - --entrypoints.web.address=:80 volumes: - /var/run/docker.sock:/var/run/docker.sock:ro networks: [edge] cloudflared: image: cloudflare/cloudflared:latest command: tunnel --no-autoupdate run environment: - TUNNEL_TOKEN=${TUNNEL_TOKEN} networks: [edge]

networks: edge: name: edge

Fíjate en que ningún servicio publica puertos (ports:). Es intencional y es la mejor defensa: si no se publica ningún puerto, no hay nada que puedas exponer por accidente.

En el panel de Cloudflare configuras el public hostname (por ejemplo, un comodín bajo tu dominio) apuntando al servicio http://traefik:80.

A partir de ahí, cada app nueva solo se une a la misma red y declara su enrutamiento:

services: myapp: image: myapp:dev networks: [edge] labels: - traefik.enable=true - traefik.http.routers.myapp.rule=Host(myapp.dev.example.com) - traefik.http.routers.myapp.entrypoints=web - traefik.http.services.myapp.loadbalancer.server.port=80

networks: edge: external: true

Con eso, una app queda en vivo por HTTPS. Pero si es una app Laravel, hay un detalle.

El detalle que rompe Laravel

Como el TLS termina en Cloudflare y Traefik habla HTTP con la app, Laravel ve peticiones HTTP. Los síntomas típicos: URLs generadas con http://, redirecciones rotas y mixed content (contenido mixto).

Se arregla confiando en los headers X-Forwarded- del proxy y forzando HTTPS. En Laravel 11 o superior, en bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {


    $middleware->trustProxies(at: '');


})

Y en el service provider, forzar el esquema:

URL::forceScheme('https');

Funciona. Pero mira bien ese '', porque trae un riesgo.

La advertencia importante

trustProxies(at: '') significa "confío en los headers de cualquiera". Solo es seguro si el origen es inalcanzable salvo a través del túnel. Si alguien puede llegar directo al contenedor, puede falsificar X-Forwarded-For o X-Forwarded-Proto.

Por eso conviene combinar tres cosas:

No publicar los puertos de las apps.
Cerrar 80/443 en el firewall.
Limitar en Traefik qué IPs son de confianza para los headers reenviados (forwardedHeaders.trustedIPs en el entrypoint), usando la red interna del túnel.

Lo que lleva a la pregunta de la que depende todo el diseño: ¿está realmente cerrado el origen?

Cerrar los puertos de verdad

Hay capas, de la más a la menos confiable:

No publiques puertos en Docker. Sin ports:, no hay nada que filtrar.
Firewall del proveedor de nube (reglas de seguridad de red): permite solo lo estrictamente necesario, por ejemplo SSH desde tu IP.
Reglas en el host como defensa adicional. Ojo: Docker manipula iptables por su cuenta y puede saltarse reglas pensadas para firewalls de nivel superior; para filtrar el tráfico hacia contenedores publicados, la cadena DOCKER-USER es el lugar previsto.

Verifica siempre desde afuera con un escaneo de puertos, no solo leyendo la configuración.

La última pieza: llegar a las bases de datos

Las apps eran públicas y los puertos estaban cerrados. Pero para depurar yo seguía queriendo conectarme a las bases de datos del entorno, sin exponerlas a nadie.

Ahí entra Cloudflare One WARP. Con una ruta de red privada a través del mismo túnel, mi máquina llega a la red de Docker como si estuviera dentro. Esto permite:

Darles a las bases de datos una IP fija en la red interna y conectarme con mi cliente de siempre.
Que solo los dispositivos autorizados en la política de Zero Trust puedan acceder.
No abrir ningún puerto de base de datos hacia afuera.

Producción es otra decisión

¿Se traslada la misma configuración a producción? No del todo. En producción uso Portainer sin Traefik: el túnel apunta directamente al contenedor de cada aplicación. Menos piezas, menos superficie y menos cosas que pueden fallar. Traefik me resuelve un problema de velocidad de despliegue en desarrollo; en producción, donde los cambios son menos frecuentes, ese problema no existe.

Lo que cedes

Nada de esto es gratis:

Dependencia de Cloudflare. Si el servicio tiene una caída, tus entornos quedan inalcanzables. Para desarrollo es tolerable; para producción hay que evaluarlo.
El token del túnel es un secreto. Quien lo tenga puede ejecutar un conector. Guárdalo como secreto, no en el repositorio.
El socket de Docker. Traefik lo monta en solo lectura, pero sigue siendo un acceso sensible. Hay alternativas con un proxy de socket que limita las operaciones permitidas.
Labels escritos a mano. Es más trabajo por proyecto que un panel integrado.
Mantenimiento de WARP. Hay que gestionar el enrolamiento de dispositivos y las políticas de acceso.
Versiones fijadas. Evita latest para cloudflared y Traefik si quieres despliegues reproducibles.

Lo que me llevo

El servidor que quería mantener oculto está oculto: nada escucha en Internet público, y aun así despliego con frecuencia con HTTPS y llego a las bases de datos desde mi propia máquina.

Si te quedas con pocas cosas:

Un túnel saliente elimina la necesidad de abrir puertos y simplifica el TLS.
No publicar puertos en Docker es la defensa más fuerte y más barata.
trustProxies(at: '*') solo es seguro si el origen es inalcanzable por cualquier otra ruta.
Traefik acelera el desarrollo; en producción, menos piezas suelen ser mejor.
Verifica la exposición desde afuera, no solo en la configuración.

DEV Community: Ivan Firestone

SaaS multi-tenant en Laravel: una base de datos, un global scope y las fugas que no detecta: 02 de 08

Tres formas de darle a cada empresa su propio espacio

La URL decide quién es el tenant

Un solo lugar que sabe cuál es la empresa actual

Un scope que falla cerrado

El job nocturno, otra vez

Empresas, usuarios y roles

Demuéstralo con un test que intenta filtrar

Dónde deja de funcionar el schema compartido

Conclusión

Building a Multi-Tenant SaaS in Laravel: The Series I Wish I Had Read First: 01 of 08

What This Series Is

What It Assumes

What You'll Find

How to Read It

Conclusion

Migrar de un sistema legacy a microservicios sin documentación ni control total

La reescritura que parecía un plan

¿Qué hace realmente el sistema viejo?

Cortar donde no puedes editar

Superar a un sistema con doce años de pruebas

Lo que esto te cuesta

Conclusión

Construir un SaaS multi-tenant en Laravel: la serie que me habría gustado leer primero: 01 de 08

Qué es esta serie

Qué asume

Qué encontrarás

Cómo leerla

Conclusión

Arquitectura de microservicios

¿Qué es realmente un microservicio?

¿Qué funcionalidades merecen su propio servicio?

1. La funcionalidad puede valerse por sí sola

2. Necesita escalar de forma distinta

3. Otros sistemas también la necesitan

4. Cambia a otro ritmo

5. Corresponde a un dominio de negocio claro

6. Tiene el tamaño adecuado

Lo que gana la tienda

Lo que paga la tienda

De vuelta a la tienda

Malos hábitos en el desarrollo web que debemos evitar

1. No pensar en el móvil desde el principio

2. Ser inconsistente

3. Escribir URLs fijas en el código

4. Omitir el atributo alt en las imágenes

5. Usar demasiados divs

De vuelta a aquella captura

A Local Development Toolbox with Docker Compose: Databases, Cloud Emulators and Mocks

The Problem

Repository Structure

dev-infra: Databases and Storage

floci: Cloud Emulators

wiremock: Third-Party API Mocks

demo: Sample Data

How to Use It

Local credentials (not versioned)

Each stack is independent

Why Mocks in Addition to Emulators

Trade-offs and Limits (What You Should Know)

What I Would Do Differently With More Time

Conclusion

Skills de IA para analizar logs: cómo estructuré un diagnóstico reproducible

Resumen

El problema

Qué es una skill

Cómo está organizado

El flujo del diagnóstico

Una decisión deliberada: señalar, no ocultar

Agentes: otra pieza distinta

Instalación

Límites que conviene tener claros

Lo que aprendí al diseñarlo

Conclusión

Ocho claves de CA, una de ellas el número 4: lo que enseña el incidente de eMudhra sobre los trust stores

Ocho claves que se cuentan con los dedos

Cinco días, cuatro fabricantes

El navegador tiene un interruptor. Tu servicio no.

Qué revisar el lunes

4. Omitir el atributo `alt` en las imágenes

5. Usar demasiados `div`s

`dev-infra`: Databases and Storage

`floci`: Cloud Emulators

`wiremock`: Third-Party API Mocks

`demo`: Sample Data

1. El nombre del servicio no coincide con `DB_HOST`