pal-e-docs

Deployment: gdocs-daily-mcp-remote

arch-deployment-gdocs-daily-mcp-remote Architecture

architecture draft
Project

Deployment: gdocs-daily-mcp-remote

Diagram

Components

Component Purpose Notes
Tailscale Funnel Public HTTPS ingress Terminates TLS. Hostname: <code>gdocs-daily-mcp-remote.tail5b443a.ts.net</code>. No cert-manager needed — Tailscale handles certs.
Ingress (tailscale class) k8s Ingress resource with funnel annotation Created by pal-e-services Terraform. <code>tailscale.com/funnel: "true"</code>. Auth required per <code>feedback_funnel_requires_auth</code>.
Service ClusterIP routing to pod Port 8000. No LoadBalancer needed — Tailscale operator handles external access.
Deployment Single-replica pod running Uvicorn Recreate strategy (token file is stateful). Image from Harbor. Resources: 32Mi request, 256Mi limit.
PVC Persistent encrypted token storage Stores Fernet-encrypted tokens.json. Survives pod restarts. local-path provisioner.
Secret OAuth credentials and session key Contains: Google OAuth client_id/secret, session_secret, onboard_secret, base_url.
Harbor Container image registry Project: <code>gdocs-daily-mcp-remote</code>. CI robot pushes, pull robot for imagePullSecrets.
ArgoCD GitOps deployment Watches pal-e-deployments overlay. Image Updater auto-detects new tags (regex: <code>^[0-9a-f]{7,40}$</code>).
Woodpecker CI Build pipeline Triggered on push to main. Kaniko builds Dockerfile.k8s, pushes to Harbor with git SHA tag.
Forgejo repo Source code <code>forgejo_admin/gdocs-daily-mcp-remote</code>. Contains server code + .woodpecker.yaml.
pal-e-deployments overlay Kustomize overlay for prod Inherits from bases/standard. Patches deployment name, image, probes, secrets.

Key Decisions

  • Tailscale funnel, not Traefik. Platform convention — all public ingress goes through Tailscale funnels. No cert-manager, no separate TLS config. Funnel requires auth (OAuth satisfies this — unauthenticated requests get redirected to Google consent).
  • Single replica with Recreate. Token store is a local encrypted file. No shared state backend. Scaling would require migrating to Redis or a database — unnecessary for a single-user MCP server.
  • Kustomize overlay in pal-e-deployments, not in-repo. Following the established pattern — k8s manifests for ArgoCD live in the shared deployments repo. The service repo contains only the app code and CI config.
  • Service onboarding via pal-e-services Terraform. One entry in k3s.tfvars creates: Harbor project + robots, k8s namespace, image pull secret, ArgoCD app, Tailscale funnel ingress. Then tofu apply.
  • Google OAuth web credentials. New OAuth client in the same GCP project (233869493443) with redirect URI https://gdocs-daily-mcp-remote.tail5b443a.ts.net/oauth/callback. Scopes: documents.readonly + drive.readonly.

Onboarding Checklist

  • Create Forgejo repo forgejo_admin/gdocs-daily-mcp-remote
  • Create Google OAuth web credentials in GCP console (new client, same project)
  • Add service entry to pal-e-services/terraform/k3s.tfvars, run tofu apply -lock=false
  • Create kustomize overlay in pal-e-deployments/overlays/gdocs-daily-mcp-remote/prod/
  • Create k8s Secret with OAuth creds + session secret
  • Push initial code → Woodpecker builds → Harbor → ArgoCD deploys
  • Run onboarding flow to pre-authorize Google account
  • Add MCP remote URL to Claude.ai settings
  • arch-domain-gdocs-daily-mcp-remote — entity model
  • arch-dataflow-gdocs-daily-mcp-remote — runtime sequence diagrams
  • story-gdocs-daily-mobile-daily-review — user story
  • service-onboarding-sop — SOP for adding new services to the platform