Deploy Troy: Cómo distribuir actualizaciones de tus plugins sin pasar por el directorio oficial de WordPress

Si desarrollas plugins de WordPress y los distribuyes fuera del directorio oficial, sabes lo complicado que puede ser gestionar las actualizaciones. Tus usuarios no reciben avisos automáticos, tienes que montar tu propio sistema de notificaciones, y al final acabas dependiendo de soluciones a medias o de terceros.

Deploy Troy es un proyecto de código abierto que propone resolver exactamente este problema: te permite montar tu propio repositorio de plugins y distribuir actualizaciones exactamente igual que si estuvieran en WordPress.org, pero desde tu servidor y bajo tu control total.

De dónde viene Troy y por qué existe

El creador de Troy es Sybre Waaijer, el mismo desarrollador detrás de The SEO Framework. Y la idea partió, porqué no decirlo, de que en 2017 le retiraron un plugin de WordPress.org sin previo aviso por una disputa de políticas. Para mantener su negocio funcionando, tuvo que montar su propio servidor de actualizaciones. Ese servidor lleva más de 7 años sirviendo a más de 20.000 sitios.

Troy nace de esa (mala) experiencia y de cabreos acumulados con el directorio oficial: plugins bloqueados sin explicación clara, conflictos de interés en las revisiones, un sistema de ranking opaco que favorece a los primeros en llegar, y una comunicación mejorable con los desarrolladores independientes. Que vale, que entiendo que es mucho trabajo, que les quiero con locura a algunos de ellos (no a todos) pero está claro que el sistema es muy mejorable, y la realidad es que del directorio de plugins dependen los pagos de la hipoteca de desarrolladores independientes, incluso la supervivencia de empresas completas.

Como él mismo dice, y en esencia estoy de acuerdo:

Entre tú y yo hay una plataforma que puede cortar esa conexión en cualquier momento, por cualquier razón, sin responsabilidad alguna. Esto no puede estar bien. Necesitamos una alternativa mejor.

Cómo funciona: los componentes del sistema

Troy se compone de varias piezas que trabajan juntas. Antes de entrar en el tutorial, es importante entender qué hace cada una:

Troy Server (para desarrolladores)

Es el corazón del sistema. Convierte cualquier instalación de WordPress en un repositorio de plugins. Desde ahí puedes:

• Subir plugins manualmente (archivos ZIP).
• Conectar repositorios de GitHub para publicar automáticamente cuando creas un release.
• Ver estadísticas anónimas de uso.
• Generar paquetes de instalación para distribuir a tus usuarios.
• Gestionar dependencias entre plugins.

Troy Client (para usuarios finales)

Es el plugin que tus usuarios instalan en sus sitios. Una vez activo, detecta automáticamente cualquier plugin que tenga una cabecera Troy: y gestiona sus actualizaciones. El usuario ve los avisos de actualización en su escritorio de WordPress exactamente igual que con los plugins del directorio oficial.

Además, Troy Client elimina los plugins habilitados para Troy de cualquier petición a WordPress.org, protegiendo la privacidad de tus usuarios.

Componentes adicionales

• Troy Client Daemon: un mu-plugin que garantiza que Troy Client esté siempre activo y bloquea comunicaciones a WordPress.org si no lo está.
• Troy Package: un instalador que puedes generar desde Troy Server para que tus usuarios instalen Troy Client junto con tus plugins de forma automática.
• Troy Embed: un fragmento de código que puedes incluir en tu plugin para que instale Troy Client silenciosamente.

Tutorial: Configurar Troy desde cero

Vamos paso a paso, y verás que al final de este tutorial tendrás tu propio servidor de actualizaciones funcionando y tu primer plugin distribuido a través de él.

Paso 1: Preparar el servidor para Troy Server

Requisitos técnicos

Troy Server tiene requisitos más exigentes que una instalación WordPress típica. Antes de empezar, asegúrate de que tu servidor cumple con todo:

Importante sobre PHP 8.4: A fecha de hoy, no todos los hostings compartidos ofrecen PHP 8.4. Si el tuyo no lo tiene, necesitarás un VPS o servidor dedicado. Sin embargo, proveedores como SiteGround te permiten seleccionar la versión de PHP en cualquier plan de alojamiento, incluso los compartidos más económicos.

