📝Guia Passo a Passo: Como Instalar o UmbrelOS no Debian (via WSL)📝

Doctor Technology
8 de nov.
5 min de leitura

Olá, pessoal! Se você está procurando uma maneira de rodar seu próprio servidor pessoal, o UmbrelOS é uma solução fantástica. Ele permite que você hospede aplicativos de forma fácil e segura.

Neste tutorial, vou mostrar o passo a passo exato que usei para instalar o UmbrelOS em uma distribuição Debian rodando no WSL (Windows Subsystem for Linux).

Vamos começar!

Parte 1: Configurando o Ambiente Debian no WSL

Antes de tudo, precisamos ter um ambiente Debian limpo e configurado no WSL. Se você já tem o Debian instalado, pode pular para o próximo passo.

Estes comandos instalam o Debian, exportam a instalação (para backup ou para movê-la para um local específico, como um SSD diferente) e a reimportam.

Nota: Os comandos de exportação e importação são ótimos para gerenciar onde seus dados do WSL ficam. No exemplo, estou movendo para D:\WSL.

# Comandos para executar no PowerShell ou CMD do Windows

# Instala a distribuição Debian
wsl --install Debian

# Exporta a instalação padrão para um arquivo .tar
wsl --export Debian D:\WSL\Debian.tar

# Desregistra a instalação original
wsl --unregister Debian

# Importa o .tar de volta para o WSL, mas agora no diretório D:\WSL
wsl --import Debian D:\WSL D:\WSL\Debian.tar

Após isso, inicie sua nova máquina Debian pelo menu Iniciar ou com o comando wsl -d Debian.

Parte 2: Instalando o Docker

O UmbrelOS é totalmente baseado em contêineres Docker. Portanto, precisamos de uma instalação limpa do Docker.

Nota Importante: Estou usando sudo su para me tornar superusuário (root) e cd /home/DoctorServer/ para ir ao meu diretório de trabalho. Ajuste o caminho /home/DoctorServer/ para o de sua preferência!

# Comandos para executar DENTRO do seu terminal Debian

# Torna-se root e vai para o diretório de trabalho
sudo su
cd /home/DoctorServer/

# Remove versões antigas do Docker, se existirem
sudo apt-get remove docker docker-engine docker.io containerd runc

# Atualiza os pacotes
sudo apt-get update
sudo apt-get upgrade

# Instala pacotes de pré-requisito
sudo apt-get install ca-certificates curl gnupg lsb-release

# Adiciona a chave GPG oficial do Docker
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Adiciona o repositório oficial do Docker
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Atualiza os pacotes novamente (agora com o repositório do Docker)
sudo apt-get update
sudo apt-get upgrade

# Instala o Docker Engine, CLI, Containerd e o plugin do Compose
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Após isso, inicie sua nova máquina Debian pelo menu Iniciar ou com o comando wsl -d Debian.

Parte 2: Instalando o Docker

O UmbrelOS é totalmente baseado em contêineres Docker. Portanto, precisamos de uma instalação limpa do Docker.

Nota Importante: Estou usando sudo su para me tornar superusuário (root) e cd /home/DoctorServer/ para ir ao meu diretório de trabalho. Ajuste o caminho /home/DoctorServer/ para o de sua preferência!

# Comandos para executar DENTRO do seu terminal Debian

# Torna-se root e vai para o diretório de trabalho
sudo su
cd /home/DoctorServer/

# Remove versões antigas do Docker, se existirem
sudo apt-get remove docker docker-engine docker.io containerd runc

# Atualiza os pacotes
sudo apt-get update
sudo apt-get upgrade

# Instala pacotes de pré-requisito
sudo apt-get install ca-certificates curl gnupg lsb-release

# Adiciona a chave GPG oficial do Docker
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Adiciona o repositório oficial do Docker
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Atualiza os pacotes novamente (agora com o repositório do Docker)
sudo apt-get update
sudo apt-get upgrade

# Instala o Docker Engine, CLI, Containerd e o plugin do Compose
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Parte 3: Instalando o Composer

O Composer é um gerenciador de dependências para PHP, também necessário para o Umbrel.

# Comandos para executar DENTRO do seu terminal Debian

sudo apt update
sudo apt-get upgrade

# Instala PHP e outras ferramentas
sudo apt install php-cli php-curl php-zip unzip git -y

# Baixa o instalador do Composer
curl -sS https://getcomposer.org/installer -o composer-setup.php

