Aloje os seus itinerários de viagem com TREK e Docker

A parte mais cansativa do planejamento de uma viagem é que os PDFs de reservas de voo, as confirmações de hotéis, as conversas com os companheiros de viagem e as listas de locais a visitar ficam dispersos em múltiplos lugares. Quando chega a altura de calcular as despesas totais e dividir as contas, é necessário um esforço tremendo para analisar todo esse histórico de dados.

O TREK é um planejador de viagens de código aberto que pode ser autohospedado, integrando o seu itinerário, as suas reservas, o seu orçamento e as listas de bagagem num único local. O seu servidor MCP integrado permite que agentes de IA (como o Claude Desktop) manipulem diretamente os dados das suas viagens.

Este guia irá acompanhá-lo passo a passo, desde a implantação até à gestão completa de uma viagem real do início ao fim.

1. Como implantar o planejador de viagens TREK com Docker

Instalar o Docker num VPS Ubuntu

# Add Docker's official GPG key and set up the Docker repository
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add the official Docker repository
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update package list
sudo apt update

# Install Docker Engine, Docker Community Edition, and containerd runtime
sudo apt install docker-ce docker-ce-cli containerd.io -y

# Verify docker is installed
docker --version

# Starts automatically when your system boots
sudo systemctl enable docker

Gerar a chave de criptografia

O TREK utiliza uma chave para criptografar dados confidenciais. Utilize o comando seguinte ou esta ferramenta online para gerar a sua chave de criptografia:

openssl rand -hex 32

Guarde-a num local seguro; perdê-la significa perder o acesso aos dados criptografados.

Iniciar o contêiner

docker run -d \
  --name trek \
  -p 3000:3000 \
  -e ENCRYPTION_KEY="<generated_key>" \
  -e APP_URL="https://trek.pafor.me" \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  --restart unless-stopped \
  mauriceboe/trek:latest

• APP_URL deve estar definido corretamente — o fluxo de descoberta OAuth do servidor MCP depende disso. Defina o seu endereço HTTPS público final desde o início.

A primeira execução demorará um pouco para descarregar a imagem:

Verifique se está em execução:

docker ps

2. Configurar o encaminhamento de domínio e SSL com o proxy reverso Caddy

O protocolo HTTPS é obrigatório para as chaves de acesso (passkeys) e OAuth para MCP. O nome de domínio é alojado na Cloudflare, que oferece um certificado SSL gratuito e proteção DDoS.

O Caddy é configurado como o servidor de proxy reverso seguro apontando para a porta 3000. Eis um exemplo de Caddyfile:

{$TREK_DOMAIN} {
  encode zstd gzip
  reverse_proxy host.docker.internal:3000
}

3. Configuração inicial e criação do administrador seguro

Existem duas formas de criar a conta de administrador:

• ADMIN_EMAIL e ADMIN_PASSWORD são definidos como variáveis de ambiente; esses valores são usados diretamente.
• O TREK cria o e-mail admin@trek.local, o nome de utilizador admin e uma senha gerada aleatoriamente que é impressa nos logs do contêiner. Execute docker logs trek para recuperá-la.

Se não conseguir encontrar a senha nos logs, redefina-a com o comando:

docker exec -it -e RESET_ADMIN_EMAIL=admin@trek.local -e RESET_ADMIN_PASSWORD='YourNewPassword' trek node server/reset-admin.js

Será solicitado que altere a senha no primeiro login.

Clique em Admin e atualize o endereço de e-mail:

3.1 Cópias de segurança (Backups)

Configure as cópias de segurança automáticas com uma política de retenção no painel de administração:

3.2 Armazenar ficheiros carregados no Cloudflare R2

Armazenar ficheiros carregados, fotos e backups no Cloudflare R2 mantém o disco do VPS limpo e leve. O TREK suporta backends compatíveis com S3, e o Cloudflare R2 encaixa-se perfeitamente nisto.

