Guia do Dev — Ambiente Nuvio (dev.nuvio.com.br)

Público: desenvolvedores que estão migrando do ambiente local no notebook para o servidor de desenvolvimento compartilhado da Nuvio.

O que muda: em vez de rodar PHP/Node/Docker no seu notebook, você edita código remotamente no servidor dev.nuvio.com.br. Os containers (Laravel/Angular/nginx) rodam lá; você acessa o site em https://<seu-projeto>-<seu-login>.dev.nuvio.com.br.

O que NÃO muda: seu editor é o mesmo (VSCode), você continua commitando com git, continua rodando testes. Só a execução dos containers saiu do seu notebook.

Índice

  1. Visão geral
  2. Primeiro login no painel
  3. Dispositivos confiáveis
  4. Gerando sua chave SSH
  5. Cadastrando a chave SSH no painel
  6. Conectando via terminal SSH
  7. Editando código com VSCode Remote-SSH
  8. Criando um novo workspace
  9. Importando um workspace existente
  10. Operando o workspace no dia a dia
  11. Rodando comandos dentro dos containers
  12. Ciclo de desenvolvimento (edit → build → preview)
  13. Boas práticas e limites
  14. Dúvidas frequentes

1. Visão geral

Os 3 endereços que você precisa conhecer

URL Pra quê
https://painel.dev.nuvio.com.br Painel web — criar/operar workspaces, ver logs, gerenciar sua conta
dev.nuvio.com.br (porta 2200) Acesso SSH ao servidor — edição de código, terminal
https://<slug>-<seu-login>.dev.nuvio.com.br URL do seu workspace rodando (preview do site)

O modelo mental

Seu notebook (VSCode)  ──SSH──▶  Servidor dev.nuvio.com.br
                                  ├── /home/<seu-login>/workspaces/<slug>/   ← seu código
                                  └── containers Docker (app/web/db)
                                      rodam aqui e servem o site via Traefik
  • Código fica em /home/<seu-login>/workspaces/<slug>/ (sua pasta pessoal no servidor).
  • Containers (Laravel FPM, nginx, Angular build) rodam no servidor, não no seu notebook.
  • Painel é a UI web pra ligar/desligar containers, ver logs, build de produção, etc.

Termos

  • Workspace = pasta com um projeto (ex: crm-web, faturamento-api). Cada workspace tem seu próprio compose.yaml e sobe 1+ containers.
  • Slug técnico = nome curto do projeto em lowercase (ex: crm, faturamento). O painel acrescenta sua camada (web/api/admin/etc.) automaticamente.
  • Template = pacote com compose.yaml/nginx.conf/CLAUDE.md padronizado da Nuvio (angular, laravel, nginx-static).
  • Operation = botão no card do workspace que roda um comando dentro do container (ex: "Build produção", "Composer install", "Migrate").

2. Primeiro login no painel

O login é por e-mail + código (sem senha). Cada login que você abrir envia um código de 6 dígitos pro seu e-mail cadastrado.

Passo a passo

  1. Abra https://painel.dev.nuvio.com.br no navegador.
  2. Digite seu e-mail corporativo (o que você informou ao time de DevOps). Clique Continuar.
  3. Vá no seu e-mail. Você vai receber uma mensagem com o assunto "Código de acesso Nuvio" contendo 6 dígitos.
  4. Volte ao painel e digite o código. Clique Entrar.
  5. Se for o primeiro acesso desse dispositivo, marque "Confiar neste dispositivo" antes de entrar (veja seção 3).

Se o código não chegar

  • Confere caixa de spam / lixo eletrônico.
  • Avisa o time de DevOps — o e-mail cadastrado pode estar errado.

3. Dispositivos confiáveis

Por que existe: digitar código do e-mail todo dia é chato. "Confiar neste dispositivo" guarda um cookie seguro no seu navegador por 7 dias e pula a etapa do código.

Regras

  • Dura 7 dias. Após isso, o painel pede código de novo.
  • Só funciona no mesmo navegador + máquina. Trocou de navegador, pede código.
  • Se alguém pegar seu notebook, pode entrar sem código enquanto a confiança for válida.
  • Nunca marque "confiar" em máquina pública ou emprestada.

Onde gerenciar / revogar

Painel → Minha conta → Dispositivos confiáveis

Você vê a lista dos seus dispositivos ativos (SO + navegador + IP + última atividade). Pra remover a confiança imediatamente, clique no botão de Revogar do dispositivo. Especialmente útil se:

  • Perdeu/trocou o notebook
  • Teve o notebook roubado
  • Usou um pc compartilhado e esqueceu de deslogar

