STUDIO 0.3.0 / AMBIENTE LINUX OBRIGATÓRIO

Preparar Linux, WSL2 e Remote SSH

Um ambiente Linux é obrigatório para a execução completa do Titan Architect Studio. O núcleo local, o banco privado e o worker WebSocket foram implementados para Linux. Windows nativo não substitui esse ambiente.

Você pode usar um desktop Linux, executar Linux no WSL2 ou conectar o VS Code a uma máquina Linux com Remote SSH. O editor pode estar no Windows: o que precisa ser Linux é o host de execução do workspace, com PHP, Node, MySQL e os arquivos do projeto.

Escolha sua forma de trabalhar

Cenário Onde instalar as dependências Onde abrir o projeto
Linux local No seu Linux Pasta local do usuário
Windows com WSL2 Dentro da distribuição Linux do WSL Pasta Linux, por exemplo ~/projetos/titan
Windows/Linux/macOS com Remote SSH No servidor Linux de desenvolvimento Pasta remota aberta pelo VS Code

Instalar PHP e MySQL no Windows e abrir um terminal WSL não é suficiente se a extensão continua executando no host Windows. Confira a indicação de WSL/SSH na barra de status e a instalação da extensão no contexto remoto.

Use um usuário comum para desenvolver. sudo é usado para instalar pacotes do sistema, não para executar o VS Code ou iniciar o host do Studio. O MySQL privado deve pertencer à sua conta de desenvolvimento.

Base Linux: exemplo Ubuntu

O roteiro de pacotes abaixo é destinado a Ubuntu 24.04 LTS ou superior, com PHP 8.2+ e MySQL Server 8+. Outras distribuições precisam fornecer os mesmos requisitos; nomes de pacotes podem mudar. MariaDB não é um substituto transparente para o inicializador MySQL usado nesta versão.

sudo apt update
sudo apt install -y \
  php-cli php-mysql php-mbstring php-xml php-curl php-zip \
  php-intl php-bcmath php-gd \
  mysql-server python3 composer git unzip curl ca-certificates xz-utils

O Studio usa uma instância MySQL própria, com --no-defaults, datadir privado e socket Unix. Ele não depende de apontar o projeto para o serviço MySQL padrão da máquina e não precisa das credenciais do seu banco operacional.

Confira as versões antes de seguir:

uname -s
php --version
php -m
mysqld --version
python3 --version
composer --version

uname -s deve informar Linux. PHP precisa ser 8.2 ou superior, e mysqld precisa ser o servidor MySQL 8+, não somente o cliente mysql.

Verifique as extensões necessárias ao host:

php -r '$required=["pdo_mysql","mbstring","pcntl","posix","sockets","sodium"]; $missing=array_values(array_filter($required,fn($name)=>!extension_loaded($name))); if($missing){fwrite(STDERR,"Faltando: ".implode(", ",$missing).PHP_EOL); exit(1);} echo "PHP pronto".PHP_EOL;'

Se houver extensão ausente, instale/habilite o pacote correspondente à versão do PHP desse Linux e repita a verificação. Não desative as verificações para conseguir iniciar o host.

Instale Node.js 22 ou superior no Linux

Use uma versão compatível do Node no próprio ambiente Linux. O compilador TypeScript acompanha o Studio, mas ele ainda precisa do executável Node. O npm é usado pelos projetos que possuem dependências adicionais e scripts de teste.

A página oficial de downloads do Node.js permite selecionar a linha suportada e a arquitetura. O exemplo abaixo usa a distribuição oficial 22.23.5 e verifica o SHA-256 do arquivo baixado. Se usar outra versão suportada, ajuste o identificador nos comandos e confira os checksums da mesma versão.

case "$(uname -m)" in
  x86_64) TITAN_NODE_ARCH=x64 ;;
  aarch64|arm64) TITAN_NODE_ARCH=arm64 ;;
  *) echo "Confira uma distribuição Node para sua arquitetura"; exit 1 ;;
esac
TITAN_NODE_VERSION=v22.23.5
TITAN_NODE_ARCHIVE="node-${TITAN_NODE_VERSION}-linux-${TITAN_NODE_ARCH}"
mkdir -p "$HOME/.local/share/titan-node/downloads"
cd "$HOME/.local/share/titan-node/downloads"
curl --fail --location --remote-name "https://nodejs.org/dist/${TITAN_NODE_VERSION}/${TITAN_NODE_ARCHIVE}.tar.xz"
curl --fail --location --remote-name "https://nodejs.org/dist/${TITAN_NODE_VERSION}/SHASUMS256.txt"
sha256sum --check --ignore-missing SHASUMS256.txt
tar -xJf "${TITAN_NODE_ARCHIVE}.tar.xz" -C "$HOME/.local/share/titan-node"
export PATH="$HOME/.local/share/titan-node/${TITAN_NODE_ARCHIVE}/bin:$PATH"
node --version
npm --version