Crear una instalación WordPress dedicada

Troy Server debe instalarse en un WordPress independiente. Las razones son:

• Evita conflictos con plugins de tu web principal
• Permite optimizar el servidor específicamente para servir actualizaciones
• Mantiene separada la gestión de plugins de tu contenido

La forma más limpia es crear un subdominio. Por ejemplo, si tu web es tudominio.com crea, por ejemplo, repo.tudominio.com para Troy Server.

Pasos para crear el subdominio:

1. En tu panel de hosting (Site Tools, cPanel, Plesk, etc.), crea un nuevo subdominio repo.tudominio.com
2. Si es necesario en tu alojamiento, apunta el subdominio a una carpeta nueva (por ejemplo, /public_html/repo).
3. Instala un certificado SSL para el subdominio (Let’s Encrypt funciona perfectamente).
4. Instala WordPress en esa carpeta como harías normalmente.

Configurar WordPress para Troy Server

Una vez tengas WordPress instalado en tu subdominio, hay algunas cosas que NO debes instalar:

• Plugins de caché: Speed Optimizer, WP Super Cache, W3 Total Cache, LiteSpeed Cache, WP Rocket, etc. rompen habitualmente las peticiones de respuesta de la API REST.
• Plugins multilingües: WPML, Polylang, TranslatePress, etc. interfieren con la generación de URLs.
• Plugins de seguridad agresivos: algunos bloquean peticiones de la API REST. Si usas uno, asegúrate de que no bloquea las rutas de Troy.

En el archivo wp-config.php, puedes añadir estas líneas para optimizar el rendimiento:

// Desactivar revisiones de entradas (no las necesitas en un servidor de repos)
define( 'WP_POST_REVISIONS', false );

// Aumentar el límite de memoria si es necesario
define( 'WP_MEMORY_LIMIT', '512M' );

También es recomendable asegurar que las actualizaciones no fallen desactivando el cron de WordPress y añadiendo un cron real en 2 sencillos pasos:

1. Desactiva WP Cron añadiendo lo siguiente al archivo wp-config.php de tu repositorio:
   define( 'DISABLE_WP_CRON', true );
2. Añade un cron real en el panel de tu hosting con la mayor frecuencia posible:
   curl -s https://repo.tudominio.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1

Instalar Troy Server

Ahora sí, vamos a instalar Troy Server:

1. Descarga el instalador desde repo.deploytroy.org
2. En tu WordPress del subdominio, ve a Plugins → Añadir nuevo → Subir plugin
3. Sube el archivo ZIP que acabas de descargar
4. Activa el plugin

Tras la activación, verás un nuevo menú en el escritorio de WordPress con las opciones de Troy Server. El instalador configurará automáticamente las tablas de base de datos necesarias.

Troy Server se actualiza automáticamente desde repo.deploytroy.org, así que no tienes que preocuparte por las actualizaciones.

Paso 2: Configurar las cabeceras Troy en tu plugin

Para que un plugin se actualice a través de Troy, solo necesitas añadir una cabecera especial en el archivo principal del plugin. Veamos los distintos escenarios.

Cabecera básica para un plugin nuevo

Este es el ejemplo más sencillo. Un plugin que se actualizará desde tu servidor Troy:

<?php
/**
 * Plugin Name: Mi Plugin Premium
 * Plugin URI: https://tudominio.com/mi-plugin-premium
 * Description: Un plugin de ejemplo que se actualiza vía Troy.
 * Version: 1.0.0
 * Requires at least: 6.0
 * Requires PHP: 7.4
 * Author: Tu Nombre
 * Author URI: https://tudominio.com
 * License: GPL v2 or later
 * Text Domain: mi-plugin-premium
 * Troy: repo.tudominio.com
 */

// El resto del código de tu plugin...

