uncloud

Gerenciamento de Cluster Uncloud

Referência para a CLI uc — uma plataforma descentralizada de self-hosting usando contêineres Docker, rede mesh WireGuard e proxy reverso Caddy.

Quando Ativar

Use esta skill ao trabalhar com clusters Uncloud, especialmente quando:

• Inicializando ou adicionando máquinas com uc machine
• Implantando serviços a partir de arquivos Compose com uc deploy
• Publicando portas HTTP, HTTPS, TCP ou UDP através do Uncloud
• Configurando o ingresso Caddy com x-caddy, x-ports ou --caddyfile
• Roteando dispositivos LAN externos através do proxy do cluster
• Inspecionando logs, estado de serviços, volumes, DNS ou posicionamento de máquinas

Como Funciona

O Uncloud executa serviços Docker em máquinas pares conectadas por uma rede mesh WireGuard. Cada máquina é um membro igual do cluster; os serviços se comunicam na rede overlay e o Caddy é executado globalmente para terminar tráfego público HTTP/HTTPS. Arquivos Compose podem usar extensões do Uncloud para ingresso, posicionamento e configuração Caddy gerada, enquanto a CLI uc lida com distribuição de imagens, agendamento, escalonamento, logs e estado do cluster.

Exemplos

uc machine init user@host --name machine-1
uc service run --name web -p app.example.com:8080/https nginx:latest
uc deploy

Conceitos Principais

• Sem plano de controle central — todas as máquinas são pares iguais conectadas por WireGuard
• Caddy é executado como um serviço global em cada máquina; obtém TLS automaticamente do Let's Encrypt
• Rede overlay — serviços se comunicam via 10.210.0.0/16 por padrão; DNS é fornecido dentro da mesh
• Caddyfile é gerado automaticamente — nunca edite-o diretamente; use x-caddy / --caddyfile

---

Referência Rápida da CLI

Máquinas

Comando	Finalidade
uc machine init user@host	Inicializar primeira máquina / novo cluster
uc machine add user@host	Adicionar máquina ao cluster existente
uc machine ls	Listar máquinas
uc machine update NAME --public-ip IP	Atualizar IP público para ingresso
uc machine rm NAME	Remover máquina

Flags principais do init: --name, --network 10.210.0.0/16, --no-caddy, --no-dns, --public-ip auto|IP|none

Serviços

Comando	Finalidade
uc service ls / uc ls	Listar serviços
uc service run IMAGE	Executar um serviço de contêiner único
uc deploy	Implantar a partir de compose.yaml
uc deploy --no-build	Implantar imagens já enviadas sem reconstruir
uc deploy --recreate	Forçar recriação do serviço
uc scale SERVICE N	Definir número de réplicas
uc service logs SERVICE	Visualizar logs
uc service exec SERVICE	Acessar shell do contêiner
uc service inspect SERVICE	Informações detalhadas
uc service rm SERVICE	Remover serviço (mantém volumes nomeados)
uc ps	Todos os contêineres do cluster

Imagens

uc image push myapp:latest                    # Enviar imagem local para todas as máquinas
uc image push myapp:latest -m machine1,machine2  # Enviar para máquinas específicas
uc images                                     # Listar imagens no cluster

Volumes

uc volume ls                  # Todos os volumes
uc volume ls -m machine1      # Em máquina específica
uc volume create NAME -m MACHINE
uc volume rm NAME

Caddy

uc caddy config    # Mostrar Caddyfile gerado atual (somente leitura)
uc caddy deploy    # Implantar/atualizar Caddy em todo o cluster

DNS e Contexto

uc dns show        # Mostrar domínio *.uncld.dev reservado
uc dns reserve     # Reservar novo domínio
uc ctx ls          # Listar contextos do cluster
uc ctx use prod    # Trocar de contexto

---

Publicação de Portas

HTTP/HTTPS (via proxy reverso Caddy)

-p [hostname:]container_port[/protocol]

Exemplo	Significado
-p 8080/https	HTTPS com nome de host automático service-name.cluster-domain
-p app.example.com:8080/https	HTTPS com nome de host personalizado
-p 8080/http	Apenas HTTP, sem TLS

TCP/UDP (vinculado ao host, ignora Caddy)

-p [host_ip:]host_port:container_port[/protocol]@host

Exemplo	Significado
-p 5432:5432@host	TCP 5432 em todas as interfaces
-p 127.0.0.1:5432:5432@host	TCP 5432 apenas loopback
-p 53:5353/udp@host	UDP

---

Extensões de Arquivo Compose

