Como instalar o Mealie em um VPS com Docker Compose

O que faz um gestor de receitas autoalojado

Um gestor de receitas autoalojado mantém as suas receitas numa base de dados num servidor que controla, e o Mealie é a opção escolhida pela maioria das famílias. Cole o endereço de uma página de receitas e o Mealie extrai os ingredientes, os passos, o rendimento e o tempo de preparação, deixando de fora o texto e a publicidade. O que fica na sua coleção é a receita.

O resto da aplicação é simples. Existe um plano semanal de refeições para o qual pode arrastar receitas e uma lista de compras criada a partir desse plano. Cada pessoa que cozinha tem a sua própria conta. Tudo é executado num único contentor e permanece inativo entre pedidos, por isso um VPS modesto consegue alojá-lo sem problemas.

Este guia usa Docker Compose. Se os termos services: e volumes: são novos para si, leia primeiro como são estruturados os ficheiros do Docker Compose, porque tudo o que se segue é um único ficheiro Compose e quatro comandos.

Instale o Mealie com Docker Compose

O Mealie publica as suas imagens no registo de contentores do GitHub. Em julho de 2026, a tag estável atual é v3.22.0. Fixe uma versão em vez de usar latest: com latest, uma docker compose pull num dia não relacionado pode fazer a atualização atravessar uma migração da base de dados para a qual ainda não está preparado.

sudo mkdir -p /srv/mealie
cd /srv/mealie
sudo nano docker-compose.yml

services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:v3.22.0
    container_name: mealie
    restart: always
    ports:
      - "127.0.0.1:9925:9000"
    deploy:
      resources:
        limits:
          memory: 1000M
    volumes:
      - mealie-data:/app/data/
    environment:
      ALLOW_SIGNUP: "false"
      PUID: 1000
      PGID: 1000
      TZ: Europe/Amsterdam
      BASE_URL: https://recipes.example.com

volumes:
  mealie-data:

Vale a pena verificar duas linhas antes de o iniciar.

A porta está escrita como 127.0.0.1:9925:9000 e não como 9925:9000. O contentor escuta na porta 9000 internamente, e o host encaminha a porta 9925 para essa porta. Associar esse mapeamento ao endereço de loopback permite que o nginx alcance o Mealie, mas impede o acesso pela internet. O Docker escreve as suas próprias regras no filtro de pacotes, por isso um 9925:9000 simples fica acessível a partir do exterior mesmo quando a firewall indica que a porta está fechada. É importante compreender esta situação uma vez: consulte por que motivo as portas publicadas pelo Docker ignoram o ufw.

BASE_URL tem de ser o endereço público exato que vai utilizar, com o esquema e sem uma barra final. O Mealie gera a partir dele as ligações para reposição de palavras-passe e os convites. Se o definir como http://localhost:9925, o convite enviado ao seu parceiro terá uma ligação que só funciona no próprio servidor.

Inicie-o e monitorize o primeiro arranque.

sudo docker compose up -d
sudo docker compose logs -f mealie

O primeiro arranque cria a base de dados SQLite e executa as migrações, o que demora alguns segundos. Quando o log estabilizar e deixar de apresentar linhas de migração, verifique a aplicação localmente.

curl -I http://127.0.0.1:9925

Um 200 OK significa que a aplicação está em execução. Connection refused significa que o contentor não está em execução: execute sudo docker compose ps e consulte o código de saída. Um contentor que terminou com o código 137 foi terminado por exceder o limite de memória de 1000M, o que acontece nos planos mais pequenos.

Primeiro login e desativação do registo aberto

A conta predefinida é changeme@example.com e a palavra-passe é MyPassword. Inicie sessão com essa conta e altere imediatamente ambos os valores, porque essa combinação está publicada na documentação e, por isso, faz parte de todos os scanners.

ALLOW_SIGNUP: "false" no ficheiro compose é intencional. Com o registo aberto, qualquer pessoa que descubra o endereço pode criar uma conta na sua caixa de receitas. Com o registo fechado, adiciona as pessoas a partir da área de administração, que gera um link de convite para enviar diretamente a cada pessoa. Esse link é criado a partir de BASE_URL, por isso esse valor é importante. Se acabar por executar várias aplicações no mesmo servidor e quiser usar uma única palavra-passe em todas, o Mealie pode delegar o login num fornecedor de identidade externo, como uma instância Authentik autoalojada.

O Mealie organiza os utilizadores por agregado familiar. Todas as pessoas do mesmo agregado partilham a coleção de receitas, o plano de refeições e a lista de compras, que é o que uma família precisa. Agregados diferentes no mesmo servidor mantêm coleções separadas, o que é útil numa casa partilhada quando ninguém chega a acordo sobre as anchovas.