La cabecera Troy: es la clave. Indica el dominio de tu servidor Troy sin el protocolo (sin https://). Troy Client usará siempre HTTPS automáticamente.

Añadir Troy a un plugin existente

Si ya tienes un plugin funcionando y quieres pasarlo a Troy, el cambio es mínimo. Solo tienes que añadir la línea Troy: a la cabecera existente:

<?php
/**
 * Plugin Name: Mi Plugin Existente
 * Plugin URI: https://tudominio.com/mi-plugin
 * Description: Plugin que ya existía y ahora usa Troy.
 * Version: 2.5.3
 * Author: Tu Nombre
 * Troy: repo.tudominio.com
 */

No necesitas cambiar nada más en el código. La próxima vez que subas una actualización a tu Troy Server, los usuarios que tengan Troy Client instalado la recibirán automáticamente.

Plugin con dependencias (ejemplo con WooCommerce)

Imagina que desarrollas una pasarela de pago para WooCommerce. Tu plugin necesita que WooCommerce esté instalado y activo. Con Troy puedes declarar esta dependencia:

<?php
/**
 * Plugin Name: Pasarela de Pago Premium
 * Plugin URI: https://tudominio.com/pasarela-pago
 * Description: Pasarela de pago personalizada para WooCommerce.
 * Version: 1.0.0
 * Requires at least: 6.0
 * Requires PHP: 7.4
 * Author: Tu Nombre
 * Author URI: https://tudominio.com
 * WC requires at least: 8.0
 * WC tested up to: 9.4
 * Troy: repo.tudominio.com
 * Troy Dependencies: woocommerce-premium
 */

¿Cómo funciona Troy Dependencies?

La cabecera Troy Dependencies: acepta una lista de slugs de plugins separados por comas. Estos son los slugs de los plugins tal como están registrados en tu Troy Server, no los de WordPress.org.

Cuando un usuario intenta activar tu plugin:

1. Troy Client comprueba si las dependencias están instaladas y activas
2. Si no lo están, las descarga automáticamente desde tu Troy Server
3. Las instala y activa antes de activar tu plugin

Esto es especialmente útil cuando tienes un ecosistema de plugins relacionados. Por ejemplo:

<?php
/**
 * Plugin Name: Mi Framework Pro - Addon SEO
 * Description: Addon de SEO para Mi Framework Pro.
 * Version: 1.0.0
 * Troy: repo.tudominio.com
 * Troy Dependencies: mi-framework-pro, mi-framework-pro-core
 */

El usuario instala el addon, y automáticamente se instalan también el framework principal y el core si no los tenía.

Plugin oculto (sin comunicación externa)

Para plugins internos que no quieres que comuniquen con ningún servidor externo (ni WordPress.org ni ningún Troy Server), usa esta cabecera especial:

<?php
/**
 * Plugin Name: Plugin Interno Empresa
 * Description: Funcionalidades internas. No distribuir.
 * Version: 3.2.1
 * Author: Departamento IT
 * Troy: disable-all-communications
 */

Con Troy: disable-all-communications, el plugin queda completamente aislado. No aparecerá en ninguna comprobación de actualizaciones ni enviará datos a ningún sitio.

Paso 3: Subir plugins a Troy Server

Ya tienes tu servidor configurado y tu plugin con la cabecera Troy. Ahora toca subirlo al repositorio.

Subida manual (archivo ZIP)

Esta es la forma más directa, ideal para empezar o para plugins que actualizas con poca frecuencia:

1. Empaqueta tu plugin en un archivo ZIP. La estructura debe ser:

   mi-plugin-premium.zip
   └── mi-plugin-premium/
       ├── mi-plugin-premium.php
       ├── includes/
       ├── assets/
       └── ...

2. En el escritorio de tu Troy Server, ve a la sección de gestión de plugins llamada Repo Plugins
3. Haz clic en Añadir nuevo plugin (¡en la interfaz de Troy Server, no en el instalador de WordPress!)
4. Sube el archivo ZIP o introduce la URL directa al ZIP si lo tienes alojado en algún sitio
5. Troy Server extraerá automáticamente:
   • Nombre del plugin
   • Versión
   • Descripción
   • Requisitos de PHP y WordPress
   • Dependencias Troy
6. Revisa que todo esté correcto y guarda

Para actualizar el plugin, simplemente repite el proceso con el nuevo ZIP. Troy Server detectará que es una versión nueva del mismo plugin (por el slug) y la añadirá como actualización disponible.

Integración con GitHub (automatizado)

Si desarrollas con GitHub, esta es la opción más cómoda. Cada vez que crees un release, Troy Server lo detectará y publicará automáticamente.

Configuración inicial:

1. En tu Troy Server, ve a la sección de integración con GitHub
2. Conecta tu cuenta de GitHub (necesitarás autorizar a Troy Server para acceder a tus repositorios)
3. Selecciona el repositorio de tu plugin
4. Configura las opciones:
   • Rama a monitorizar: normalmente main o master
   • Patrón de tags: por ejemplo, v* para tags que empiecen por «v» (v1.0.0, v1.2.3, etc.)
   • Procesamiento: automático (se publica cada tag nuevo) o manual (tú decides cuándo)

Flujo de trabajo con GitHub:

1. Desarrollas y haces commits normalmente
2. Cuando tienes una versión lista, creas un tag:

   git tag v1.2.0
   git push origin v1.2.0

3. Creas un release en GitHub asociado a ese tag
4. Troy Server detecta el nuevo release, descarga el ZIP y lo publica
5. Tus usuarios reciben la actualización automáticamente

Si elegiste procesamiento manual, en lugar del paso 4 verás el release pendiente en tu Troy Server y podrás publicarlo cuando quieras.

Paso 4: Distribuir Troy Client a tus usuarios

Tus usuarios necesitan tener Troy Client instalado para recibir las actualizaciones de tus plugins. Tienes 3 formas de facilitarles esto, de más a menos automática.

Opción A: Troy Embed (la más transparente)

Esta es la opción que recomiendo para la mayoría de casos. Consiste en incluir un pequeño fragmento de código en tu plugin que instala Troy Client automáticamente cuando el usuario activa tu plugin.

El usuario no tiene que hacer nada extra: instala tu plugin, lo activa, y Troy Client aparece instalado y activo sin intervención.

Implementación de Troy Embed:

Crea un archivo includes/troy-embed.php en tu plugin con el siguiente código:

<?php
/**
 * Troy Embed - Instala Troy Client automáticamente
 * 
 * Este código instala y activa Troy Client si no está presente.
 * Incluir en el archivo principal del plugin o en un archivo separado.
 */

// Evitar acceso directo
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Comprueba e instala Troy Client si es necesario
 */
function miplugin_troy_embed_init() {
    // Si Troy Client ya está activo, no hacer nada
    if ( defined( 'TROY_CLIENT_VERSION' ) ) {
        return;
    }

    // Si no estamos en el admin, no hacer nada
    if ( ! is_admin() ) {
        return;
    }

    // Comprobar si Troy Client está instalado pero no activo
    $troy_client_file = 'troy-client/troy-client.php';
    
    if ( file_exists( WP_PLUGIN_DIR . '/' . $troy_client_file ) ) {
        // Está instalado, solo hay que activarlo
        activate_plugin( $troy_client_file );
        return;
    }

    // No está instalado, hay que descargarlo e instalarlo
    miplugin_install_troy_client();
}
add_action( 'admin_init', 'miplugin_troy_embed_init' );

/**
 * Descarga e instala Troy Client
 */
function miplugin_install_troy_client() {
    // URL de descarga de Troy Client
    $download_url = 'https://repo.deploytroy.org/plugin/get/zip/troy-client';
    
    // Necesitamos las funciones de instalación de plugins
    require_once ABSPATH . 'wp-admin/includes/file.php';
    require_once ABSPATH . 'wp-admin/includes/plugin-install.php';
    require_once ABSPATH . 'wp-admin/includes/class-wp-upgrader.php';
    require_once ABSPATH . 'wp-admin/includes/plugin.php';

    // Descargar el plugin
    $temp_file = download_url( $download_url );
    
    if ( is_wp_error( $temp_file ) ) {
        // Error en la descarga, registrar y salir
        error_log( 'Troy Embed: Error descargando Troy Client - ' . $temp_file->get_error_message() );
        return;
    }

    // Instalar el plugin
    $upgrader = new Plugin_Upgrader( new Quiet_Skin() );
    $installed = $upgrader->install( $temp_file );

    // Limpiar archivo temporal
    @unlink( $temp_file );

    if ( is_wp_error( $installed ) || ! $installed ) {
        error_log( 'Troy Embed: Error instalando Troy Client' );
        return;
    }

    // Activar Troy Client
    $activate = activate_plugin( 'troy-client/troy-client.php' );
    
    if ( is_wp_error( $activate ) ) {
        error_log( 'Troy Embed: Error activando Troy Client - ' . $activate->get_error_message() );
    }
}

/**
 * Skin silencioso para el upgrader (no muestra nada en pantalla)
 */
if ( ! class_exists( 'Quiet_Skin' ) ) {
    class Quiet_Skin extends WP_Upgrader_Skin {
        public function feedback( $string, ...$args ) {
            // No mostrar nada
        }
        public function header() {}
        public function footer() {}
    }
}

Ahora, en tu archivo principal del plugin, incluye este archivo:

<?php
/**
 * Plugin Name: Mi Plugin Premium
 * Plugin URI: https://tudominio.com/mi-plugin-premium
 * Description: Plugin premium con Troy Embed integrado.
 * Version: 1.0.0
 * Author: Tu Nombre
 * Troy: repo.tudominio.com
 */

// Evitar acceso directo
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

// Incluir Troy Embed para instalación automática de Troy Client
require_once plugin_dir_path( __FILE__ ) . 'includes/troy-embed.php';

// Resto del código de tu plugin...

¿Qué hace este código?

1. Cuando se activa tu plugin, comprueba si Troy Client ya está activo
2. Si no está activo pero sí instalado, lo activa
3. Si no está instalado, lo descarga desde el repositorio oficial de Troy y lo instala silenciosamente
4. Todo esto ocurre sin que el usuario vea nada (el Quiet_Skin se encarga de eso)

Opción B: Troy Package

Troy Server puede generar un paquete que incluye todo lo necesario en un solo ZIP:

• Troy Client
• Tu plugin (o plugins)
• Un instalador que lo configura todo automáticamente

Para generar un Troy Package:

1. En tu Troy Server, ve a la sección de Packages
2. Crea un nuevo paquete
3. Selecciona los plugins que quieres incluir
4. Genera el paquete
5. Obtendrás una URL de descarga que puedes dar a tus usuarios

El usuario descarga el ZIP, lo instala como cualquier plugin, y automáticamente tiene Troy Client y tus plugins instalados y configurados.

Esta opción es ideal cuando vendes un producto y quieres que la experiencia de instalación sea lo más sencilla posible.

Opción C: Documentación manual

La opción más básica pero perfectamente válida para usuarios técnicos: simplemente documentas que necesitan instalar Troy Client primero.

En la documentación de tu plugin, incluye algo como:

Requisito previo: Este plugin requiere Troy Client para recibir actualizaciones automáticas. Descarga Troy Client aquí e instálalo antes de instalar este plugin.

Paso 5: Verificar que todo funciona

Antes de distribuir tu plugin, haz estas comprobaciones:

En tu Troy Server

1. Accede a la sección de plugins y verifica que tu plugin aparece con la versión correcta
2. Comprueba que la URL del plugin es accesible: https://repo.tudominio.com/plugin/get/info/mi-plugin-premium
3. Verifica que puedes descargar el ZIP: https://repo.tudominio.com/plugin/get/zip/mi-plugin-premium

En un sitio de prueba

1. Instala Troy Client en un WordPress de prueba
2. Instala tu plugin (con la cabecera Troy configurada)
3. Ve a Escritorio → Actualizaciones y verifica que tu plugin aparece si hay actualizaciones disponibles
4. Ve a Herramientas → Salud del sitio → Información y busca la sección de Troy Client para verificar la conexión

Probar una actualización

1. Cambia la versión de tu plugin local (por ejemplo, de 1.0.0 a 0.9.0 para simular que es antigua)
2. Recarga la página de actualizaciones
3. Deberías ver que hay una actualización disponible desde tu Troy Server
4. Actualiza el plugin y verifica que la actualización se aplica correctamente

Opciones avanzadas

Troy Client Hide: ocultar Troy Client del listado de plugins

Si no quieres que tus usuarios vean Troy Client en su listado de plugins (para una experiencia más limpia), puedes añadir esta constante en wp-config.php de los sitios de tus clientes:

define( 'TROY_CLIENT_HIDE', true );

Troy Client seguirá funcionando perfectamente, pero no aparecerá en la lista de plugins instalados.

Troy Client Channel: canal de actualizaciones beta

Si quieres que un sitio reciba versiones beta de Troy Client (y de los plugins que publiques con versiones beta), añade:

define( 'TROY_CLIENT_CHANNEL', 'beta' );

Útil para sitios de staging o para usuarios que quieran probar las novedades antes que nadie.

Troy Client Daemon: garantizar que Troy Client siempre esté activo

Si gestionas múltiples sitios de clientes y quieres asegurarte de que Troy Client nunca se desactive accidentalmente, puedes usar el Daemon.

El Troy Client Daemon es un mu-plugin (must-use plugin) que:

• Reinstala Troy Client si se elimina
• Reactiva Troy Client si se desactiva
• Bloquea las peticiones a WordPress.org si Troy Client no está activo

Para instalarlo, descarga troy-client-daemon.php desde el repositorio de GitHub y colócalo en /wp-content/mu-plugins/ (crea la carpeta si no existe). No necesita activación, los mu-plugins se cargan automáticamente.

Privacidad y estadísticas

Troy está diseñado con la privacidad como principio fundamental:

• No se envían nombres de dominio: tu servidor no sabe en qué sitios están instalados tus plugins.
• Identificadores rotativos: cada sitio genera un UUID anónimo que cambia cada 4 semanas, impidiendo el rastreo.
• Solo HTTPS: todas las comunicaciones van cifradas.
• Datos segmentados: cada plugin solo envía estadísticas a su repositorio correspondiente.

Las estadísticas que sí puedes ver en tu Troy Server son:

• Número de descargas (totales y por versión).
• Distribución de versiones instaladas.
• Versiones de PHP de tus usuarios.
• Versiones de WordPress.
• Idiomas/locales.

Todo anónimo y agregado. No hay forma de identificar sitios individuales.

Resumen de requisitos

Para desarrolladores (Troy Server)

Para usuarios finales (Troy Client)

Licencia y más información

Troy usa licencia MIT, no GPL. Esto significa que puedes usarlo, modificarlo e incluirlo en proyectos comerciales sin restricciones, solo manteniendo el aviso de copyright. Sybre lo define como «un regalo sin condiciones».

Más información:

• Web oficial de Deploy Troy
• Documentación de Troy Client
• Documentación de Troy Server
• Repositorio en GitHub
• Foro de soporte en GitHub Discussions

Conclusión: ¿merece la pena?

Si distribuyes plugins fuera de WordPress.org y hasta ahora has estado usando soluciones caseras o dependiendo de servicios de terceros para gestionar actualizaciones, Troy es una alternativa bien pensada, para mi gusto, mejor que la de FAIR.

Los requisitos de servidor son exigentes (PHP 8.4 no está disponible en todos los hosting compartidos), pero ya hemos visto que es posible, incluso sencillo, montar tu propio repositorio es cuestión de minutos.

El hecho de que venga de alguien con la experiencia de Sybre Waaijer, que lleva años usando un sistema similar en producción con miles de sitios, da confianza en que es una solución probada y no un experimento. De hecho él mismo lo usa como te comenté al principio.

Pero, precisamente, esto mismo es lo que me hace dudar del proyecto, que no de la solución propuesta, que me encanta, y es que un desarrollo que dependa de una sola persona es demasiado frágil a largo plazo. La parte buena es que es Open Source y ahí está por si más gente quiere unirse, ampliarlo, mejorarlo, continuarlo si a Sybre le da la pájara de abandonarlo un día de estos, que la vida tiene sus cosas.

En cualquier caso, como te digo, la idea es cojonuda y el sistema tremendamente bueno. Para desarrolladores de plugins premium, agencias que crean soluciones a medida, o cualquiera que quiera independencia total sobre la distribución de su código, Deploy Troy es probablemente la mejor alternativa disponible ahora mismo en el ecosistema WordPress, fuera claro está, del repositorio de WordPress, que sigue siendo la mejor opción.

¿Te gustó este artículo? ¡Ni te imaginas lo que te estás perdiendo en YouTube!