Como instalar o Open-Meteo em uma VPS

Pré-requisitos

A auto-hospedagem do Open-Meteo exige hardware considerável: no mínimo 8 GB de RAM, 16 GB recomendados, uma CPU moderna com suporte a AVX2 e pelo menos 150 GB de armazenamento SSD NVMe para conjuntos abrangentes de dados de previsão. Uma configuração limitada a um único modelo pode caber em 32-48 GB. Isso NÃO é adequado para planos de VPS baratos e de entrada.

Atenção: Para a maioria dos desenvolvedores, a API hospedada (api.open-meteo.com) é gratuita, não exige chave de API e é mais simples de usar. A auto-hospedagem é recomendada apenas para soberania de dados, ambientes isolados de redes externas ou processamento de modelos personalizados.

Planeje downloads grandes, atualizações dos modelos, armazenamento em cache e uma política de limites para a API pública. Mantenha espaço em disco suficiente para conservar o conjunto de modelos anterior e poder reverter uma atualização. Se você só precisa de dados meteorológicos para um aplicativo, considere usar o endpoint hospedado.

Etapa 1, conectando-se ao servidor

Atualize o servidor e crie diretórios separados para a API, os modelos e o cache:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl git
mkdir -p /opt/open-meteo/{app,models,cache,backups}
cd /opt/open-meteo
chmod 750 /opt/open-meteo

Use um volume de disco que persista após a recriação do contêiner. Não armazene os dados dos modelos em uma partição pequena do sistema. Restrinja o SSH e mantenha os arquivos dos modelos fora da raiz pública do site.

Etapa 2, instalando o Docker e o Docker Compose

Instale o Docker Engine e o plugin Compose seguindo as instruções oficiais do Docker para Ubuntu:

docker --version
docker compose version
systemctl enable --now docker
df -h
free -h

A instalação oficial do Open-Meteo pode exigir ferramentas nativas ou um ambiente de execução específico. Siga esse requisito quando a compilação do modelo não oferecer suporte a Docker.

Etapa 3, executando a compilação oficial do Open-Meteo

Baixe o código-fonte atual, os recursos dos modelos e as instruções de compilação do projeto oficial do Open-Meteo. Não invente uma imagem Docker nem use um espelho aleatório de modelos meteorológicos. As fontes de dados e as versões dos modelos necessárias fazem parte da correção do produto.

Se a versão selecionada oferecer uma imagem de contêiner, informe o nome verificado em .env:

OPEN_METEO_IMAGE=REPLACE_WITH_THE_CURRENT_OFFICIAL_IMAGE
MODEL_DATA_PATH=/opt/open-meteo/models
CACHE_PATH=/opt/open-meteo/cache

Um arquivo Compose de implantação pode ter esta estrutura:

services:
  api:
    image: ${OPEN_METEO_IMAGE}
    restart: unless-stopped
    environment:
      MODEL_DATA_PATH: /models
      CACHE_PATH: /cache
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - /opt/open-meteo/models:/models
      - /opt/open-meteo/cache:/cache

Use as portas, variáveis, verificações de integridade e caminhos de montagem dos modelos da versão oficial. Valide somente depois de substituir os marcadores de posição:

docker compose config
docker compose pull
docker compose up -d
docker compose ps

Baixe os dados meteorológicos imediatamente. Sem essa etapa, a API retorna resultados vazios:

docker exec -it <container> sync ecmwf_ifs025 temperature_2m

Substitua <container> pelo nome real do seu contêiner. Registre a versão do modelo e as datas das fontes para que as previsões possam ser reproduzidas.

Os dados dos modelos meteorológicos precisam ser atualizados regularmente. Configure um cron ou timer do systemd para executar o comando de sincronização periodicamente (por exemplo, a cada 6 horas):

crontab -e
# Add: 0 */6 * * * docker exec <container> sync ecmwf_ifs025 temperature_2m

Etapa 4, configurando o proxy reverso

Encaminhe weather.example.com para a porta privada da API no localhost usando Nginx ou Caddy. Encerre o HTTPS no proxy, defina limites adequados para o tamanho do corpo da solicitação e adicione cabeçalhos de cache. Exemplo de configuração do Nginx:

server {
    listen 443 ssl;
    server_name weather.example.com;

    client_max_body_size 1m;
    proxy_buffering off;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache openmeteo;
        proxy_cache_valid 200 30s;
        proxy_cache_use_stale error timeout updating;
    }
}

Mantenha o armazenamento dos modelos e os endpoints administrativos privados. Teste um endpoint de integridade, uma solicitação pequena de previsão e outra que use dados em cache. Não exponha um endpoint ilimitado para baixar modelos nem para depuração.

Etapa 5, primeiro acesso e configuração inicial

Acesse o endpoint da API por HTTPS e envie uma solicitação pequena usando os parâmetros compatíveis com o conjunto de modelos implantado. Verifique o fuso horário, as coordenadas, as unidades e os metadados do modelo. Compare uma resposta de exemplo com a referência oficial antes de integrá-la a um produto.

Adicione monitoramento para detectar dados de modelos desatualizados. Uma API pode retornar HTTP 200 mesmo servindo previsões antigas ou incompletas, então as verificações de integridade também devem conferir a atualização dos dados.

Manutenção

Agende as atualizações dos modelos separadamente das atualizações do aplicativo. Baixe os novos dados para um diretório de preparação, valide-os e faça a troca atomicamente quando o processo oficial permitir. Mantenha o conjunto de modelos anterior para reversão e faça backup apenas da configuração e dos metadados quando os dados forem grandes demais para backups comuns.

Implemente tarefas cron de limpeza, exclua arquivos compactados com mais de 10 dias e identifique arquivos com mais de 90 dias. Monitore o uso do disco, pois o volume de dados meteorológicos cresce continuamente.

Monitore disco, CPU, atualização dos modelos, latência da API e taxa de erros. Se a carga exceder a capacidade da VPS, transfira o processamento dos modelos para computação dedicada ou use o serviço hospedado, em vez de desativar a validação.