O importador, que é o motivo para executar isto

Abra a coleção de receitas, escolha criar uma receita a partir de um URL e cole uma ligação. O Mealie obtém a página e procura dados estruturados de receitas, o bloco legível por máquinas que a maioria dos sites de receitas incorpora para os motores de pesquisa. Quando esse bloco está presente, a importação é limpa e imediata.

Também pode importar a partir de uma imagem ou de texto simples colado por si, incluindo uma fotografia de uma página de um livro de receitas. Estes casos seguem um processo mais lento e devem ser verificados depois, porque é fácil interpretar mal uma fração manuscrita.

As importações em massa são executadas no mesmo ecrã: cole uma lista de endereços, um por linha, e o Mealie processa-os em segundo plano. Uma coleção com duzentos marcadores é transferida de uma só vez.

Planos de refeições e lista de compras

O planeador de refeições é um calendário. Arraste uma receita para um dia para a planear. A lista de compras recolhe os ingredientes das receitas planeadas numa única lista e combina os duplicados. Assim, duas receitas que precisem de cebolas produzem uma linha em vez de duas.

A lista é uma página atualizada em tempo real no seu telemóvel, enquanto está na loja. Como é mantida pelo seu próprio servidor, todas as pessoas da casa veem a mesma lista ao mesmo tempo. Quando uma pessoa marca o leite como comprado, este desaparece do ecrã das outras pessoas.

Configure o nginx e o TLS na frente

O Mealie utiliza HTTP simples e não trata certificados por conta própria. Termine o Transport Layer Security (TLS) no nginx, que ficará na frente do serviço. Primeiro, aponte um registo DNS A para o seu servidor, porque a emissão do certificado valida esse nome.

sudo apt update && sudo apt install -y nginx
sudo nano /etc/nginx/sites-available/mealie

