Base de Conhecimento

Activepieces na VPS: automação própria no seu servidor

  • activepieces, automação, docker, docker compose, nginx, vps
  • Usuários acharam útil: 0

Aprenda a instalar o Activepieces na sua VPS com Docker Compose: requisitos, variáveis essenciais, HTTPS com Nginx, primeiro administrador, backup e atualização.

Por Redação Eleven Host · @robson.direitodigital · 4 de novembro de 2026 · 10 min de leitura

Arte da Eleven Host: janela de terminal com o título: Activepieces na VPS: automação própria no seu servidor

Capa da Redação Eleven Host para o guia: Activepieces na VPS: automação própria no seu servidor Arte: Eleven Host

Activepieces na VPS: o Activepieces ajuda equipes a criar fluxos de automação com IA e agentes de IA, e você pode instalá-lo no seu próprio servidor. Veja requisitos, instalação com Docker Compose, HTTPS, primeiro acesso, backup e atualização.

Em 04/11/2026, a versão mais recente no GitHub é a 0.92.3-hotfix.2, publicada em 28/10/2026. Se você está conhecendo o assunto, o guia O que é servidor VPS explica o básico do servidor onde o Activepieces vai ficar.

O que é o Activepieces

A documentação diz que o Activepieces ajuda equipes a criar fluxos de automação com IA e agentes de IA. O README do projeto o descreve como uma automação com IA completa, extensível por um framework de peças (pieces) escrito em TypeScript, e se apresenta como uma alternativa de código aberto ao Zapier. O mesmo README fala em um projeto feito para ser hospedado por você, com controle sobre os seus dados.

Na prática, você liga serviços por meio das peças. Consulte a lista de peças no site do projeto para ver se o serviço que você usa está lá.

A licença tem partes. Segundo a documentação, o núcleo do Activepieces é de código aberto sob a licença MIT. Os recursos das edições enterprise e cloud, que ficam em pastas separadas do repositório, usam uma licença comercial, e usá-los numa instalação própria exige uma licença da Activepieces.

Requisitos do Activepieces

O guia de Docker Compose pede pelo menos 2 vCPU e 4 GB de RAM. Também exige o Docker Compose v2: a documentação avisa que o antigo comando docker-compose, com hífen, não funciona. Confira a sua versão com:

docker compose version

Para o caminho manual abaixo, você também precisa do git e do openssl. O script de preparação usa o openssl para gerar as senhas e chaves.

Que plano de VPS cabe no seu orçamento? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver as VPS

Duas formas de instalar

A documentação apresenta duas opções. A recomendada por ela é o Docker Compose com PostgreSQL e Redis. A outra é um contêiner único com banco embutido (PGlite), que ela trata como opção para teste e uso leve. Esse contêiner único, segundo a documentação, não escala, não pode ser migrado para a edição Enterprise e, para sair dele, é preciso recomeçar do zero. Para produção, a própria documentação manda usar PostgreSQL e Redis.

Por isso, o restante do guia usa o Docker Compose. Nos dois casos, a documentação lembra que, em produção, o AP_FRONTEND_URL deve apontar para o seu domínio de verdade.

Instalar com Docker Compose e PostgreSQL

O Compose do projeto sobe quatro contêineres: app, worker, postgres e redis. A aplicação responde na porta 8080 do servidor. Para o caminho manual, baixe o repositório:

git clone --depth 1 https://github.com/activepieces/activepieces.git

cd activepieces

Depois, rode o script de preparação. Segundo a documentação, ele copia o .env.example para .env e preenche as senhas e chaves:

sh tools/deploy.sh

Confira se as três variáveis secretas ficaram com valor:

grep -E '^(AP_ENCRYPTION_KEY|AP_JWT_SECRET|AP_POSTGRES_PASSWORD)=' .env

A documentação é direta: cada uma delas precisa ter valor. Se alguma estiver vazia, instale o openssl e rode o script de novo.

Antes de subir, abra o arquivo .env e defina o endereço público, como no exemplo abaixo, com um domínio fictício:

AP_FRONTEND_URL=https://automacao.exemplo.com

Agora suba os serviços e acompanhe os logs:

docker compose -p activepieces up -d

docker compose -p activepieces logs -f app

docker compose -p activepieces logs -f worker