1. Crie um bucket R2 chamado trek.
2. Na secção Account Details, encontre o ID da sua conta:
3. Clique em Manage API Tokens:
4. Clique em Create Account API token com permissões de leitura/escrita para o bucket:
5. Clique em Storage no painel de ADMINISTRATION:
6. Clique no botão Add Backend e preencha o endpoint, o bucket e as credenciais:
7. Clique em Apply e depois no botão Test. Deverá ver a mensagem "Connection OK":
8. Altere todas as categorias de armazenamento para Cloudflare R2 e clique em Save changes:

3.3 Login com chaves de acesso (Passkeys)

O TREK suporta chaves de acesso, autenticação de dois fatores (2FA) e autenticação única (SSO) via OIDC. Para chaves de acesso, introduza o seu nome de domínio e as origens permitidas (allowed origins) nas definições e clique em Save:

Sem configurar as allowed origins, o registo da chave de acesso falhará.

3.4 Chave de API do Google Maps

Uma chave do Google Maps enriquece a pesquisa de locais com classificações, horários de funcionamento e fotos. O TREK reverte automaticamente para o OpenStreetMap caso não seja inserida nenhuma chave, contudo as classificações e fotos não estarão disponíveis.

Siga este link e clique em Get demo key para solicitar uma:

Cole a chave nas definições e clique em Test para confirmar a ligação:

3.5 Integração de IA

O modelo de IA é utilizado para recuperar e estruturar e-mails de confirmação e PDFs de reserva em dados de reserva estruturados.

Clique em Addons no menu esquerdo e ative AI Parsing. Selecione "OpenAI" (ou outro fornecedor compatível) e preencha as informações do mesmo:

3.6 Acesso MCP

Sob Addons, ative o MCP:

3.7 Plugins

Os seguintes plugins são recomendados e vale a pena ativá-los:

3.8 Criar o seu utilizador para o dia a dia

Planeie as viagens como um utilizador normal, não como administrador. Crie um utilizador regular e inicie sessão com ele:

Depois de iniciar sessão, adicione uma chave de acesso ou configure a autenticação de dois fatores (2FA) para reforçar a segurança da conta:

Clique em + Add a passkey, introduza a senha atual e confirme:

4. Testar a implantação: importar dados de viagens passadas

Uma excelente forma de explorar o TREK é registar o seu histórico de viagens.

4.1 Criar a viagem

Clique em + New Trip e configure a data de início (Start Date) e data de fim (End Date) com as datas passadas do seu passeio:

Adicione uma foto de capa (arraste uma ou cole do seu área de transferência) e clique em Create New Trip:

4.2 Importar as reservas

Arraste e solte todos os ficheiros de voos, comboios e outros meios de transporte:

Com o modelo de IA ativado, os PDFs de confirmação de reservas são analisados e estruturados automaticamente.

Reveja o resultado do processamento e clique em Add para registar os detalhes da reserva:

Se uma reserva estiver apenas num e-mail, exporte o e-mail como PDF e carregue-o — aplica-se o mesmo fluxo de extração por IA.

As capturas de ecrã seguintes mostram como as reservas são apresentadas:

Na página Plan, todos os alojamentos serão indicados no mapa:

Clique em Atlas na barra de menu superior para aceder à lista (e mapa) de todos os países que já visitou:

4.3 Adicionar companheiros de viagem

Clique no botão Share:

Na parte inferior de la janela, é possível adicionar convidados:

4.4 Registar as despesas

Clique em Add expense para registar despesas adicionais que não sejam reservas, tais como seguro de saúde, transporte local ou cartões SIM:

4.5 Segmentos da viagem

Esta funcionalidade requer que o plugin Trip Segment esteja instalado.

As viagens longas são divididas de forma elegante em segmentos, cada etapa exibindo as suas próprias reservas, pontos turísticos e custos:

4.6 Criar um diário de viagem (Journey) e consultar o seu atlas

Agrupe as suas viagens num Journey (diário de rota) e escreva relatos para partilhar as aventuras com os seus amigos:

5. Desenhar itinerários personalizados e listas de bagagem

Clique em + New Trip, introduza um nome e configure as datas:

Se ainda não definiu as datas do seu roteiro, deixe ambos os campos em branco. Irá surgir um campo indicando o "número de dias" (até 365). Planeie primeiro, defina as datas mais tarde.

5.1 Adicionar locais

Este costuma ser o passo mais moroso de qualquer planeamento de viagem, e o TREK tem várias formas de acelerá-lo:

1. Clique com o botão direito no mapa para criar um local nessa posição exata (o endereço é geocodificado de forma reversa automaticamente):

2. Clique em + Add Place/Activity e pesquise por nome:

3. Cole um URL do Google Maps (maps.app.goo.gl/… ou maps.google.com/…) no campo de pesquisa. O TREK extrairá o nome, o endereço e as coordenadas automaticamente:

4. Importação em lote — o caminho mais simples. Se já tem uma lista de locais pendentes no Google Maps, exporte-a como .gpx (os formatos .kml e .kmz também funcionam) e clique em Import file no painel direito para carregar tudo de uma só vez:

Adicione primeiro todos os pontos de interesse, independentemente de caberem ou não na agenda. Pode distribuí-los por dias específicos mais tarde.

5.2 Planos diários e notas

O plano diário organiza os locais por dias sequenciais. É uma lista desdobrável por cada dia, e tudo funciona com o recurso de arrastar e soltar:

Os detalhes essenciais que fazem a diferença:

• Transporte entre paragens: o ícone de autocarro no canto superior esquerdo de um dia adiciona transportes intermédios (comboios, autocarros ou voos dentro do mesmo dia):
• Notas do diárias: o ícone de notas no canto inferior esquerdo adiciona notas identificadas com emojis — "arranque matinal hoje", "este museu necessita de reserva prévia":
• Horários definidos: arraste um local do painel direito para um dia e atribua-lhe uma hora. Os locais com horário definido são ligados automaticamente no mapa:
• Consulte a página wiki de Planos Diários e Notas para mais informações sobre Otimização de rotas e o Clima.

5.3 Coleções: listas de locais reutilizáveis

As Coleções permitem aos utilizadores guardar listas de locais independentemente de qualquer viagem. Podem ser partilhadas com amigos e estarem preparadas para a próxima jornada. Os locais são copiados para as viagens, pelo que a edição de um ponto num itinerário nunca altera a sua coleção original e vice-versa.

Clique em Collections na barra de menu superior:

Clique em + New list para criar uma nova:

Clique em + Add a place e preencha os dados:

Nota: a barra de pesquisa dentro da janela "Add a place" parece não funcionar, pelo que terá de inserir os detalhes manualmente.

Si as coordenadas geográficas dos locais estiverem disponíveis, estes aparecerão no mapa:

Para organizar os locais com etiquetas (labels), clique no ícone da caixa de seleção:

Selecione os locais que pretende agrupar e clique em Assign label:

Clique em Manage labels para criar as etiquetas de antemão:

Selecione uma etiqueta e clique em Assign label:

5.4 Custos e orçamento

Podemos registar outras despesas para a viagem na página 'Costs'.

Os pagamentos efetuados por companheiros de viagem podem ser adicionados e divididos nessa mesma página.

O painel de acertos executa um algoritmo voraz (greedy) para calcular o número mínimo de transferências necessárias para liquidar as despesas entre os membros.

6. Aproveitar o Model Context Protocol (MCP) para Planeamento de Viagens com IA

O TREK possui um servidor MCP (Model Context Protocol) integrado, o que permite que agentes de IA leiam e editem diretamente os seus dados de viagem — com mais de 150 ferramentas e 30 recursos para itinerários, pontos de interesse, orçamentos, bagagem, reservas e colaboração.

6.1 Cloudflare Zero Trust

Devido ao facto de o TREK correr atrás de uma rede Cloudflare Zero Trust, terá de adicionar o seu domínio à lista de inclusão do Split Tunnels. Caso contrário, terá problemas com a autorização OAuth. Consulte este ticket do GitHub: issue do github.

Guia relacionado

Expor o Hermes Agent em rede privada com Cloudflare WARP

