Documentação de Instalação e Arquitetura

1. Visão Geral & Arquitetura

O CloudVTurb é uma solução completa de hospedagem e streaming adaptativo para VSLs (Video Sales Letters), criada para substituir ferramentas proprietárias (VTurb, PandaVideo, Vimeo) eliminando o custo recorrente por tráfego.

A plataforma opera sobre Node.js 20 LTS, banco relacional embarcado SQLite com WAL mode (garantindo concorrência massiva de leitura/escrita com zero latência de rede), transcodificação multi-bitrate via FFmpeg e entrega otimizada via HLS (HTTP Live Streaming).

2. Requisitos de Infraestrutura & Provedores VPS

Como o processamento de vídeos (FFmpeg) exige recursos de CPU e memória RAM durante o upload, a escolha do servidor é o passo mais importante para um ambiente veloz.

Especificações de Servidor

Provedores Recomendados (Links Diretos)

3. Deploy via Dokploy (Método Recomendado)

O Dokploy é um painel open-source moderno e leve para gerenciar containers Docker com SSL automático Traefik e deploy contínuo via GitHub.

Passo 1: Instale o Dokploy na sua VPS

Conecte-se na sua VPS via SSH e execute o comando oficial de instalação do Dokploy:

curl -sSL https://dokploy.com/install.sh | sh

Passo 2: Configure a Aplicação no Painel

1. Acesse o painel do Dokploy pelo endereço http://IP_DA_VPS:3000.
2. Crie um novo Projeto (ex: CloudVTurb).
3. Adicione um novo serviço do tipo Application.
4. Selecione o Source como Git e insira a URL do repositório:
   https://github.com/Gumballxnz/meu-vturb.git (Branch: main).
5. Na aba General, configure a porta do container para 4000.
6. Na aba Environment, adicione as variáveis de ambiente necessárias (veja a tabela na Seção 6).
7. Na aba Domains, configure os domínios da sua aplicação:
   • seudominio.com (Porta 4000)
   • dash.seudominio.com (Porta 4000)
   • player.seudominio.com (Porta 4000)
   • docs.seudominio.com (Porta 4000)
8. Clique em Deploy. O Dokploy fará o build da imagem Docker com Node 20 e FFmpeg automaticamente.

4. Deploy via Coolify

O Coolify é outra alternativa open-source conceituada para gerenciar aplicações em servidores próprios.

Comando oficial de instalação do Coolify em VPS limpa:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

Após a instalação, adicione uma nova aplicação conectando o repositório https://github.com/Gumballxnz/meu-vturb, defina os domínios FQDN e mapeie os volumes persistentes:

/opt/cloudvturb/data:/app/data
/opt/cloudvturb/videos:/app/videos

5. Deploy em VPS Crua (Docker & Docker Compose)

Se preferir rodar diretamente no sistema operacional sem painéis adicionais, execute a sequência abaixo em um terminal Ubuntu limpo:

# 1. Atualize o sistema operacional
sudo apt update && sudo apt upgrade -y

# 2. Instale dependencias essenciais
sudo apt install -y curl git ufw ffmpeg

# 3. Instale o Docker Engine oficial
curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh

# 4. Configure o firewall UFW
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 4000/tcp
sudo ufw --force enable

Em seguida, clone o código do repositório e configure as variáveis:

# 5. Clone o repositorio no diretorio de servicos
git clone https://github.com/Gumballxnz/meu-vturb.git /opt/cloudvturb
cd /opt/cloudvturb

# 6. Configure o arquivo .env
cp .env.example .env
nano .env

# 7. Inicie a aplicacao em background com Docker Compose
docker compose up -d --build

6. DNS & Regras Cloudflare

O gerenciamento de DNS pelo painel da Cloudflare é altamente recomendado pela proteção Anti-DDoS e roteamento global ultrarrápido.

Tabela de Apontamentos DNS Obrigatórios

7. Dicionário de Variáveis de Ambiente (.env)

Todas as credenciais sensíveis e domínios são controlados exclusivamente pelo arquivo .env.

Para gerar uma chave criptográfica forte para o seu JWT_SECRET, execute no terminal:

openssl rand -hex 64

8. Armazenamento Cloudflare R2 (Custo Zero de Egress)

O Cloudflare R2 é uma solução compatível com a API S3 da Amazon, com a vantagem decisiva de ter taxa zero de saída de dados.

Passo a Passo de Configuração

1. Acesse o Painel Cloudflare R2.
2. Clique em Create Bucket e atribua um nome (ex: meu-vturb-vsls).
3. No menu lateral direito do R2, clique em Manage R2 API Tokens e crie um token com permissão Object Read & Write.
4. Anote o Access Key ID e o Secret Access Key.
5. Acesse a aba Settings do bucket criado e ative Public Access ou adicione um subdomínio próprio (ex: cdn.seudominio.com).
6. No painel do CloudVTurb, acesse Configurações → Armazenamento, selecione Cloudflare R2 / S3 e salve os dados.

9. Login com Google OAuth

Para habilitar o botão de login social em 1 clique com contas Google:

1. Acesse o Google Cloud Console.
2. Crie um novo projeto ou selecione um existente.
3. Acesse APIs e Serviços → Credenciais e clique em Criar Credenciais → ID do cliente OAuth.
4. Tipo de aplicativo: Aplicativo da Web.
5. Em Origens JavaScript autorizadas, adicione os seus domínios:
   https://dash.seudominio.com
https://seudominio.com
6. Copie o Client ID gerado e adicione ao seu arquivo .env na variável GOOGLE_CLIENT_ID.

10. Como Incorporar o Player nas Suas Páginas

O player do CloudVTurb foi construído para funcionar com máxima fluidez e compatibilidade em qualquer construtor visual: Elementor, WordPress, Webflow, Leadlovers, ClickFunnels ou HTML puro.

Código Iframe Responsivo 16:9

<!-- Pre-carregamento rapido do player -->
<link rel="preconnect" href="https://player.seudominio.com">
<link rel="dns-prefetch" href="https://player.seudominio.com">

<!-- Container responsivo com proporcao 16:9 -->
<div style="position:relative;padding-bottom:56.25%;height:0;overflow:hidden;border-radius:12px;">
  <iframe src="https://player.seudominio.com/players/SEU_VIDEO_ID"
          style="position:absolute;top:0;left:0;width:100%;height:100%;border:0;"
          allow="autoplay; fullscreen"
          allowfullscreen></iframe>
</div>

11. Troubleshooting & FAQ

Como verificar os logs da aplicação

docker logs -f --tail 100 meu-vturb-app

Como atualizar a aplicação para a versão mais recente

cd /opt/cloudvturb
git pull origin main
docker compose up -d --build