O desenvolvimento moderno com WordPress evoluiu além das configurações manuais e fluxos de implantação inconsistentes. O Radicle combina o Roots e outras ferramentas de desenvolvimento para WordPress, como Bedrock, Sage e Acorn, em uma única pilha.
Essa integração significa que você pode ter a experiência de desenvolvimento do Laravel diretamente no WordPress.
Além disso, a configuração do Radicle na Kinsta oferece a você um ambiente de hospedagem compatível com os requisitos técnicos que essa pilha exige. Você obtém acesso por SSH, integração com WP-CLI e a capacidade de configurar seu diretório raiz.
Este guia descreve o processo de configuração e as etapas de implantação necessárias para executar o Radicle na infraestrutura da Kinsta.
Radicle e seus componentes
O Radicle combina três projetos Roots distintos em um ambiente de desenvolvimento integrado:
- O Bedrock fornece a base com sua estrutura de pastas aprimorada e o gerenciamento de dependências baseado no Composer.
- O Sage lida com o desenvolvimento de temas com a integração do Tailwind CSS e o Vite para a criação de ativos.
- O Acorn faz a ponte entre o WordPress e o Laravel, trazendo modelos Blade, migrações, roteamento e muito mais para seus projetos WordPress.
Esse tipo de ambiente de desenvolvimento permite que você trabalhe diretamente a partir da raiz do projeto, em vez de dentro dos diretórios típicos de temas. Seus templates ficam em resources/views/ na raiz do projeto, enquanto a configuração ocorre por meio de arquivos específicos do ambiente no diretório bedrock.
O Composer gerencia o núcleo, os plugins e as dependências personalizadas do WordPress por meio de um único arquivo composer.json. A pilha requer PHP 8.3 ou superior, juntamente com extensões específicas. Você também precisa do Composer para o gerenciamento de dependências e do WP-CLI para operações de linha de comando.
Radicle vs WordPress tradicional
As instalações padrão do WordPress (ou seja, colocar tudo dentro do diretório wp-content ) podem complicar o controle de versão e dificultar a manutenção de instalações consistentes em diferentes ambientes.
No entanto, o Radicle reestrutura isso para que você possa controlar a versão do código do aplicativo sem rastrear os arquivos principais do WordPress ou a mídia carregada:
- O núcleo do WordPress fica no diretório
public/wp, separado do código do aplicativo. - O diretório
public/contentsubstitui owp-contente o código do seu tema personalizado fica na raiz do projeto.
A configuração no estilo Laravel usa um arquivo .env em vez de incorporar credenciais do banco de dados e chaves de segurança nos arquivos de configuração. Você define configurações diferentes para os ambientes de desenvolvimento, teste e produção por meio de arquivos de configuração separados em bedrock/environments/.
Sua estratégia de controle de versão é beneficiada porque você rastreia apenas o código e a configuração do aplicativo. As atualizações do núcleo do WordPress ocorrem por meio do Composer, os plugins servem como dependências e as alterações de tema são armazenadas em seu repositório.
Configurando o Radicle para a Kinsta
Ao implantar na Kinsta, você precisa de autenticação de chave SSH, que está disponível no painel MyKinsta.
Localize seus detalhes de acesso SFTP/SSH na seção Informações do site e adicione sua chave SSH pública, se você ainda não o fez.
A infraestrutura da Kinsta está alinhada com os requisitos técnicos da Radicle. Ela executa o PHP 8.3, inclui o Composer para gerenciamento de dependências e tem o WP-CLI pré-instalado, para que você possa gerenciar o WordPress diretamente da linha de comando.
Diferentemente de uma configuração tradicional do WordPress, a Radicle usa uma estrutura de diretórios baseada em versões. Cada implantação cria uma pasta de versão com registro de data e hora, e um link simbólico current aponta para a versão ativa. O diretório raiz da web para seu aplicativo deve ser definido como public/current/public.
Em seguida, configure suas variáveis de ambiente. Copie o arquivo .env.example na raiz do projeto Radicle e renomeie-o para .env. Em seguida, adicione os detalhes do banco de dados e as configurações de ambiente:
DB_NAME='your_database_name'
DB_USER='your_database_user'
DB_PASSWORD='your_database_password'
DB_HOST='your_database_host'
WP_ENV='staging'
WP_HOME='https://{kinsta-staging-url}'
WP_SITEURL="${WP_HOME}/wp"
O Radicle instala o núcleo do WordPress em um subdiretório /wp. Isso mantém os arquivos principais separados do código do aplicativo personalizado, oferecendo suporte a uma estrutura mais limpa e com controle de versão.
Configuração do ambiente de teste
O diretório de configuração fica na raiz do seu projeto Radicle, junto com as pastas public e resources. Abra bedrock/environments/staging.php para definir configurações específicas para o ambiente de teste. Esse arquivo substitui os valores de bedrock/application.php sempre que o arquivo .env define WP_ENV para staging.
Defina a URL do seu site de teste adicionando as seguintes constantes na parte superior de staging.php:
<?php
define('WP_HOME', 'https://staging-url');
define('WP_SITEURL', WP_HOME . '/wp');
A URL do ambiente de teste segue o padrão exibido na seção Ambientes do seu site ao selecionar o ambiente de teste.
Seu caminho de implantação determina onde os arquivos ficam no servidor Kinsta. No MyKinsta, observe o caminho em Detalhes do ambiente. Normalmente, esse caminho é /www/sitename/public e representa seu destino de implantação. Seu script de implantação sincroniza os arquivos aqui, criando uma estrutura como /www/sitename/public/releases/timestamp para cada implantação, com o link simbólico /www/sitename/public/current apontando por symlink para a release ativa.
Também é uma boa prática habilitar o modo de depuração para o ambiente de teste em bedrock/environments/staging.php. Além disso, copie e defina as credenciais do banco de dados para o ambiente de teste no arquivo local .env (que não deve ser confirmado no controle de versão). Como alternativa, configure-as como variáveis de ambiente em seu servidor de implantação. A Kinsta gera credenciais exclusivas para cada ambiente.
Configuração de produção
Quando você mudar para o ambiente de produção no menu suspenso do painel MyKinsta, o processo de configuração espelhará o ambiente de teste, mas usará valores específicos de produção e configurações de segurança mais rígidas.
Para fazer isso, abra bedrock/environments/production.php no diretório bedrock da raiz do seu projeto e altere a URL de produção:
<?php
define('WP_HOME', 'https://yourdomain.com');
define('WP_SITEURL', WP_HOME . '/wp');
O tratamento de erros em produção difere do ambiente de teste. A principal diferença é desabilitar a exibição de erros enquanto mantém o registro de logs:
define('WP_DEBUG', false);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', false); Além disso, copie as credenciais do banco de dados de produção na seção Acesso ao banco de dados do MyKinsta enquanto estiver no ambiente de produção. Essas credenciais normalmente são diferentes das do ambiente de teste. No entanto, os caminhos de implantação em produção seguem o mesmo padrão do ambiente de teste, mas apontam para o diretório do ambiente de produção. O caminho exibido em Detalhes do ambiente no MyKinsta provavelmente terá uma URL diferente, embora semelhante. Seu script de implantação usará esse caminho como destino para as releases de produção.
Modificando tarefas de implantação
As configurações padrão de implantação do Radicle assumem um controle de servidor que a Kinsta não oferece em hospedagem gerenciada. Por isso, você precisa remover quaisquer tarefas de implantação que tentem gerenciar serviços do servidor.
Se você estiver usando o Trellis (a ferramenta de implantação padrão da Radicle), edite trellis/roles/deploy/hooks/finalize-after.yml e exclua completamente a tarefa Reload php-fpm. A Kinsta gerencia reinicializações do PHP-FPM automaticamente ao detectar alterações nos arquivos.
Além disso, a limpeza do cache ocorre por meio da API da Kinsta e não por comandos no servidor. Portanto, substitua qualquer limpeza de cache baseada no servidor por uma requisição HTTP ao endpoint de limpeza da Kinsta. Você pode adicionar esta tarefa ao hook de finalização da implantação depois de configurar uma chave API:
- name: Clear Kinsta cache
uri:
url: "{{ site_env.wp_home }}/kinsta-clear-cache-endpoint/"
method: GET
Cada site tem um endpoint exclusivo para segurança, que você pode obter com a equipe de suporte da Kinsta.
A build de assets é executada antes da implantação, não no servidor. Sua máquina de desenvolvimento local ou pipeline de CI/CD executa npm run build para compilar JavaScript e CSS no diretório public/build. Esses ativos compilados serão implantados junto com seus arquivos PHP.
A instalação das dependências do Composer ocorre após a sincronização de arquivos usando SSH para executar o seguinte:
cd /www/sitename/public/current
composer install --no-dev --optimize-autoloader --no-interaction
A flag --no-dev exclui dependências de desenvolvimento, como estruturas de teste e ferramentas de depuração. O sinalizador --optimize-autoloader cria mapas de classe para carregamento automático mais rápido, reduzindo a sobrecarga de localização de arquivos de classe durante as solicitações.
Adicionando o plugin Kinsta MU ao Radicle
O plugin Kinsta MU habilita cache de página completa, integração com CDN e gerenciamento de cache no MyKinsta. Como o Radicle utiliza uma estrutura de diretórios não padrão, você precisará definir constantes específicas, embora o plugin Kinsta MU possa ser adicionado ao Radicle via Composer. As constantes devem ser adicionadas em bedrock/application.php após instalar o plugin:
/**
* Kinsta CDN fix for Radicle/Bedrock structure
*/
define('KINSTA_CDN_USERDIRS', 'app');
/**
* Fix Kinsta MU Plugins URL path with Radicle/Bedrock
*/
$mu_plugins_url = Config::get('WP_CONTENT_URL') . '/mu-plugins';
define('KINSTAMU_CUSTOM_MUPLUGIN_URL', "{$mu_plugins_url}/kinsta-mu-plugins");
A primeira constante especifica o diretório de uploads na estrutura app do Bedrock. A segunda corrige os caminhos de URL dos assets do plugin, garantindo que os arquivos JS e CSS sejam carregados corretamente.
Depois de confirmar a instalação, você pode testar a limpeza de cache pelo MyKinsta para verificar se o plugin está se comunicando corretamente com a infraestrutura da Kinsta.
Como configurar implantações automatizadas
O GitHub Actions é uma maneira direta de automatizar as implementações do Radicle na Kinsta. Por exemplo, você pode criar um arquivo de fluxo de trabalho em seu repositório em .github/workflows/deploy.yml. Esse fluxo de trabalho é acionado quando você faz push para branches específicos, que criam ativos e implantam o código no ambiente correspondente.
Os segredos SSH armazenados em seu repositório GitHub permitirão conexões seguras com os servidores da Kinsta. Para isso, adicione segredos para sua chave privada SSH, host Kinsta, porta SSH e nome de usuário no GitHub.
Um script de implantação orquestra o processo de sincronização de arquivos. Normalmente, esse script usa rsync para transferir arquivos de forma eficiente, envia apenas arquivos alterados e mantém as permissões adequadas. No entanto, você deve excluir arquivos de desenvolvimento como node_modules, .git e .env da implantação para manter seu ambiente de produção limpo.
Quando você tiver uma sincronização de arquivos bem-sucedida, poderá executar as tarefas de limpeza do cache. O processo envolve o script de implantação que faz uma solicitação ao endpoint de limpeza de cache da Kinsta, aguardando confirmação e executando eventuais comandos adicionais.
Configuração do GitHub Actions
Você pode definir toda a automação de implantação criando um arquivo .github/workflows/deploy.yml. Isso gerencia a build de assets, instalação de dependências e sincronização de arquivos com a Kinsta.
O workflow começa com triggers baseados na branch, enviando a branch staging para o ambiente de teste e a main para o ambiente de produção:
name: Deploy to Kinsta
on:
push:
branches:
- staging
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '22'
- name: Install dependencies and build assets
run: |
npm ci
npm run build
As estratégias de matriz lidam com múltiplos ambientes sem duplicar o código do workflow. As variáveis específicas de ambiente que você adiciona podem mudar com base na branch que acionou o workflow.
strategy:
matrix:
include:
- branch: staging
ssh_host: ${{ secrets.KINSTA_STAGING_HOST }}
ssh_port: ${{ secrets.KINSTA_STAGING_PORT }}
ssh_user: ${{ secrets.KINSTA_STAGING_USER }}
deploy_path: /www/sitename_1/public
- branch: main
ssh_host: ${{ secrets.KINSTA_PRODUCTION_HOST }}
ssh_port: ${{ secrets.KINSTA_PRODUCTION_PORT }}
ssh_user: ${{ secrets.KINSTA_PRODUCTION_USER }}
deploy_path: /www/sitename_2/public
As etapas de build de assets criam arquivos JavaScript e CSS otimizados antes da implantação. O fluxo de trabalho usa npm ci em vez de npm install para obter compilações reproduzíveis com base em seu arquivo package-lock.json. O comando npm run build executa o script de build de produção definido em package.json, normalmente executando o Vite ou outro bundler para compilar e minificar assets.
Neste ponto, você pode adicionar a instalação do Composer após as etapas de Node.js:
- name: Setup PHP
uses: server/setup-php@v2
with:
php-version: '8.3'
- name: Install Composer dependencies
run: composer install --no-dev --optimize-autoloader --no-interaction
O fluxo de trabalho agora tem ativos compilados e dependências instaladas prontas para serem implantadas na Kinsta.
Detalhes do script de implantação
A sincronização de arquivos via rsync transfere apenas os arquivos alterados, minimizando o tempo de implantação. Para resolver isso, adicione esta etapa ao seu fluxo de trabalho do GitHub Actions depois de criar seus ativos:
- name: Deploy to Kinsta via rsync
env:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
run: |
mkdir -p ~/.ssh
echo "$SSH_PRIVATE_KEY" > ~/.ssh/deploy_key
chmod 600 ~/.ssh/deploy_key
rsync -avz --delete \
--exclude='.git' \
--exclude='node_modules' \
--exclude='.env' \
--exclude='trellis' \
-e "ssh -i ~/.ssh/deploy_key -p ${{ matrix.ssh_port }} -o StrictHostKeyChecking=no" \
./ ${{ matrix.ssh_user }}@${{ matrix.ssh_host }}:${{ matrix.deploy_path }}/releases/$(date +%Y%m%d%H%M%S)/As flags do rsync controlam o comportamento da transferência:
-ahabilita o modo arquivo que preserva permissões e timestamps.-vfornece saída detalhada para depuração.-zcomprime dados durante a transferência.
O sinalizador --delete remove arquivos do servidor que não existem mais no seu repositório, o que mantém a implantação limpa.
Os padrões de exclusão evitam a transferência de arquivos desnecessários. Além disso, os metadados do Git, as dependências de desenvolvimento, os arquivos de ambiente e as ferramentas de implantação ficam fora do servidor de produção. A estrutura de diretório da versão cria diretórios com registro de data e hora para cada implantação, permitindo reversões rápidas por meio da alteração de links simbólicos.
O gerenciamento de links simbólicos conecta seus dados persistentes a cada nova versão. Depois de sincronizar os arquivos, você pode entrar no servidor por SSH e criar links simbólicos:
- name: Create symlinks and update current
run: |
ssh -i ~/.ssh/deploy_key -p ${{ matrix.ssh_port }} -o StrictHostKeyChecking=no \
${{ matrix.ssh_user }}@${{ matrix.ssh_host }} << 'EOF'
cd ${{ matrix.deploy_path }}
# Link shared .env file
ln -nfs ${{ matrix.deploy_path }}/shared/.env \
${{ matrix.deploy_path }}/releases/$(ls -t releases | head -1)/.env
# Link uploads directory
ln -nfs ${{ matrix.deploy_path }}/shared/public/content/uploads \
${{ matrix.deploy_path }}/releases/$(ls -t releases | head -1)/public/content/uploads
# Update current symlink atomically
ln -nfs ${{ matrix.deploy_path }}/releases/$(ls -t releases | head -1) \
${{ matrix.deploy_path }}/current
EOFO arquivo .env contém a configuração específica do ambiente que persiste entre as implementações. Uploads armazenados fora do diretório de release evitam perda de arquivos de mídia quando releases antigas são removidas. A atualização atômica do symlink, feita com (ln -nfs) garante zero tempo de inatividade, pois as requisições nunca atingem uma release parcialmente implantada.
A limpeza remove releases antigas após uma implantação bem-sucedida para manter apenas as cinco mais recentes:
- name: Clean up old releases
run: |
ssh -i ~/.ssh/deploy_key -p ${{ matrix.ssh_port }} -o StrictHostKeyChecking=no \
${{ matrix.ssh_user }}@${{ matrix.ssh_host }} << 'EOF'
cd ${{ matrix.deploy_path }}/releases
ls -t | tail -n +6 | xargs rm -rf
EOFEssa estratégia de limpeza atinge um equilíbrio entre a utilização do espaço em disco e a capacidade de reversão. Cinco versões oferecem vários pontos de reversão e, ao mesmo tempo, evitam o crescimento indefinido do armazenamento.
Resumo
O Radicle transforma o desenvolvimento com WordPress ao integrar a estrutura aprimorada do Bedrock, o fluxo moderno de desenvolvimento de temas do Sage e os recursos do Laravel fornecidos pelo Acorn em uma única pilha.
A implantação na Kinsta exige uma configuração além da hospedagem padrão do WordPress, mas oferece benefícios em segurança, capacidade de manutenção e experiência do desenvolvedor que justificam o esforço de configuração.
Quando você estiver pronto para implantar aplicativos modernos em WordPress com confiança, explore a hospedagem gerenciada para WordPress da Kinsta e experimente uma infraestrutura de hospedagem que oferece suporte ao fluxo de desenvolvimento personalizado que você deseja.
