Como instalar o n8n com Docker: passo a passo do zero

Instale o Docker no computador ou servidor

Antes de subir o n8n, confirme que o Docker está instalado e respondendo. No Windows e no macOS, o atalho é instalar o Docker Desktop e abrir o programa pelo menos uma vez para garantir que o serviço inicializou. No Linux, um caminho básico no Ubuntu é rodar sudo apt update e depois sudo apt install docker.io. Em alguns ambientes, o Docker Compose entra no pacote junto com o Docker; em servidores Linux, você verifica se ele está disponível com docker compose version ou docker-compose -v.

Se estiver usando um VPS, confira se você tem acesso por SSH, permissões sudo ou root e se a porta 5678 está liberada no firewall. Para validar o Docker, rode docker -v. Em ambiente Linux, ainda dá para adicionar seu usuário ao grupo do Docker com sudo usermod -aG docker $USER, o que corta a necessidade de usar sudo em todos os comandos. Depois disso, é comum precisar fazer logout e login novamente para a alteração valer na sessão atual.

Crie um espaço persistente para não perder seus fluxos

O n8n precisa de um local persistente para guardar workflows, credenciais, chaves e arquivos de configuração. Sem isso, parar ou remover o contêiner apaga o que você criou. Dois caminhos aparecem o tempo todo: usar um volume Docker ou mapear uma pasta local. Se quiser o jeito mais simples, com volume gerenciado pelo próprio Docker, rode docker volume create n8n_data. Esse volume será ligado à pasta interna /home/node/.n8n, onde o n8n grava os dados.

Se preferir trabalhar com diretório local, crie uma pasta como ~/n8n, ~/n8n_data ou ~/n8n-data, de acordo com a organização que você quiser usar. Em VPS Linux, é comum montar um projeto com mkdir ~/n8n && cd ~/n8n e, dentro dele, uma subpasta como n8n_data. Em alguns ambientes, faz diferença ajustar a posse da pasta com sudo chown -R 1000:1000 n8n_data para evitar erro de permissão quando o contêiner tentar gravar os arquivos.

Rode o n8n com um único comando Docker

Se a ideia é testar rápido, você inicia o n8n sem Compose, usando só o comando docker run. Primeiro, crie o volume persistente. Em seguida, rode o contêiner com a porta 5678 exposta e as variáveis de ambiente principais. Um exemplo funcional é:

docker run -it --rm --name n8n -p 5678:5678 -e GENERIC_TIMEZONE="America/Sao_Paulo" -e TZ="America/Sao_Paulo" -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true -e N8N_RUNNERS_ENABLED=true -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

Nesse comando, -p 5678:5678 libera o acesso pelo navegador, -v n8n_data:/home/node/.n8n mantém os dados salvos e GENERIC_TIMEZONE define o fuso usado por nós de agendamento. A variável TZ ajusta o fuso do sistema dentro do contêiner. Já N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true aplica permissões mais rígidas no arquivo de configuração. Na primeira execução, o Docker baixa a imagem; quando o processo termina, o acesso fica disponível em http://localhost:5678.

Acesse o n8n no navegador e confira se abriu

Com o contêiner em execução, abra o navegador e digite http://localhost:5678 no computador local. Em VPS ou servidor remoto, o endereço passa a ser http://IP_DO_SERVIDOR:5678. Se a configuração estiver correta, a interface web do n8n aparece. Em alguns fluxos de instalação, a primeira tela pede a criação da conta de proprietário da instância. Em outros cenários, se você ativou autenticação básica no contêiner, o navegador solicita usuário e senha antes de mostrar a interface.

Se a página não abrir, verifique três pontos: se o contêiner está rodando, se a porta 5678 está livre na máquina e se o firewall do servidor permite a conexão. Para checar o estado dos contêineres, use docker ps, docker ps -a ou, no Compose, docker compose ps. Em instalações sem SSL, pode surgir um aviso relacionado a cookies seguros. Isso não indica falha do n8n; mostra que a camada HTTPS ainda não foi configurada, algo esperado em acesso simples por HTTP local ou direto por IP.

Use Docker Compose para deixar a instalação mais fácil de manter