server {
    listen 80;
    server_name recipes.example.com;

    client_max_body_size 64M;

    location / {
        proxy_pass http://127.0.0.1:9925;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo ln -s /etc/nginx/sites-available/mealie /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

nginx -t, syntax is ok e test is successful são a verificação necessária. Só faça o reload depois de essa verificação passar, porque recarregar uma configuração inválida mantém a configuração antiga em execução e oculta o erro até ao próximo restart.

client_max_body_size 64M é necessário porque o valor predefinido do nginx é 1 MB. Carregar uma fotografia de receita ou restaurar uma cópia de segurança pelo browser envia um body maior do que esse limite. Sem essa linha, recebe um 413 Request Entity Too Large do nginx, não do Mealie, e o log da aplicação não regista nada.

Em seguida, emita o certificado. Essa etapa e o respetivo timer de renovação são descritos em emitir um certificado Let's Encrypt para o nginx com certbot.

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d recipes.example.com

O Certbot reescreve o server block para escutar na porta 443 e adiciona um redirecionamento da porta 80. Carregue o site através de https:// e confirme que o browser aceita o certificado. Se o Mealie carregar, mas os próprios links enviarem para http://, então BASE_URL ainda indica http. Corrija esse valor e execute sudo docker compose up -d para recriar o container com o novo valor.

Servir o Mealie num subpath, como example.com/recipes, não funciona, porque o frontend não pode ser servido a partir de um subpath. Utilize um subdomínio.

Backups e o que uma restauração realmente faz

Tudo o que o Mealie gere fica em /app/data/ dentro do contentor. Esse é o volume mealie-data. Ao copiar esse volume, copia as receitas, as imagens e a base de dados em conjunto.

sudo docker volume ls
sudo docker compose stop mealie
sudo docker run --rm -v mealie_mealie-data:/data -v "$PWD":/backup \
  alpine tar czf /backup/mealie-data.tgz -C /data .
sudo docker compose start mealie

O nome do volume tem o nome do projeto como prefixo, e o nome do projeto é o diretório que contém o ficheiro compose. Em /srv/mealie, o volume é mealie_mealie-data. Por isso, o primeiro comando é docker volume ls: use o nome apresentado pelo comando, não o nome deste guia. É importante parar primeiro o contentor, porque o SQLite está frequentemente a escrever e uma cópia feita com o serviço em execução pode ser restaurada como ilegível.

O Mealie também tem a sua própria página de backup na área de administração. Essa página cria um arquivo portátil que contém a base de dados em JSON e as imagens. Use-o para migrar entre servidores, porque continua a funcionar depois de uma alteração de versão que pode impedir uma cópia direta dos ficheiros. A restauração é destrutiva por definição: elimina a base de dados atual antes de carregar o arquivo e não pode ser anulada. A sessão é terminada quando o processo acaba.

Nenhuma das cópias é um backup enquanto permanecer no mesmo servidor. Envie o arquivo para outro local segundo um agendamento. É para isso que servem os backups encriptados fora do servidor com restic.

Atualizar o Mealie

cd /srv/mealie
sudo nano docker-compose.yml
sudo docker compose pull
sudo docker compose up -d
sudo docker compose logs -f mealie

Aumente a versão fixada no ficheiro e, em seguida, faça o pull e recrie o contentor. As migrações são executadas no primeiro arranque da nova imagem. Faça uma cópia do volume antes de mudar de versão principal, porque uma migração que falhe a meio deixa uma base de dados que a imagem anterior já não consegue abrir. Leia as notas de lançamento de todas as versões entre a sua versão atual e a nova versão.

Quando o importador falha

Alguns sites não publicam dados estruturados de receitas, e o Mealie importa apenas o título, com a lista de ingredientes vazia. Não é possível corrigir isso através de configuração. Cole manualmente o texto da receita.

Outras falhas são causadas pela proteção contra bots colocada à frente do site da receita, que responde ao Mealie com uma página de desafio em vez da receita. O Mealie já se identifica como um navegador e alterna o user agent para reduzir este problema. Quando um site continua a recusar o acesso, as opções documentadas são encaminhar o scraper através de um proxy com melhor reputação de endereço ou executar uma instância do FlareSolverr que resolva o desafio num navegador real. Ambas são opcionais e são configuradas através de variáveis de ambiente no contentor.

Um import que falha porque o servidor não consegue alcançar o site é um problema diferente. Teste a partir do servidor com curl -I https://the-site.example/recipe e leia a linha de estado antes de atribuir a falha ao scraper.

Onde se enquadra

O Mealie é uma boa primeira aplicação self-hosted para uma casa, porque as pessoas com quem vive vão utilizá-lo sem ser necessário pedir-lhes. Tem uma finalidade semelhante à de executar a sua própria biblioteca de fotografias com o Immich, embora seja muito mais leve, e faz parte da lista mais ampla de serviços que vale a pena alojar por conta própria este ano. Um servidor pequeno pode alojar ambos. O Immich não é a única opção para essa segunda finalidade e, se ainda estiver a decidir, os requisitos mínimos de memória e os comandos de backup do PhotoPrism e do Immich são suficientemente diferentes para justificar a leitura antes de atribuir o restante espaço em disco.

FAQ

Porque é que a importação de um URL de receita falha?

Existem duas causas comuns. A página pode não publicar dados estruturados de receita, pelo que o scraper não encontra nada e obtém um título sem ingredientes. Em alternativa, uma camada de proteção contra bots à frente do site pode devolver uma página de desafio em vez da receita. No segundo caso, o Mealie pode ser configurado para utilizar um proxy com melhor reputação de endereço ou uma instância FlareSolverr auto-hospedada que resolve o desafio num navegador real. Confirme que o servidor consegue aceder à página com curl -I antes de alterar qualquer configuração.

Preciso de PostgreSQL ou o SQLite é suficiente?

O SQLite é suficiente para uma casa e é a opção predefinida. Mude para PostgreSQL quando o diretório de dados estiver num armazenamento ligado à rede, porque o SQLite num sistema de ficheiros de rede produz erros de base de dados bloqueada e pode corromper o ficheiro. As restaurações com PostgreSQL exigem que o utilizador da base de dados seja superuser, porque a restauração elimina tudo antes de carregar o arquivo.

Posso executar o Mealie sem um nome de domínio?

Sim, na sua própria rede. Defina BASE_URL para o endereço que vai realmente introduzir, como http://192.168.1.20:9925, e não utilize nginx. As ligações de convite e reposição de palavra-passe são criadas a partir de BASE_URL, pelo que um valor incorreto produz ligações que mais ninguém consegue abrir. Não o exponha à internet através de HTTP simples, porque nesse caso o início de sessão é enviado sem encriptação.

Como posso dar à minha família as suas próprias contas?

Mantenha ALLOW_SIGNUP definido como "false" e adicione as pessoas na área de administração. Isto produz uma ligação de convite que pode enviar-lhes. Coloque no mesmo agregado familiar todas as pessoas que partilham uma cozinha, para que partilhem as receitas, o plano de refeições e a lista de compras. Agregados familiares separados no mesmo servidor mantêm coleções separadas.

O que acontece às minhas receitas se deixar de executar o Mealie?

Pode levá-las consigo. A cópia de segurança da área de administração grava os seus dados em JSON. O Mealie também pode exportar receitas como ficheiros markdown simples, que continuam legíveis em qualquer editor de texto, sem necessidade de software adicional. Faça uma exportação antes de precisar dela e confirme que consegue abri-la.