Só extraia se a verificação do arquivo terminar com OK. Para autenticidade dos checksums, consulte também as orientações oficiais de verificação das assinaturas do projeto Node.js.

A alteração de PATH acima vale para o terminal atual. Adicione o diretório de binários ao perfil do seu shell para persistir a configuração ou informe no Studio o caminho absoluto retornado por command -v node. Reabra/reconecte o VS Code após mudar o ambiente do host remoto. O Studio não expande ~ ou $HOME dentro dos campos de executável: use um caminho absoluto nesses campos.

Linux local

  1. Instale o VS Code para o seu Linux e as dependências deste guia.
  2. Abra o terminal com seu usuário de desenvolvimento, entre na pasta do projeto e execute code ..
  3. Instale o VSIX no VS Code. Confira se a extensão está habilitada nessa janela.
  4. Execute Titan Architect: Diagnosticar ambiente e resolva os requisitos ausentes.
  5. Execute Titan Architect: Iniciar núcleo Titan local para validar a base vazia.
  6. Abra o manifesto de um módulo e use Carregar módulo nativo no Titan local para iniciar seu fluxo de trabalho.

Windows com WSL2

No PowerShell como administrador, verifique as distribuições disponíveis e instale uma distribuição Ubuntu adequada:

wsl --list --online
wsl --set-default-version 2
wsl --install -d Ubuntu-24.04

Reinicie o Windows se a instalação solicitar. Abra a distribuição e crie seu usuário Linux. Confirme pelo PowerShell:

wsl --list --verbose

A distribuição usada pelo projeto deve aparecer com versão 2. A documentação oficial do WSL descreve os requisitos e as variações do procedimento.

No Linux do WSL, execute a instalação de PHP, MySQL, Python, Composer e Node deste guia. Mantenha os fontes no filesystem Linux para esse fluxo:

mkdir -p ~/projetos/titan
cd ~/projetos/titan
code .

No Windows, instale o VS Code e a extensão oficial WSL. Abra a pasta com WSL: Open Folder in WSL ou por code . no terminal da distribuição. A barra de status deve mostrar WSL: Ubuntu…. Instale/habilite o Titan Architect Studio nesse contexto WSL.

O terminal integrado precisa responder Linux para uname -s. command -v php, command -v node e command -v mysqld devem apontar para arquivos do Linux. Se retornarem executáveis do Windows ou não forem encontrados, corrija o contexto antes de iniciar o runtime. Consulte o guia oficial do VS Code para WSL.

Remote SSH para Linux

Use uma máquina Linux de desenvolvimento e uma conta com acesso aos fontes. Não reutilize uma conta operacional nem um diretório de produção para resolver requisitos do Studio.

  1. Instale as dependências no servidor Linux com seu procedimento administrativo normal.
  2. No computador que possui a interface do VS Code, instale a extensão oficial Remote - SSH.
  3. Configure uma conexão SSH para a conta de desenvolvimento. Um exemplo de entrada em ~/.ssh/config é:
Host titan-dev
    HostName seu-servidor-de-desenvolvimento
    User seu-usuario
    IdentityFile ~/.ssh/id_ed25519
  1. Use Remote-SSH: Connect to Host…, selecione titan-dev e abra a pasta remota do projeto.
  2. Instale/habilite o Titan Architect Studio em SSH: titan-dev, e não apenas na lista de extensões locais.
  3. No terminal remoto, execute todas as verificações de versão deste guia.
  4. Inicie o núcleo local pela extensão e confira o painel Portas caso seja necessário inspecionar os encaminhamentos.

O Studio usa as portas locais de HTTP e WebSocket e solicita seu encaminhamento pelo VS Code. Não é necessário publicar as portas do banco ou abrir uma exposição pública do host de desenvolvimento. A documentação oficial de Remote SSH explica a conexão e a instalação de extensões remotas.

Configuração do Studio

Nas configurações de usuário do contexto Linux/WSL/SSH:

{
  "titanStudio.phpPath": "php",
  "titanStudio.nodePath": "node",
  "titanStudio.mysqlServerPath": "mysqld",
  "titanStudio.sdkPath": ""
}

Se o PATH remoto não encontrar um executável, substitua o nome pelo caminho absoluto mostrado por command -v. Deixe sdkPath vazio para usar o SDK V2 embarcado; não é preciso baixar outro SDK para o primeiro uso do Studio.

Checklist final

  • O host do workspace responde Linux.
  • A extensão está instalada no contexto correto: local Linux, WSL ou SSH.
  • PHP 8.2+, Node 22+, MySQL Server 8+, Python e as extensões PHP estão disponíveis nesse host.
  • Há espaço e permissões para criar um banco privado e cópias locais dos módulos.
  • O workspace contém código confiável, e as dependências nativas necessárias estão disponíveis como módulos irmãos.
  • O diagnóstico foi revisado, e o núcleo vazio abriu antes de carregar integrações.
  • Nenhuma credencial, diretório de dados ou conexão operacional foi usado para preencher o ambiente local.