Atenção: a porta 8080 fica publicada no servidor e o primeiro cadastro vira administrador. Crie a sua conta logo, como explica a seção Primeiro acesso, e não divulgue o endereço antes disso.

Um detalhe da documentação: o Compose do repositório fixa a imagem numa versão específica (a 0.92.2 no ramo principal, enquanto a mais recente é a 0.92.3-hotfix.2) e define 5 réplicas do worker, mais do que uma máquina pequena precisa. Quem atualiza precisa trocar a tag da imagem, e recomendamos ajustar o número de réplicas ao tamanho da sua VPS.

Variáveis de ambiente essenciais

A documentação marca algumas variáveis como obrigatórias para uma instalação própria em produção. O script tools/deploy.sh cuida de gerar as chaves, mas vale saber o que cada uma faz:

  • AP_FRONTEND_URL: o endereço público, usado para montar as URLs de redirecionamento e de webhook. Terceiros precisam alcançá-lo para que webhooks e gatilhos de aplicativos funcionem;
  • AP_ENCRYPTION_KEY: a chave hexadecimal que criptografa as conexões salvas. A documentação mostra como gerar uma com openssl rand -hex 16;
  • AP_JWT_SECRET: a chave que assina os tokens de sessão (JWT), gerada com openssl rand -hex 32;
  • AP_POSTGRES_PASSWORD: a senha do PostgreSQL. Quando você define AP_POSTGRES_URL, os campos separados do banco são ignorados.

Se a porta 8080 já estiver ocupada, a documentação manda trocar a variável AP_HOST_PORT no .env, e não a AP_PORT. Se aparecerem mensagens de erro de conexão do Socket.IO no worker, a documentação explica que o AP_FRONTEND_URL do worker não resolve dentro do contêiner: nesse caso, use o nome do serviço, http://app, no ambiente do worker.

Modo de execução dos fluxos

A variável AP_EXECUTION_MODE define o isolamento da execução. O padrão é UNSANDBOXED: o motor roda como um processo comum, com limite de memória. A documentação indica esse modo para quem usa o Activepieces com uma equipe só.

Para ambientes enterprise, ela recomenda SANDBOX_CODE_ONLY, que isola cada passo de código num contexto V8 próprio e roda sem contêiner privilegiado. Já os modos SANDBOX_PROCESS e SANDBOX_CODE_AND_PROCESS exigem que o worker tenha a capacidade CAP_SYS_ADMIN, ou seja, um contêiner privilegiado. A documentação avisa que um worker privilegiado não deve dividir o nó com cargas de trabalho sem relação, e nós não recomendamos esse modo numa VPS que roda outras coisas.

Outro ponto: a combinação AP_EDITION=ee com UNSANDBOXED faz o servidor recusar a inicialização, e a documentação cita isso como causa comum de o app reiniciar sem parar. Se você não usa a edição Enterprise, não precisa dessa variável. Sem ela, você fica na edição Community, e a documentação avisa que, nesse caso, não será possível ativar uma chave de licença depois.

HTTPS com o Nginx

A documentação ensina a terminar o TLS com um proxy reverso Nginx, para quem gerencia os próprios certificados. Ela parte do princípio de que você já tem um certificado para o domínio, emitido pela Cloudflare ou gerado com Let's Encrypt ou Certbot, e manda colocar os arquivos em /etc/key.pem e /etc/cert.pem. Os comandos são:

sudo apt-get install nginx

sudo nano /etc/nginx/sites-available/default

sudo systemctl restart nginx

No arquivo, a documentação usa return 301 https://$server_name$request_uri; para redirecionar o HTTP e proxy_pass http://localhost:8080; para encaminhar ao Activepieces. Um exemplo mínimo de configuração, a partir dessas duas linhas, com domínio fictício (teste antes de usar):

server {

listen 80;

server_name automacao.exemplo.com;

return 301 https://$server_name$request_uri;

}

server {

listen 443 ssl;

server_name automacao.exemplo.com;

ssl_certificate /etc/cert.pem;

ssl_certificate_key /etc/key.pem;

location / {

proxy_pass http://localhost:8080;

}

}

Adapte o exemplo e compare com a página de SSL da documentação do Activepieces. Depois de reiniciar o Nginx, abra o domínio: a documentação diz que você deve ver a aplicação rodando com SSL. Confirme também que o AP_FRONTEND_URL do .env usa o endereço https do domínio. Quem prefere gerenciar vários sites com uma interface gráfica pode ver o guia Nginx Proxy Manager.