4. Gerando sua chave SSH

SSH é como o git funciona com GitHub/GitLab — você gera uma chave par (privada no seu notebook, pública no servidor). Depois o servidor te reconhece sem pedir senha.

Se você nunca gerou uma chave SSH

Linux / Mac (terminal):

ssh-keygen -t ed25519 -C "seu-email@nuvio.com.br"

Windows:

  • Opção 1 (recomendada): instala o Git for Windows, abre o Git Bash, e roda o mesmo comando acima.
  • Opção 2: abre o PowerShell e roda o mesmo comando (funciona a partir do Windows 10).

Durante a geração o ssh-keygen vai perguntar:

  1. "Enter file in which to save the key" — aperta Enter (aceita o padrão ~/.ssh/id_ed25519).
  2. "Enter passphrase" — você pode:
    • Deixar vazio (Enter) — SSH não vai pedir senha, mas se alguém acessar seu notebook, usa a chave de graça.
    • Pôr uma senha — mais seguro; você digita essa senha na 1ª conexão e o ssh-agent do SO guarda enquanto o notebook fica ligado.

Resultado — 2 arquivos em ~/.ssh/:

  • id_ed25519 → sua chave privada. NUNCA compartilhe, nunca commita, nunca envia pra ninguém.
  • id_ed25519.pub → sua chave pública. Esta é a que vai no painel.

Se você já tem uma chave SSH (ex: usa o GitHub)

Pode reusar a mesma. Ou gerar uma nova exclusiva pra trabalho — fica a gosto.

Como ver a chave pública pra copiar

Linux / Mac:

cat ~/.ssh/id_ed25519.pub

Windows (Git Bash / PowerShell):

cat ~/.ssh/id_ed25519.pub
# ou no PowerShell:
type $HOME\.ssh\id_ed25519.pub

Vai aparecer algo assim (1 linha só, longa):

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIB... seu-email@nuvio.com.br

Copia a linha inteira (com ssh-ed25519 no começo e seu e-mail no fim).

5. Cadastrando a chave SSH no painel

  1. Painel → Minha conta → seção Chaves SSH autorizadas.
  2. Clica em Adicionar chave.
  3. No campo Chave pública, cola a linha que você copiou do .pub.
  4. Campo Rótulo: um nome pra você lembrar qual máquina (ex: notebook-pessoal, macbook-trabalho).
  5. Clica em Adicionar.
  6. O painel vai pedir um código de segurança (mandado pro seu e-mail) — é confirmação extra pra alterações sensíveis. Cola o código.

Pronto. Sua chave agora está em /home/<seu-login>/.ssh/authorized_keys no servidor. Pode fechar o painel e testar o SSH.

Adicionando mais chaves

Pode ter quantas precisar (um notebook, um PC desktop, etc.). Cada uma com rótulo próprio. Pra remover (ex: notebook roubado): painel → lista → Remover → confirma código.

6. Conectando via terminal SSH

Assumindo que seu login Linux é {seu-login} (ex: grusso):

ssh -p 2200 {seu-login}@dev.nuvio.com.br

A porta SSH do servidor é 2200 (não a 22 default). Sem o -p 2200 a conexão trava.

Primeira conexão — SSH pergunta:

The authenticity of host 'dev.nuvio.com.br' can't be established.
...
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Digita yes + Enter. Ele guarda a assinatura do servidor e não pergunta de novo.

Segunda conexão em diante — entra direto. Você vê algo como:

Last login: Tue Apr 22 01:42:30 2026 from 187.x.x.x
{seu-login}@dev:~$

Atalho: entrada sem digitar @dev.nuvio.com.br

Cria/edita ~/.ssh/config no seu notebook:

Host nuvio
    HostName dev.nuvio.com.br
    Port 2200
    User {seu-login}
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 60

Depois conecta com:

ssh nuvio

Pastas importantes no seu home

/home/{seu-login}/
├── workspaces/               ← seus projetos ficam aqui (1 pasta por workspace)
│   ├── crm-web/
│   ├── faturamento-api/
│   └── ...
├── .ssh/authorized_keys      ← suas chaves SSH (gerenciadas pelo painel)
└── .gitconfig                ← configure com seu nome + e-mail

Configure o git na 1ª vez

git config --global user.name "Seu Nome Completo"
git config --global user.email "seu-email@nuvio.com.br"

7. Editando código com VSCode Remote-SSH

Você edita no VSCode da sua máquina, mas os arquivos vivem no servidor. A mágica é a extensão oficial Remote - SSH.