O Uncloud adiciona estas extensões sobre o Docker Compose:

x-ports — publicar portas com domínios

services:
  app:
    image: app:latest
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
      - api.example.com:9000/https

x-caddy — configuração Caddy personalizada para o serviço

services:
  app:
    image: app:latest
    x-caddy: |
      example.com {
        redir https://www.example.com{uri} permanent
      }
      www.example.com {
        reverse_proxy {{upstreams 8000}} {
          import common_proxy
        }
        basic_auth /admin/* {
          admin $2a$14$...
        }
      }

Funções de template disponíveis dentro de x-caddy:

• {{upstreams [service] [port]}} — IPs de contêineres saudáveis
• {{.Name}} — nome do serviço
• {{.Upstreams}} — mapa de todos os serviços → IPs

x-machines — restrições de posicionamento

services:
  db:
    image: postgres:18
    x-machines: db-machine          # Nome de única máquina
  app:
    image: app:latest
    x-machines:
      - machine-1
      - machine-2

Exemplo completo de múltiplos serviços

services:
  api:
    build: ./api
    x-ports:
      - api.example.com:3000/https
    environment:
      DATABASE_URL: postgres://db:5432/mydb

  web:
    build: ./web
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
    environment:
      API_URL: http://api:3000

  db:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db-data:/var/lib/postgresql/data
    x-machines: db-machine

volumes:
  db-data:

---

Roteamento para Dispositivos Externos (Fora do Cluster)

Para expor um dispositivo externo (ex.: BMC, NAS, interface do roteador) via Caddy sem executar um contêiner real:

1. Crie um trecho de Caddyfile (ex.: ~/device.caddyfile):

https://device.example.com {
    reverse_proxy https://192.168.1.x {
        transport http {
            tls_insecure_skip_verify   # necessário para certificados BMC autoassinados
        }
    }
    log
}

Para upstream sem criptografia: reverse_proxy http://192.168.1.x:porta

2. Registre como um serviço nomeado com contêiner no-op:

uc service run \
  --name device-bmc \
  --caddyfile ~/device.caddyfile \
  registry.k8s.io/pause:3.9

pause é um contêiner no-op mínimo — não faz nada, mas dá ao Uncloud uma entrada de serviço para anexar o Caddyfile.

3. Verifique:

uc caddy config   # O bloco device.example.com deve aparecer

--caddyfile não pode ser combinado com portas publicadas que não sejam @host.

Dica de DNS: Um registro curinga (*.seudominio.com → ip-publico-do-cluster) significa que qualquer novo subdomínio funciona imediatamente — sem necessidade de alteração de DNS por serviço.

---

DNS de Serviço (Interno)

Serviços dentro do cluster resolvem uns aos outros pelo nome:

Nome DNS	Resolve para
service-name	Qualquer contêiner saudável
service-name.internal	O mesmo
rr.service-name.internal	Round-robin
nearest.service-name.internal	Prioriza máquina local

---

Escalonamento e Serviços Globais

uc scale web 5    # 5 réplicas (distribuídas entre máquinas)
uc scale web 1    # Reduzir

services:
  caddy:
    deploy:
      mode: global   # Um contêiner em cada máquina

---

Templates de Tags de Imagem (no compose.yaml)

image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}

Função	Saída
{{gitsha N}}	Primeiros N caracteres do SHA do commit
{{gitdate "formato"}}	Data do commit no formato Go
{{date "formato"}}	Data atual

---

Fluxos de Trabalho Comuns

Implantar a partir do código-fonte:

uc deploy                          # Compila + envia + implanta
uc build --push && uc deploy --no-build   # Etapas separadas

Inspecionar um serviço:

uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web                        # Abre shell
uc exec web /bin/sh -c "env"       # Executar comando específico

Implantações sem downtime ocorrem automaticamente; o Uncloud aguarda verificações de saúde antes de encerrar contêineres antigos.

Forçar recriação:

uc deploy --recreate

---

Erros Comuns

Erro	Correção
Editar o Caddyfile diretamente	Use x-caddy no compose ou --caddyfile no uc service run
Proxy de upstream HTTPS com certificado autoassinado	Adicione transport http { tls_insecure_skip_verify }
uc caddy config não mostra blocos definidos pelo usuário	Socket admin do Caddy inacessível — verifique uc inspect caddy e uc logs caddy
Serviço não consegue acessar IP LAN externo do contêiner	Verifique se o host do contêiner Caddy tem rota para a rede de destino
Volumes perdidos após uc service rm	Volumes nomeados persistem; apenas volumes anônimos são removidos automaticamente