Primeiro acesso ao Activepieces

Segundo a documentação, a primeira conta criada vira a administradora da plataforma, e não existe usuário ou senha padrão.

Crie a sua conta logo depois de subir

Como o primeiro cadastro vira administrador, quem abrir o endereço antes de você poderia assumir a plataforma. Recomendamos criar a sua conta assim que o serviço subir, antes de divulgar o endereço. Outra opção é acessar a primeira vez por um túnel SSH.

Guarde o arquivo .env: a documentação diz que os segredos são gravados nele e manda fazer backup. Sem a chave AP_ENCRYPTION_KEY, as conexões guardadas não podem ser descriptografadas, nem a partir de um backup completo do banco.

Telemetria

A documentação afirma que a análise de uso do produto não coleta informações pessoais. Para desligar essa análise, ela cita AP_TELEMETRY_ENABLED=false como valor inicial; depois da primeira leitura, a opção passa para a tela de administração (Account, Configurations, chave Product analytics).

Backup, atualização e volta de versão

Antes de atualizar, a documentação manda fazer o backup do banco. No Compose, o comando é este, que grava o arquivo backup.sql na pasta atual:

docker compose -p activepieces exec postgres pg_dump -U postgres activepieces > backup.sql

Leve o backup.sql e o .env para fora da VPS e trate os dois como dados sensíveis, pois sem a chave de criptografia o banco sozinho não recupera as suas conexões.

Para atualizar, a documentação indica o script de atualização do próprio projeto, que preserva o .env, os dados e as suas edições no Compose. Pelo caminho manual, como o Compose fixa a tag da imagem, o procedimento é trocar a tag de app e worker no docker-compose.yml pela versão mais recente da página de releases e subir de novo. Recomendamos esse caminho por causa do aviso da documentação sobre a tag fixa:

docker compose -p activepieces up -d

Se precisar voltar para uma versão anterior, o projeto traz um comando de rollback que reverte as migrações do banco. A documentação diz que boa parte das versões pode ser revertida sem problema e que as notas da versão avisam quando não for o caso. O exemplo dela, voltando da 0.78.0 para a 0.77.0, é este, depois de parar os serviços com docker compose -p activepieces down:

docker run --rm --env-file .env --entrypoint npm \

activepieces/activepieces:0.78.0 \

run rollback -- --to 0.77.0

Se houver migração que quebra a volta, a documentação acrescenta a opção --force. Em seguida, troque a imagem no docker-compose.yml pela versão antiga e suba com docker compose -p activepieces up -d.

Outras opções de automação

Se você quer comparar ferramentas de automação, a base de conhecimento tem o guia do Execute Command no n8n, sobre rodar comandos de shell dentro dos fluxos do n8n. Para publicar vários aplicativos no mesmo servidor, há o guia do Coolify na VPS.

Já comparou os planos de VPS pelo preço de entrada? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Conhecer as VPS

Perguntas frequentes

O Activepieces é gratuito?

O núcleo, chamado de Community Edition, é de código aberto sob a licença MIT. Os recursos enterprise ficam sob licença comercial, e usá-los numa instalação própria exige uma licença da Activepieces. A documentação diz que a plataforma roda no plano gratuito por padrão.

Qual versão do Activepieces instalar?

Em 04/11/2026, a mais recente no GitHub é a 0.92.3-hotfix.2, de 28/10/2026. As versões saem com frequência, então confira a página de releases antes de instalar.

Posso usar o contêiner único em produção?

A documentação diz que não. Esse modo usa banco embutido, não escala e não vira Enterprise. Para produção, ela manda usar PostgreSQL e Redis, como no Docker Compose.

O Activepieces precisa de um domínio?

Para o HTTPS com o Nginx, sim: o guia da documentação parte de um certificado para o seu domínio. Além disso, o AP_FRONTEND_URL precisa ser um endereço que terceiros consigam alcançar, para que webhooks e gatilhos funcionem.

Onde ficam as minhas conexões e senhas de serviços?

As conexões ficam criptografadas com a AP_ENCRYPTION_KEY. Guarde o .env com essa chave junto do backup do banco.

Esta resposta lhe foi útil?

Artigos Relacionados