Guia Definitivo: Instalando o Frappe Framework no Windows com WSL

Este guia detalha o processo completo para instalar um ambiente de desenvolvimento robusto para o Frappe Framework no Windows 10 ou 11, utilizando o Subsistema Windows para Linux (WSL) com Ubuntu 22.04. O foco é exclusivamente na instalação do framework base, preparando o terreno para a criação de aplicativos customizados ou a futura instalação de apps como o ERPNext.

Pré-requisitos

• Windows 10 ou 11.
• Conexão com a internet.
• Terminal com privilégios de Administrador (PowerShell ou Prompt de Comando).

Passo 1: Habilitando o WSL e Instalando o Ubuntu 22.04

Se você ainda não possui o WSL configurado, este é o ponto de partida.

1. Abra o PowerShell ou Prompt de Comando como Administrador.
2. Execute o comando para instalar o WSL e a distribuição Ubuntu 22.04:

wsl --install -d Ubuntu-22.04

3. Reinicie o computador quando solicitado. Após a reinicialização, o terminal do Ubuntu será aberto para que você crie seu usuário e senha padrão do Linux.

Passo 2: Criando um Usuário Dedicado 'frappe' (Etapa Crucial)

Para evitar 99% dos problemas de permissão, nunca execute os comandos do Frappe como root ou com seu usuário padrão. Vamos criar um usuário dedicado chamado frappe.

1. No terminal do Ubuntu, crie o novo usuário:

sudo adduser frappe

2. Adicione este usuário ao grupo sudo para que ele possa executar tarefas administrativas:

sudo usermod -aG sudo frappe

3. Feche o terminal atual e abra um novo. A partir de agora, sempre troque para este usuário antes de começar a trabalhar:

su - frappe

Importante: O hífen (-) é essencial. Ele simula um login completo, carregando o ambiente e as configurações corretas do usuário frappe.

Passo 3: Instalando as Dependências do Sistema

Agora, como usuário frappe, vamos instalar todos os pacotes de software necessários.

1. Atualize a lista de pacotes do Ubuntu:

sudo apt update && sudo apt upgrade -y

2. Instale os pacotes essenciais:

Isso inclui Git, Python, MariaDB, Redis, e outras bibliotecas necessárias.

sudo apt install -y git python3-dev python3-pip python3-venv mariadb-server redis-server libmariadb-dev pkg-config curl

3. Configure e proteja o MariaDB:

Este script interativo definirá a senha do superusuário (root) do banco de dados.

sudo mariadb-secure-installation

Siga as instruções na tela. É extremamente importante que você defina e anote a senha do root do MariaDB, pois ela será necessária em breve.

Passo 4: Instalando Node.js e Ferramentas de Frontend

O Frappe utiliza Node.js e Yarn. A melhor forma de instalar o Node.js é através do NVM (Node Version Manager).

1. Instale o NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

2. Carregue o NVM no seu terminal: (Feche e reabra o terminal ou execute o comando abaixo)

source ~/.bashrc

3. Instale a versão 18 do Node.js (recomendada):

nvm install 18

4. Instale o Yarn globalmente:

npm install -g yarn

Passo 5: Instalando o Gerador de PDF (wkhtmltopdf)

Esta ferramenta é essencial para que o Frappe Framework possa criar documentos em PDF, como relatórios e faturas.

1. Instale as dependências gráficas necessárias:

sudo apt install -y xvfb libfontconfig1

2. Baixe o pacote para Ubuntu 22.04 (Jammy):

wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb

3. Instale o pacote baixado:

sudo dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb

Dica: E se eu já baixei o arquivo pelo navegador no Windows?

Se você baixou o arquivo .deb na sua pasta de Downloads do Windows, pode acessá-lo diretamente pelo terminal do WSL. O seu disco C: está montado em /mnt/c/. O comando para acessar a pasta e instalar será algo assim (substitua <seu-usuario-windows> pelo seu nome de usuário do Windows):

# 1. Navegue até a sua pasta de Downloads do Windows
cd /mnt/c/Users/<seu-usuario-windows>/Downloads

# 2. Instale o pacote a partir desta pasta
sudo dpkg -i wkhtmltox_0.12.6.1-2.jammy_amd64.deb

Passo 6: Instalando o Frappe Bench

bench é a CLI que você usará para gerenciar todo o seu ambiente Frappe.

1. Instale o frappe-bench usando pip:

pip install frappe-bench

2. Verifique se o bench está no seu PATH:

Execute bench --version. Se o comando não for encontrado, adicione o diretório local de binários ao seu PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Passo 7: Criando seu Ambiente ("Bench") e Primeiro Site

1. Inicialize a "bench":

# Certifique-se de estar no seu diretório home
cd ~
bench init frappe-bench

2. Entre no diretório da sua bench:

cd frappe-bench

3. Crie um novo site: (Substitua meu-site.local pelo nome que desejar)

bench new-site meu-site.local

O sistema pedirá a senha do root do MariaDB e, em seguida, você criará a senha para o usuário Administrator do seu site Frappe. Anote esta senha!

Passo 8: Iniciando o Servidor

Com tudo configurado, inicie o servidor de desenvolvimento.

bench start

Passo 9: Dicas de Desenvolvimento - O Ambiente Virtual (env)

Excelente ponto! Embora o comando bench gerencie o ambiente virtual para você na maioria das vezes, um desenvolvedor frequentemente precisa "entrar" nesse ambiente para tarefas específicas. A pasta env dentro do seu frappe-bench é um ambiente virtual Python isolado.

Quando Ativar o Ambiente Manualmente?

• Para instalar uma biblioteca Python com pip que será usada apenas neste projeto (ex: pip install requests).
• Para usar o console interativo do Frappe com o comando bench --site meu-site.local console.
• Para rodar scripts Python diretamente no contexto do Frappe.

Comandos Essenciais

Para ativar o ambiente, faça o seguinte:

# 1. Certifique-se de estar na pasta frappe-bench
cd ~/frappe-bench

# 2. Ative o ambiente
source env/bin/activate

Você saberá que funcionou, pois o seu prompt do terminal mudará, exibindo (env) no início. Por exemplo: (env) frappe@SEU-PC:~/frappe-bench$

Para sair do ambiente e voltar ao terminal normal, simplesmente digite:

deactivate

Lembrete Importante: Para comandos normais como bench start, bench update ou bench new-site, você não precisa ativar o ambiente manualmente. O bench faz isso por você nos bastidores. Esta ativação manual é apenas para as tarefas de desenvolvimento avançadas listadas acima.

Conclusão

Parabéns! O seu ambiente de desenvolvimento do Frappe Framework está no ar. Abra seu navegador no Windows e acesse http://localhost:8000.

Faça o login com o usuário Administrator e a senha que você acabou de criar. Você concluiu com sucesso a instalação de uma base sólida, pronta para desenvolver ou instalar qualquer aplicativo sobre o Frappe Framework.