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
- Instale o VS Code para o seu Linux e as dependências deste guia.
- Abra o terminal com seu usuário de desenvolvimento, entre na pasta do projeto e execute
code .. - Instale o VSIX no VS Code. Confira se a extensão está habilitada nessa janela.
- Execute Titan Architect: Diagnosticar ambiente e resolva os requisitos ausentes.
- Execute Titan Architect: Iniciar núcleo Titan local para validar a base vazia.
- 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.
- Instale as dependências no servidor Linux com seu procedimento administrativo normal.
- No computador que possui a interface do VS Code, instale a extensão oficial Remote - SSH.
- 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
- Use Remote-SSH: Connect to Host…, selecione
titan-deve abra a pasta remota do projeto. - Instale/habilite o Titan Architect Studio em SSH: titan-dev, e não apenas na lista de extensões locais.
- No terminal remoto, execute todas as verificações de versão deste guia.
- 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.