Para uso contínuo, o caminho mais organizado é criar um arquivo docker-compose.yml ou compose.yaml. Assim, você não precisa repetir um comando grande toda vez. Um exemplo simples inclui a imagem oficial, reinício automático, porta 5678, volume persistente e variáveis de ambiente. O conteúdo básico pode seguir esta estrutura: versão 3.8, serviço n8n, imagem n8nio/n8n, restart: unless-stopped, porta 5678:5678, volume n8n_data:/home/node/.n8n e variáveis como GENERIC_TIMEZONE=America/Sao_Paulo e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true.

Também existe a variação que usa uma pasta local, como ~/.n8n:/home/node/.n8n ou ./n8n_data:/home/node/.n8n. Se quiser, você adiciona autenticação básica com N8N_BASIC_AUTH_ACTIVE=true, N8N_BASIC_AUTH_USER e N8N_BASIC_AUTH_PASSWORD. Em arquivos mais completos, aparecem ainda N8N_HOST, N8N_PORT=5678, N8N_PROTOCOL=http ou https e NODE_ENV=production. Com isso, a configuração do n8n fica centralizada em um único arquivo e o gerenciamento do ambiente, migração e atualização ficam concentrados no Compose.

Inicie e pare o n8n com os comandos do Compose

Depois de salvar o arquivo Compose na pasta do projeto, abra o terminal exatamente nesse diretório e suba a aplicação em segundo plano. Dependendo do ambiente, o comando usado é docker-compose up -d ou docker compose up -d. O parâmetro -d deixa o contêiner rodando em segundo plano, sem travar o terminal. Na primeira subida, o Docker baixa a imagem do n8n; na sequência, cria e inicia o serviço automaticamente. Para confirmar o status, rode docker compose ps ou docker-compose ps.

Para parar o ambiente, use docker-compose down ou docker compose down. Se a configuração tiver restart: unless-stopped, o n8n volta sozinho após reinício do Docker, algo particularmente útil em servidores. Algumas pessoas ainda criam um Makefile com atalhos como make up, make down, make restart e make logs, mas isso fica como extra. O ponto central é ter um arquivo Compose salvo e usar sempre os comandos de subir, parar e inspecionar no mesmo diretório onde o arquivo está.

Ative login por usuário e senha se o n8n ficar exposto

Se você vai acessar o n8n fora do seu computador, principalmente em VPS, faz sentido ativar uma camada de proteção com autenticação básica. Isso é feito no arquivo Compose adicionando N8N_BASIC_AUTH_ACTIVE=true, N8N_BASIC_AUTH_USER e N8N_BASIC_AUTH_PASSWORD. Também há exemplos antigos com nomes sem sublinhado, mas a forma usada com N8N_BASIC_AUTH_... é a configuração mais clara para esse cenário. Depois de salvar o arquivo, reinicie o serviço com docker compose up -d para aplicar as mudanças.

Se você preferir não deixar as credenciais escritas diretamente no docker-compose.yml, crie um arquivo .env no mesmo diretório do projeto e puxe as variáveis dali. Isso ajuda quando você também define domínio, subdomínio e outras configurações do ambiente. Em acesso local, essa proteção é opcional. Já em servidor público, expor o painel sem autenticação aumenta muito o risco. O mínimo é exigir login e senha; em cenário de produção, essa camada entra junto com HTTPS e proxy reverso.

Configure HTTPS e domínio no servidor, se quiser usar em produção

Em VPS ou servidor Linux, o uso de HTTPS costuma ficar na mão de um proxy reverso. Um caminho bem documentado é instalar o NGINX, emitir certificado com Certbot e encaminhar o tráfego da porta 443 para a porta 5678 do n8n. Nesse fluxo, você instala o NGINX com sudo apt install nginx -y, para o serviço temporariamente com sudo systemctl stop nginx, instala o Certbot com sudo apt install certbot -y e solicita o certificado com sudo certbot certonly --standalone -d seu-dominio. Depois disso, volta a iniciar o NGINX com sudo systemctl start nginx.

Outra opção é usar Traefik junto do Docker Compose. Nesse caso, o Compose sobe dois contêineres: um do n8n e outro do Traefik, que cuida do TLS/SSL e do roteamento. A configuração costuma incluir variáveis como DOMAIN_NAME, SUBDOMAIN, SSL_EMAIL, N8N_PROTOCOL=https e WEBHOOK_URL. Também é comum mapear o n8n internamente como 127.0.0.1:5678:5678, deixando o acesso público apenas via HTTPS pelo proxy. Isso corta a exposição direta da porta 5678 na internet.