Instalação (1ª vez)

  1. VSCode → aba Extensions (Ctrl+Shift+X).
  2. Instala Remote - SSH (publisher: Microsoft).

Conectando

  1. Ctrl+Shift+P → digita Remote-SSH: Connect to Host.
  2. Se já criou o ~/.ssh/config com Host nuvio (seção 6), escolhe nuvio na lista. Senão, escolhe Add New SSH Host e digita ssh -p 2200 {seu-login}@dev.nuvio.com.br.
  3. O VSCode abre nova janela. No canto inferior esquerdo aparece SSH: nuvio (ou dev.nuvio.com.br).
  4. File → Open Folder → digita /home/{seu-login}/workspaces/<slug> → Enter.

Daqui em diante: tudo que você edita grava direto no servidor. Git também roda no servidor (é onde o .git vive). Terminal integrado (Ctrl+`) já é um shell SSH remoto.

Extensões no servidor vs local

Algumas extensões rodam no lado local (ex: temas), outras precisam ser instaladas no servidor (ex: Prettier, ESLint, linters PHP). Quando você abrir um workspace remoto pela primeira vez, o VSCode pergunta se quer instalar suas extensões no servidor — diga sim.

8. Criando um novo workspace

Pra começar um projeto do zero usando um template Nuvio:

  1. Painel → Meus workspaces → botão Novo workspace (topo direito).
  2. Escolhe o Template (angular / laravel / nginx-static).
  3. Preenche os campos:
    • Título do projeto: nome humano (ex: Faturamento)
    • Slug técnico: nome curto sem hífens — só letras minúsculas e números, começando por letra (ex: faturamento, paracuidar). O painel compõe o slug final juntando com a camada (ex: paracuidar-web).
    • Camada: api, web, admin, etc. (se aplicável ao template)
    • URL da API backend (Angular): /api por default, ou URL específica
  4. Clica Criar.
  5. A criação é async — demora 2 a 5 min e você vê o log em tempo real na tela.

O que acontece por baixo

  • O painel cria a pasta /home/{seu-login}/workspaces/<slug>-<camada>/.
  • Renderiza compose.yaml, nginx.conf, CLAUDE.md, AGENTS.md etc. com seus dados.
  • Sobe os containers Docker (docker compose up -d).
  • Angular: roda create-nx-workspace + npm install + gera libs shared/* vazias.
  • Laravel: roda composer create-project laravel/laravel:^12 + composer require da stack padrão (Lighthouse GraphQL, Doctrine, JWT, etc.) + estrutura DDD + migrate.

Quando terminar, seu workspace aparece no card e você pode abrir a URL de preview.

9. Importando um workspace existente

Quando você já tem código (num repositório Git ou num .tar.gz / .zip):

  1. Painel → Meus workspaces → botão Importar workspace.
  2. Wizard em 5 passos:

Passo 1 — Origem

  • Pasta local: código já está em ~/workspaces/<slug>/ (você copiou via SSH/SCP).
  • Repositório Git: clona do GitHub/GitLab usando sua Credencial Git (próxima seção).
  • Arquivo comprimido: upload de .tar.gz / .zip (máx 500 MB).

Passo 2 — Dados

  • Slug + camada + URL do repo / arquivo.

Passo 3 — Inspeção

O painel clona/extrai o código em uma área temporária (staging) e mostra:

  • Número de arquivos, tamanho total
  • Linguagens detectadas
  • Arquivos-chave encontrados (package.json, composer.json, nx.json, etc.)
  • Template recomendado com badge "Recomendado"

Passo 4 — Template + validação

  • Seleciona o template (ou "Nenhum" pra só adotar sem aplicar infra padronizada).
  • Painel valida se o código-fonte bate com o template escolhido:
    • ✓ package.json com @angular/core encontrado
    • ✓ nx.json encontrado
    • ✗ etc.
  • Se alguma validação falhar (✗), não dá pra prosseguir — precisa corrigir o código ou escolher outro template.

Passo 4b — Ajustes recomendados

Se o código vem de outro projeto, pode ter inconsistências (nome no project.json, baseHref antigo, apiUrl de outro ambiente, paths absolutos no CSS). O painel detecta e oferece correções automáticas. Cada ajuste tem um checkbox. Por default vêm marcados.

Exemplos (Angular):

  • baseHref do project.json deve ser "/" — Atual: /fidelidade-frontend/ → Recomendado: /
  • Nome do projeto em project.json — Atual: fidelidade-frontend → Recomendado: <seu-slug>
  • outputPath do build em project.json — ajusta pra dist/apps/<seu-slug>
  • URL da API backend (environment.ts) — campo editável: confirma ou digita novo valor
  • Paths absolutos em X arquivo(s) usam o baseHref antigo — reescreve url(/<old>/) → url(/)

Atenção ao digitar no campo da apiUrl: depois de digitar, clica em outro campo (perde o foco) antes de clicar em Importar — isso garante que o valor seja enviado ao backend.

Passo 5 — Pronto

  • Clica Importar + aplicar template.
  • Painel move o staging pro seu home, aplica o template, aplica os ajustes marcados, roda post_import (npm install / composer install), reinicia containers.
  • Resultado: workspace pronto no card.

Credencial Git (obrigatório pra origem "Repositório Git")

Antes de importar de um repo Git, cadastre a credencial:

  1. Painel → Minha conta → Credenciais Git.
  2. Provider: GitHub / GitLab / Bitbucket / Gitea.
  3. Username: seu usuário no provider (no GitLab pode ser "oauth2").
  4. Token: Personal Access Token com escopo read_repository (GitLab) ou repo:read (GitHub). Gera no próprio provider (GitHub: Settings → Developer Settings → Tokens).

10. Operando o workspace no dia a dia

Cada workspace vira um card em Meus workspaces, com:

Ações de ciclo de vida

Botão O que faz
Subir docker compose up -d — sobe todos os containers
Parar docker compose stop — para, mas mantém volumes/estado
Derrubar docker compose down -v — para + remove containers + volumes. Destrutivo
Rebuild docker compose up -d --build — rebuilda as imagens locais
Remover Apaga a pasta inteira. Irrecuperável

Ações por container individual

Na tabela de containers (expande "Containers"):

  • Logs — abre janela com log live (atualiza a cada 3s)
  • Stats — abre janela com CPU / Memória / Rede / IO / PIDs + tabela de processos
  • Start / Stop / Restart — só esse container, sem mexer nos outros

Operações do template

Expande Operações do template — cada template tem um conjunto específico:

Angular:

  • NPM install / Build (produção) / Build (dev) / Lint / Test (vitest) / Reset cache Nx

Laravel:

  • Composer install / Composer update / Migrate SQLite / Rodar testes / Formatar (Pint)
  • Composer require — especial: você digita vendor/pacote em uma modal e ele instala dentro do container (ex: nuwave/lighthouse webonyx/graphql-php, separados por espaço)

Toda operação roda assíncrona e mostra log live embaixo do card.

Log live

Quando clicar qualquer ação async, aparece embaixo do card um painel com log em tempo real da execução (via WebSocket). Ao fim, mostra "✓ Concluído em Xs" ou "✗ Falhou". Botão Fechar dispensa o painel (a ação continua em background se estiver em execução).

11. Rodando comandos dentro dos containers

Às vezes você precisa rodar um comando ad-hoc que não é uma operation do template:

Via painel

  • Composer require (Laravel): botão dedicado no card (explicado acima).

Via SSH no servidor

Conecta no servidor via SSH e entra na pasta do workspace:

cd ~/workspaces/crm-web
docker compose exec app bash        # shell dentro do container app
# dentro do container:
php artisan route:list
composer dump-autoload
exit

Pra comando pontual sem abrir shell:

docker compose exec app composer require nuwave/lighthouse
docker compose exec build npx nx g @nx/angular:library shared/feature-x

Via VSCode Remote-SSH

O terminal integrado (Ctrl+) do VSCode Remote abre um shell direto no servidor, na pasta do workspace. Então você roda docker compose exec ...` direto sem precisar abrir outro terminal.

12. Ciclo de desenvolvimento (edit → build → preview)

Angular

  1. Edita arquivos em src/ ou libs/ no VSCode.
  2. Roda docker compose exec build npx nx serve (dev server com HMR na porta 4200) OU clica Build (dev) no painel pra um build único.
  3. Abre https://<seu-slug>-<seu-login>.dev.nuvio.com.br no navegador.
  4. Pra subir em "produção" (assets otimizados): painel → Build (produção).

Laravel

  1. Edita arquivos em app/, routes/, resources/, etc.
  2. Não precisa buildar — PHP recarrega sozinho. Nginx + FPM já servem.
  3. Abre https://<seu-slug>-<seu-login>.dev.nuvio.com.br.
  4. Pra rodar migration / seed: painel → Migrate SQLite ou via SSH.

Trabalhando com Git

O .git do projeto vive no servidor (não no seu notebook). Você faz commit/push direto lá:

cd ~/workspaces/crm-web
git status
git add .
git commit -m "feat: X"
git push origin main

Se preferir, o VSCode Remote-SSH também tem aba Source Control funcionando normal — clica, stage, commit, push como em qualquer projeto local.

13. Boas práticas e limites

O que NÃO fazer

  • ❌ Rodar MariaDB/PostgreSQL dentro do seu workspace — o banco vive em workspace DB dedicado (pergunta pra DevOps como se conectar ao DB do seu projeto).
  • ❌ Editar compose.yaml/nginx.conf/Dockerfile sem avisar o DevOps — são de infra padronizada. Mudança ad-hoc dificulta manutenção.
  • ❌ Deixar Derrubar apertado sem avaliar — destrói volumes (SQLite do seu projeto pode sumir dependendo do setup).
  • ❌ Commitar .env, node_modules/, vendor/, dist/ — são gerados ou sensíveis.

O que É obrigatório

  • ✅ Ler o CLAUDE.md do workspace — cada template tem convenções próprias (DDD no Laravel, OnPush + PrimeNG no Angular, etc.). Respeitar essas convenções.
  • ✅ Rodar ./vendor/bin/pint (Laravel) ou npx nx lint (Angular) antes de cada commit.
  • ✅ Colocar seu commit em inglês ou pt-BR, mas conciso.
  • ✅ Usar as operations do painel pra composer/npm/migrate — evita divergência de versões.

Limites de recurso

  • Disco: cada workspace vive no seu home. Fique de olho no indicador "ocupa" no card. Limpe com nx reset, rm -rf node_modules (+ reinstalar depois).
  • CPU/RAM: o servidor é compartilhado. Evite rodar builds pesados em paralelo com os colegas.
  • Portas: só containers com label traefik.enable=true são acessíveis externamente. Nada de ports: 8080:80 no compose — use Traefik.

14. Dúvidas frequentes

P: Esqueci meu login Linux. R: Painel → Minha conta → Dados da conta (mostra seu login abaixo do seu nome).

P: SSH pede senha em vez de usar a chave. R: (1) Verifica se cadastrou a chave pública correta (veja seção 5). (2) No SSH client, adiciona -v pra debug: ssh -v -p 2200 {seulogin}@dev.nuvio.com.br. (3) No Windows Git Bash, às vezes precisa ssh-add ~/.ssh/id_ed25519 antes da primeira conexão.

P: O site dá 404. R: (1) Painel → card do workspace: clica Logs nos containers pra ver o erro do nginx. (2) Se for Angular, roda Build (produção) se nunca rodou. (3) Se mudou baseHref ou outputPath, talvez precise docker restart <container-web> pra nginx recarregar.

P: Meus containers somem depois de umas horas. R: Containers com restart: unless-stopped (padrão do template) sobrevivem a restart do host. Se sumiu, verifica se alguém rodou Derrubar. Card sempre mostra o estado atual.

P: Quero ver a configuração de um template (ex: quais pacotes PHP vêm). R: Painel → Templates → clica no template → vê lista de extensões PHP, arquivos renderizados, operações, conteúdo bruto dos .j2.

P: Como funcionam os "Ajustes recomendados" no import? R: O painel lê seu código-fonte e compara com o que o template espera. Se achar divergência conhecida (ex: baseHref errado, nome do projeto diferente do slug), oferece corrigir automaticamente no import. Você escolhe quais aplicar via checkbox.

P: Dispositivo confiável expirou antes de 7 dias. R: Navegador pode ter limpado cookies (private/incognito). Faz o fluxo de código de e-mail de novo e marca "confiar".

P: Quero revogar acesso de uma máquina que perdi. R: Painel → Minha conta → Chaves SSH (remove a chave dessa máquina) + Dispositivos confiáveis (revoga o cookie da sessão web). Dois lugares.

P: Onde vejo o que está sendo auditado no painel? R: Só admins veem — menu Administração → Auditoria. Pra devs comuns: tudo que você faz via painel (install SSH, import, build, etc.) é registrado e pode ser auditado.

P: Preciso de algo não listado nas operations do template. R: SSH + docker compose exec (seção 11). Se for algo que usa rotina (ex: composer require de pacotes novos recorrentes), use o botão dedicado no painel (Laravel) ou pede pro DevOps adicionar como operation.

Precisa de ajuda?

  • Bug no painel / servidor: avisa o DevOps.
  • Dúvida sobre arquitetura / convenção de código: consulta o CLAUDE.md do workspace e/ou os docs em /srv/docs/.
  • Fora do escopo deste guia: pergunta no canal do time.

Última atualização: 2026-04-22