pal-e-docs

Deployment: intelligentstaffingsystems

arch-deployment-iss Architecture

architecture active
Project

Deployment: intelligentstaffingsystems

Diagram




          
  
Components



          
  

    

        
          

              Component
              Purpose
              Notes
          

        
      
          

              <strong>rails</strong>
              Rails application server (Puma)
              Port 3000 production, 9999 local dev. Image: intelligentstaffingsystems/intelligentstaffingsystems in Harbor.
          

          

              <strong>infra</strong>
              Platform infrastructure (k3s cluster + edge)
              Self-hosted on Hetzner. All components below are infra.
          

          

              Caddy
              TLS termination, reverse proxy
              Runs on Hetzner VPS, proxies to k3s via Tailscale mesh
          

          

              PostgreSQL
              Primary database
              CNPG-managed, iss namespace. Backups to MinIO.
          

          

              Keycloak
              SSO/OIDC
              Realm: iss. Client: intelligentstaffingsystems. PKCE enforced.
          

          

              Forgejo
              Git hosting
              Tailnet-only access
          

          

              Woodpecker CI
              CI pipelines
              Triggered by Forgejo webhooks (push events)
          

          

              Harbor
              Container registry
              Project: intelligentstaffingsystems. Robot accounts for push/pull.
          

          

              ArgoCD
              GitOps deployment
              Syncs from pal-e-deployments overlays/intelligentstaffingsystems/
          

          

              Image Updater
              Tag detection
              Polls Harbor, writes new tag to pal-e-deployments via git commit
          

          

              Postmark
              Transactional email
              The one managed dependency. Single API token.
          

          

              App Store
              Payment collection
              Apple handles subscriptions. No PCI surface.
          

      
    

  



          
  
Key Decisions



          
  
    
      
  • Fully self-hosted except email — Postmark is the only managed dependency. Everything else (Git, CI, registry, GitOps, SSO, database) runs on the cluster. Trades operational complexity for full ownership.
    • 
      
  • Three-repo model — pal-e-platform (infra provisioning), pal-e-services (per-service automation), pal-e-deployments (Kustomize overlays). Separation of concerns: infra changes don't touch app config.
    • 
      
  • Caddy edge on Hetzner — public traffic enters via a VPS, not directly into the cluster. Caddy handles TLS + reverse proxy; Tailscale mesh connects to k3s. Adds a hop but keeps the cluster off the public internet.
    • 
      
  • SOPS-encrypted secrets in git — all secrets live in pal-e-deployments as SOPS-encrypted YAML. ArgoCD decrypts at sync time. No external secrets manager.
    • 
      
  • App Store for payments — Apple collects $800/month subscriptions. Guaranteed collection (no app access without payment), no PCI surface, at the cost of Apple's commission.
    • 
      
  • Image Updater writes to git — rather than ArgoCD polling the registry directly, Image Updater commits the new tag to pal-e-deployments. GitOps purity: the git repo is always the source of truth for what's deployed.
    • 



          
  


          
  
    
      
  • arch-domain-iss — entity relationships
    • 
      
  • arch-dataflow-iss — runtime data flow
    • 
      
  • project-iss — project page
    • 
      
  • sop-secrets-management — SOPS workflow
    • 
      
  • deployment-lessons — lessons learned from deploy issues
    •