Aprenda a expor e acessar globalmente seu Hermes Agent de forma segura com o Cloudflare WARP e o Zero Trust, sem abrir portas de entrada em seu firewall.

9 MIN DE LEITURA

6.2 Claude Desktop

Clique em + New Client para criar um novo cliente de agente de IA:

Selecione o separador Claude Desktop e clique em Register Client:

É apresentado um ID de cliente e segredo de cliente. Guarde-os num local seguro. De seguida, clique em Client Configuration para mostrar as definições do MCP:

No Claude Desktop, clique em Edit Config para abrir o ficheiro local de configuração dos servidores MCP:

Cole a configuração do TREK, substituindo os marcadores de posição pelas suas credenciais:

  "mcpServers": {
    "trek": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://trek.pafor.me/mcp",
        "--static-oauth-client-info",
        "{\"client_id\": \"<your_client_id>\", \"client_secret\": \"<your_client_secret>\"}"
      ]
    }
  },

Reinicie o Claude Desktop, e o servidor do TREK passará a ser exibido como ligado em Local MCP servers:

Agora envie uma instrução (prompt):

Vamos adicionar uma despesa usando linguagem natural:

For the West Europe trip, the Grab from KLIA1 to the hotel cost RM115.90 on 26/4/2025. Please add it as an expense without split to the trip.

Ao verificar a página Costs, a despesa surge criada com a indicação "Ninguém pagou ainda", uma vez que nenhum pagador foi mencionado na ordem:

Adicionar elementos à lista de bagagem funciona exatamente da mesma maneira:

Atualize a página Packing List e verá os três elementos adicionados:

6.3 Gemini CLI (registo dinâmico)

A Gemini CLI suporta registo dinâmico, pelo que não necessita de um cliente pré-criado. Adicione isto a .gemini/settings.json:

    "trek": {
      "httpUrl": "https://trek.pafor.me/mcp",
      "oauth": {
        "enabled": true
      }
    }

Execute gemini no terminal e clique em Approve quando a janela de autorização surgir:

De seguida, comece com uma instrução simples:

6.4 Kimi CLI (registo dinâmico)

A mesma abordagem — adicione ao ficheiro mcp.json na pasta /Users/<user>/.kimi/:

    "trek": {
      "type": "http",
      "url": "https://trek.pafor.me/mcp",
      "auth": "oauth"
    }

Execute kimi mcp auth trek no terminal e clique em Approve:

Uma vez autorizado, as ferramentas disponíveis são listadas:

7. Experiência móvel

O TREK é uma PWA (progressive web app) em dispositivos móveis. Um service worker guarda em cache os mapas e os dados das APIs, para que o seu itinerário continue legível mesmo sem ligação à Internet. No entanto, as notificações push podem apresentar alguma latência em comparação com uma aplicação nativa.

Considerações finais

Ligar agentes de IA através de MCP poupa grande parte do cansativo trabalho de inserção manual de reservas de voos e hotéis. Além disso, os agentes podem sugerir pontos de interesse com base nas datas e na época do ano em que viaja. Uma única conversa com um agente de IA pode cobrir todo o processo, desde a pesquisa e criação do itinerario até ao controlo de orçamento e à preparação da bagagem.

Há alguns pequenos pormenores técnicos por ajustar. Por exemplo, ao importar reservas a partir de ficheiros PDF, a moeda assume por omissão a moeda base da viagem em vez da moeda efetivamente paga. Além disso, ao criar uma nova lista em Coleções, qualquer imagem de capa associada durante a criação desaparece ao guardar, embora possa ser readicionada manualmente na edição posterior.

Existe uma ligeira barreira técnica, pois necessita de alojar o sistema no seu próprio servidor. O TREK foi concebido principalmente para pessoas que viajam com frequência e têm elevadas expectativas sobre a organização dos seus dados de viagem. Sugerimos que experimente a demonstração oficial em demo.liketrek.com antes de equacionar o autohospedamento.

Referências:

• Início rápido do TREK
• Resolução de problemas do TREK
• Escopos MCP do TREK