# Executa o instalador, movendo o Composer para o binário global
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

# Remove o arquivo de instalação
rm composer-setup.php

# Verifica a instalação
composer --version

Parte 4: Instalando Dependências Adicionais

O Umbrel precisa de mais alguns pacotes para funcionar corretamente, como Node.js, jq (para processar JSON) e rsync.

# Comandos para executar DENTRO do seu terminal Debian

sudo apt update
sudo apt install nodejs npm -y
sudo apt-get install jq
npm install jsonwebtoken
sudo apt-get install rsync
sudo apt-get install parted

Parte 5: Baixando e Configurando o UmbrelOS

Agora vamos clonar o repositório oficial do Umbrel e iniciar o script de desenvolvimento.

# Comandos para executar DENTRO do seu terminal Debian

# Garante que o git está instalado
sudo apt update && sudo apt install git -y

# Clona o repositório do Umbrel
git clone https://github.com/getumbrel/umbrel.git

# Entra no diretório
cd umbrel

# Inicia o script de desenvolvimento (isso pode demorar um pouco!)
./scripts/umbrel-dev

Parte 6: Criando um Serviço de Inicialização Automática (systemd)

Não queremos ter que iniciar o Umbrel manualmente toda vez que ligamos o WSL, certo? Vamos criar um serviço systemd para que ele inicie automaticamente.

Primeiro, crie o arquivo de serviço:

# Comandos para executar DENTRO do seu terminal Debian

# Navega para o diretório de serviços do systemd
cd /etc/systemd/system/

# Cria e abre o arquivo de serviço com o editor nano
nano umbrel-startup.service

Cole o conteúdo abaixo dentro do editor nano.

Atenção: Lembre-se de alterar os caminhos ExecStart e ExecStop se você não usou /home/DoctorServer/!

[Unit]
Description=Umbrel Startup Service
After=network.service NetworkManager-wait-online.service mnt-umbrel.mount

[Service]
ExecStart=/home/DoctorServer/umbrel/scripts/umbrel-dev
ExecStop=/home/DoctorServer/umbrel/scripts/umbrel-dev

[Install]
WantedBy=multi-user.target

Salve e feche o nano (aperte CTRL + X, depois Y e Enter).

Agora, vamos habilitar o serviço:

# Comandos para executar DENTRO do seu terminal Debian

# Recarrega os daemons do systemctl
sudo systemctl daemon-reload

# Habilita nosso serviço para iniciar no boot
sudo systemctl enable umbrel-startup.service

# Reinicia a máquina virtual
sudo reboot

# Após reiniciar, verifique o status do serviço
sudo systemctl status umbrel-startup.service

Se tudo estiver verde e "active (running)", você conseguiu!

Parte 7: Expondo o Umbrel na Rede (Comandos Windows)

Por padrão, o servidor Umbrel só está acessível de dentro do WSL. Para acessá-lo pelo navegador do seu Windows (em http://localhost), precisamos fazer um redirecionamento de porta.

Primeiro, você precisa saber o IP da sua máquina WSL. No terminal Debian, digite:

hostname -I

Anote esse IP. Agora, abra o PowerShell ou CMD como Administrador no Windows e execute os comandos abaixo, substituindo <IP WSL> pelo IP que você anotou.

PowerShell

# Comando para executar no PowerShell (como Administrador)

# Redireciona a porta 80 do seu Windows para a porta 80 do WSL
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=80 connectaddress=<IP WSL> connectport=80

⚠️ AVISO IMPORTANTE SOBRE O FIREWALL ⚠️

Você pode precisar de uma regra de firewall. O comando abaixo DESLIGA COMPLETAMENTE o firewall do Windows.

PowerShell

# Comando NÃO RECOMENDADO para uso diário
netsh advfirewall set allprofiles state off

Isso é perigoso e deixa seu computador vulnerável. Uma alternativa muito mais segura é criar uma regra específica para permitir o tráfego na porta 80:

PowerShell

# Comando RECOMENDADO para o Firewall do Windows
netsh advfirewall firewall add rule name="Umbrel WSL Port 80" dir=in action=allow protocol=TCP localport=80

Conclusão

Pronto! Se tudo correu bem, agora você pode abrir seu navegador e acessar http://localhost ou http://<IP WSL> para ver a tela de configuração inicial do seu UmbrelOS.

Espero que este guia tenha sido útil! Deixe um comentário se tiver qualquer dúvida.