# Satela > A Satela publica o seu sistema a partir do GitHub, sem derrubar o site, e cuida de endereço, HTTPS, bancos de dados e acompanhamento de uso. --- # Documentação da Satela A Satela coloca o seu sistema na internet e cuida do resto: publicar versões novas, endereço, segurança do site, bancos de dados e acompanhamento do uso. Você conecta o seu código do GitHub e cada atualização vai ao ar sozinha, **sem derrubar o site**. ## Se você não é da área técnica - [Como funciona, em poucas palavras](/comecar/) - [Como acompanhar o seu consumo (os cubos)](/consumo/) - [Perguntas frequentes](/faq/) ## Se você é desenvolvedor (ou é uma IA lendo isto) - [O que o seu repositório precisa ter](/repositorio/) - [Publicar, versões e voltar atrás](/publicar/) - [Endereço e HTTPS](/enderecos/) - [Variáveis e segredos](/variaveis/) - [Dados, bancos e arquivos](/dados/) - [Limites, portas e WebSocket](/limites/) - [Satela AI (texto, imagem, documento, áudio, voz)](/satela-ai/) - [O que a Satela não faz](/limites-do-servico/) Versão para máquinas: [llms.txt](/llms.txt) (índice) e [llms-full.txt](/llms-full.txt) (tudo em um arquivo só). --- # Como funciona, em poucas palavras 1. **Você conecta o seu código.** Ele fica no GitHub. A Satela lê de lá; não é preciso enviar arquivos. 2. **A Satela monta e publica.** Cada vez que o código muda, ela cria uma versão nova e só troca a antiga quando a nova está funcionando. 3. **O seu site continua no ar.** Se a versão nova falhar, a anterior segue atendendo e você vê o motivo na tela do app. 4. **Você acompanha tudo no painel:** se o app está no ar, o que aconteceu, e quanto do seu plano já foi usado. ## O que você vê no painel - **Status:** "No ar", "Parado" ou "Atualizando". - **Versões:** cada atualização fica guardada; dá para voltar para uma anterior com um clique. - **Uso:** os [cubos](/consumo/), como a bateria do celular. ## Quem faz o quê | Você | A Satela | |---|---| | Escreve e atualiza o código | Constrói, publica e mantém no ar | | Escolhe o endereço desejado | Liga o endereço e o cadeado (HTTPS) | | Define as senhas e chaves do app | Guarda cada uma de forma cifrada | Dúvida sobre um termo técnico? Veja as [perguntas frequentes](/faq/). --- # Como acompanhar o seu consumo ## A bateria de cubos No painel, o seu plano aparece como uma **fileira de cubos**, parecida com a bateria do celular. Cada cubo verde é uma parte do plano que ainda sobra; conforme o app trabalha, os cubos vão se apagando. - **Cubos cheios:** você está bem dentro do plano. - **Poucos cubos:** o plano deste período está acabando. - **Sem cubos ("potência excedente"):** o plano do período acabou e **o app continua funcionando normalmente**. O uso a mais é considerado à parte. - **O plano não acumula:** o que sobra de um período não passa para o seguinte. O painel diz em quantos dias o período fecha. ## O que consome o plano Cada item mostra **Pouco**, **Moderado** ou **Bastante**, sem números complicados: - **Processamento:** o quanto o sistema trabalhou. - **Memória:** o espaço de trabalho ocupado. - **Tráfego de rede:** o que foi enviado e recebido (visitas, downloads, integrações). - **Banco e arquivos:** espaço extra para dados e arquivos. - **Satela AI:** o quanto a inteligência artificial trabalhou por você. ## Detalhes avançados Quem quiser os **valores exatos** abre "Ver detalhes avançados" no painel. Lá aparecem as quantidades do período atual, com unidade: - Processamento em **horas**. - Memória em **GB por hora**. - Tráfego em **GB**. - Banco e arquivos em **GB** ou blocos de 512 MB. - Satela AI em **k tokens**. Um *token* é um pedaço de palavra; **1 k = mil tokens**. Usamos "k" (e não milhões) porque números pequenos ficam visíveis. O painel nunca mostra os cálculos internos da cobrança. --- # Perguntas frequentes **O que é um "deploy"?** É publicar uma versão nova do seu sistema. Na Satela acontece sozinho quando o código muda. **O meu site sai do ar quando atualizo?** Não. A versão nova sobe ao lado da atual e só assume quando está funcionando. **E se a atualização der erro?** A versão atual continua no ar. Você vê o motivo na tela do app e pode voltar para uma versão anterior. **O que é HTTPS?** É o cadeado do navegador: o site é aberto de forma segura. A Satela liga e renova isso automaticamente. **O que é um domínio próprio?** O endereço da sua empresa (por exemplo, `www.suaempresa.com.br`) em vez do endereço padrão da Satela. A equipe liga para você. **O que é um banco de dados?** O lugar onde o sistema guarda as informações (clientes, pedidos, mensagens). A Satela oferece PostgreSQL e Redis, com cópia diária do PostgreSQL. **O que é uma "variável"?** Uma configuração ou senha que o sistema lê ao iniciar e que fica fora do código. Veja [variáveis e segredos](/variaveis/). **O que são os cubos?** A bateria do seu plano. Veja [como acompanhar o consumo](/consumo/). **Como peço um domínio próprio, mais recursos ou ajuda?** Pelo suporte da Satela. Alguns ajustes só a equipe faz, por segurança. --- # O que o seu repositório precisa ter A Satela só publica código que está no **GitHub** (repositórios públicos ou privados). ## Dockerfile Na raiz do repositório (ou em outra pasta, informando o caminho e a pasta de contexto no painel, útil em monorepo). Sem Dockerfile, a Satela tenta reconhecer projetos Next.js, Node, Django, FastAPI, Flask e sites estáticos. - O app deve **escutar em uma única porta**, a do `EXPOSE` do Dockerfile (ou a que você informar no painel). A variável de ambiente `PORT` também é passada ao app. - Rode como um usuário comum, se puder. ## Procfile (opcional) ``` web: gunicorn config.wsgi --bind :$PORT release: python manage.py migrate worker: python tarefas.py ``` - `web` substitui o comando padrão do Dockerfile. - `release` roda **uma vez** antes de cada troca de versão (bom para migrações). - Qualquer outra linha (ex.: `worker`) vira um processo de fundo, sem endereço na internet. ## Arquivo ENV (opcional) Linhas `NOME=valor` com valores padrão que **não** são segredos. O que você definir no painel tem prioridade. Veja [variáveis e segredos](/variaveis/). `HEALTHCHECK_PATH=/saude` muda a rota usada para verificar se o app está bem. ## Pasta de dados O que precisa sobreviver a novas versões (um arquivo SQLite, uploads) deve ficar em **`/data`**. Todo o resto do app é recriado a cada versão. Se o app roda com um usuário comum, a pasta `/data` precisa pertencer a ele no Dockerfile (por exemplo `mkdir /data && chown 10001 /data`). ## Saúde Depois de subir a versão nova, a Satela faz uma requisição à rota de saúde (padrão `/`). Respostas abaixo de 500 contam como saudável; erro 5xx ou silêncio reprovam a versão, que então não vai ao ar. A espera máxima é de 2 minutos. --- # Publicar, versões e voltar atrás ## Como uma versão vai ao ar 1. Você envia uma alteração (`push`) para a **branch de produção** escolhida no painel. 2. A Satela é avisada pelo GitHub (e confere por conta própria a cada 30 segundos). 3. Ela baixa o código, constrói o app e, se houver `release` no Procfile, roda esse comando. 4. Sobe a versão nova **ao lado** da antiga e verifica a saúde. 5. Só então troca o tráfego para a nova e, depois de uns 30 segundos para as conexões em andamento terminarem, desliga a antiga. **Se algo falhar antes da troca, a versão atual continua no ar.** O motivo aparece no registro da versão. ## Versões Cada versão corresponde a um commit do GitHub. A Satela guarda as **5 mais recentes** prontas para uso. ## Voltar atrás No painel, escolha uma versão anterior e peça para voltar. Ela é reativada **sem reconstruir**, então é rápido. Só é possível voltar para as versões guardadas. ## Forçar uma nova publicação Se nada mudou no código, mas você quer reconstruir (por exemplo, para atualizar dependências), use "reimplantar" no painel. Mudar uma variável também gera uma publicação nova. ## Parar, ligar e reiniciar O painel permite parar o app (o endereço mostra "temporariamente parado"), ligar de novo e reiniciar. A versão fica guardada enquanto parado. --- # Endereço e HTTPS ## Endereço padrão Todo app ganha um endereço pronto no formato `nome-do-app.satela.com.br`, já com o **cadeado (HTTPS)** ativo. Não é preciso configurar nada. ## Domínio próprio (ex.: `www.suaempresa.com.br`) O domínio próprio é ligado pela **equipe da Satela**, para evitar que alguém aponte para um endereço que não é seu. Peça pelo suporte. O processo: 1. A equipe informa para onde o DNS do seu domínio deve apontar. 2. Você faz essa mudança no lugar onde registrou o domínio. 3. A Satela confere sozinha se o apontamento chegou e só então liga o endereço. 4. O certificado de segurança é emitido e renovado automaticamente. A mudança de DNS pode levar de alguns minutos a algumas horas para valer. ## Para desenvolvedores - O certificado é emitido pelo Let's Encrypt, um por endereço, sem custo extra. - O tráfego passa por um proxy reverso que **aceita WebSocket** normalmente. - Os cabeçalhos de segurança padrão e a compressão (gzip e zstd) já vêm ligados. - Não é possível personalizar regras do proxy por app (por exemplo, enviar um caminho para outra porta). --- # Variáveis e segredos **Variável** é uma configuração que o app lê ao iniciar (um endereço, uma chave de acesso, uma senha). Ela fica fora do código para que o segredo não vá parar no GitHub. ## Onde definir - **No painel do app** (para segredos): ficam **cifradas** e nunca entram na imagem nem aparecem em registros. - **No arquivo `ENV` do repositório** (para valores que não são segredos): servem de padrão. Se a mesma variável existir nos dois lugares, **vale a do painel**. ## O que a Satela já entrega ao app - `PORT`: a porta em que o app deve escutar. - `DATABASE_URL` e `REDIS_URL`: quando você liga um [banco gerenciado](/dados/) ao app. ## Importante - Alterar uma variável gera uma **nova publicação** (as variáveis só valem em uma versão nova). - Não é possível importar um arquivo `.env` inteiro: os valores são colados no painel. - Argumentos de construção (`ARG` no Dockerfile) também podem receber valores do painel. --- # Dados, bancos e arquivos ## Pasta `/data` Cada app tem uma pasta persistente em `/data`. Ela **sobrevive** a novas versões, reinícios e voltas de versão. O resto do app é recriado a cada publicação, então qualquer arquivo que precise ficar (um banco SQLite, uploads de usuários) deve morar em `/data`. **Atenção com SQLite:** durante a troca de versão, a versão antiga e a nova ficam no ar juntas por cerca de 30 segundos e enxergam a mesma pasta `/data`. Um app com SQLite deve tolerar dois processos usando o mesmo arquivo nesse intervalo. **Cópia de segurança:** a pasta `/data` de um app **não** tem cópia automática. Combine com a equipe se o seu app precisa disso. ## Bancos gerenciados - **PostgreSQL** (versões 15 a 17) e **Redis** (7 e 8). - Cada banco roda isolado, em rede própria, e **só os apps ligados a ele o enxergam**. - A Satela cria a variável `DATABASE_URL` (ou `REDIS_URL`) no app ligado. - O PostgreSQL tem **cópia diária** e restauração pela equipe, sempre com uma cópia de segurança antes de restaurar. ## O que não existe MySQL/MariaDB gerenciado e extensões de busca vetorial (como `pgvector`) não são oferecidos. Se o seu app precisa deles, rode-os dentro do seu próprio app. --- # Limites, portas e WebSocket ## Recursos de cada app Cada app roda isolado, com limite de processador e de memória definidos no plano. O padrão é **meio processador e 512 MB de memória**, e a equipe pode ajustar. Há também um limite de processos simultâneos e uma pasta temporária (`/tmp`) pequena. ## Uma porta por app O app escuta em **uma única porta**. A Satela não envia caminhos diferentes para portas diferentes. Se o seu sistema tem duas partes (por exemplo, um site e um canal de WebSocket), sirva as duas na mesma porta. ## WebSocket Conexões WebSocket funcionam pelo mesmo endereço do app, na mesma porta. Mantenha o app pronto para **reconectar sozinho**: quando uma publicação ou ajuste de rota acontece no servidor, conexões abertas podem ser interrompidas. ## Rede - O app tem rede própria e **não enxerga o computador em que roda** (por exemplo, serviços locais em `localhost`). - Para falar com outro serviço da Satela ou da internet, use o **endereço público** dele. - A saída para a internet funciona normalmente. ## Verificação de saúde Só acontece na publicação (veja [Publicar](/publicar/)). Depois, o app reinicia sozinho se cair e a equipe é avisada quando ele cai e quando volta. ## Segurança do app Os apps rodam sem privilégios extras: não conseguem mudar configurações do servidor e ficam separados uns dos outros. --- # Satela AI A Satela AI é uma API de inteligência artificial **compatível com a da OpenAI**. Se o seu código já usa uma biblioteca da OpenAI, basta trocar o endereço e a chave. - **Endereço:** `https://ai.satela.com.br/v1` - **Chave:** crie no painel (Satela AI > Chaves). Envie no cabeçalho `Authorization: Bearer sk-sat-...`. A chave aparece **uma única vez**, guarde-a em local seguro. - **Modelos:** você usa só os nomes da Satela (por exemplo `AC310`). A lista do que está liberado para você vem em `GET /v1/models`. Um modelo só funciona depois que a equipe o libera. ## O que a Satela AI faz | O que você quer | Rota | Observação | |---|---|---| | Conversar, resumir, classificar, extrair dados | `POST /v1/chat/completions` | Texto, com respostas em tempo real (`stream`) e funções (`tools`) | | Entender uma **imagem** | `POST /v1/chat/completions` | Imagem dentro da mensagem | | Ler um **documento** (PDF e texto) | `POST /v1/chat/completions` | Documento dentro da mensagem | | Transformar **áudio em texto** | `POST /v1/audio/transcriptions` | Inclui áudio de WhatsApp (ogg/opus) | | Transformar **texto em voz** | `POST /v1/audio/speech` | Devolve um arquivo WAV | | Busca por significado (**embeddings**) | `POST /v1/embeddings` | Texto único ou lista | ## Exemplos **Conversa** ``` curl https://ai.satela.com.br/v1/chat/completions \ -H "Authorization: Bearer $SATELA_KEY" -H "Content-Type: application/json" \ -d '{"model":"AC310","messages":[{"role":"user","content":"Resuma em uma frase: ..."}]}' ``` **Imagem e documento na mensagem** (o arquivo vai em base64, como `data:;base64,...`) ``` {"model":"AC310","messages":[{"role":"user","content":[ {"type":"text","text":"O que diz este contrato?"}, {"type":"file","file":{"filename":"contrato.pdf","file_data":"data:application/pdf;base64,JVBERi0..."}}, {"type":"image_url","image_url":{"url":"data:image/png;base64,iVBORw0..."}} ]}]} ``` - Imagens: PNG, JPEG e WebP, até 10 MB cada. - Documentos: PDF, texto, CSV, HTML e Markdown, até 20 MB cada. - Até 10 arquivos por pedido e 30 MB no total. Endereços da internet (`https://...`) não são aceitos: envie o arquivo em base64. - Com documento, a resposta vem inteira (sem `stream`) e sem `tools`. **Áudio para texto** ``` curl https://ai.satela.com.br/v1/audio/transcriptions \ -H "Authorization: Bearer $SATELA_KEY" \ -F model=TRC100 -F file=@mensagem.ogg -F language=pt ``` - Formatos: ogg, opus, mp3, wav, flac, aac e m4a, até 20 MB (cerca de uma hora de voz). Em WAV o limite é de 30 minutos. - Campos opcionais: `language` (ex.: `pt`), `prompt` (até 500 caracteres, com nomes e termos para ajudar na grafia) e `response_format` (`json`, o padrão, ou `text`). **Texto para voz** ``` curl https://ai.satela.com.br/v1/audio/speech \ -H "Authorization: Bearer $SATELA_KEY" -H "Content-Type: application/json" \ -d '{"model":"SPK100","input":"Olá! Seu pedido saiu para entrega.","voice":"aurora"}' --output fala.wav ``` - Vozes: `aurora` (padrão), `brisa`, `cedro`, `duna`, `estrela` e `farol`. O texto pode ter até 4.000 caracteres. O formato de saída é só `wav`. **Embeddings** ``` {"model":"EMB100","input":["primeiro texto","segundo texto"]} ``` Até 100 textos por pedido e 30.000 caracteres cada. ## Como o uso é contado Tudo é contado em **tokens** e aparece no painel em **k tokens** (1 k = mil tokens). Para áudio e imagem, o painel usa o equivalente em tokens: **cerca de 32 tokens por segundo de áudio** e **cerca de 1.100 tokens por imagem**. Veja [como acompanhar o consumo](/consumo/). ## Limites e erros - Cada chave tem um limite de **chamadas por minuto** e, se você quiser, um **teto mensal**. Passou do limite: erro `429`. - Os erros seguem o formato da OpenAI: `{"error": {"message": "...", "type": "...", "code": "..."}}`. - `400` pedido inválido (formato, tamanho, tipo de arquivo) · `401` chave inválida · `413` arquivo grande demais · `429` limite atingido · `502` ou `503` falha momentânea (tente de novo). ## O que ainda não existe - Geração de imagens. - Legendas com tempo (`srt`/`vtt`) na transcrição. - Voz em `mp3` ou `opus` (só `wav`). - Imagens ou documentos por endereço da internet. --- # O que a Satela não faz Para você planejar com segurança, estas coisas **não existem** hoje: - Publicar a partir de outro lugar que não seja o **GitHub** (nem enviar uma imagem de container pronta). - **Mais de uma porta** por app, ou rotas diferentes indo para portas diferentes. - Regras personalizadas no proxy (cabeçalhos, redirecionamentos por app). - **Cópia de segurança automática** da pasta `/data` de um app (os bancos PostgreSQL têm). - Limite de espaço em disco ou de banda por app. - Tarefas agendadas (`cron`). Só há processos de fundo contínuos, pelo Procfile. - Versões de teste por pedido de alteração (*preview*). - Bancos MySQL/MariaDB gerenciados e busca vetorial (`pgvector`). - Acesso do app a serviços que só existem no servidor local. - Importar um arquivo `.env` completo. Se algo aqui é essencial para o seu projeto, fale com a equipe antes de migrar.