Skip to content

architecture-overview.mdx

Latest commit

 

History

History
97 lines (72 loc) · 5.11 KB

architecture-overview.mdx

File metadata and controls

97 lines (72 loc) · 5.11 KB
title Architecture Overview
description See how the Pullbase server, agents, database, and Git repositories work together.

Pullbase orchestrates Git-driven configuration for traditional servers. Agents pull desired state from the central server, apply it locally, and report the results.

Components

Go application that exposes the REST API, web UI, and webhook endpoints. It manages environments, servers, tokens, audit logs, and status history. SQLite (default) for zero-config deployment, or PostgreSQL for scale. Stores configuration and operational data. Migrations run automatically on startup. Lightweight binary that authenticates with a scoped token, clones the config repo, reconciles packages/services/files, and reports drift. Contains `config.yaml` files. Environments point to a repo, branch, and path. Pullbase reads Git to compute the target commit hash.

Server internals

  • HTTP stack: REST APIs with middleware for authentication, CSRF protection, structured logging, and request tracing.
  • Data access: Database repository layer (SQLite or PostgreSQL) that stores environments, servers, tokens, rollbacks, users, and audit history.
  • Git monitor: Watches repositories for new commits via webhooks or polling and keeps the environment target commit current.
  • Webhook router: Validates HMAC signatures, queues events, and updates environment target commits immediately.
  • Audit logging: Actions like user creation, token issuance, and rollbacks are persisted for later review.

Agent internals

The agent is built with pluggable package and service managers:

Package managers (auto-detected):

  • APK (Alpine Linux)
  • APT (Debian, Ubuntu)
  • YUM/DNF (RHEL, CentOS, Rocky Linux, Fedora)

Service managers (auto-detected):

  • systemd (most modern distributions)
  • supervisor (Docker containers, custom setups)
  • OpenRC (Alpine Linux, Gentoo)

The system.serviceManager field in config.yaml can override auto-detection when needed.

Agent workflow

  1. Fetch public server info from GET /api/v1/serverinfo/{serverID} to get Git configuration.
  2. Authenticate with AGENT_TOKEN and fetch full server info via GET /api/v1/agent/serverinfo.
  3. Obtain a Git credential via GET /api/v1/agent/git-token if the environment uses a GitHub App.
  4. Clone or update the repository under /etc/pullbase/repo.
  5. Parse config.yaml and reconcile packages, services, and files using the detected managers.
  6. Post a status update to PUT /api/v1/agent/status, including commit hash, drift flag, and error messages.

Data flow overview

Git commit -> Webhook/polling updates target commit -> Agent polls server info -> Agent applies state -> Agent posts status
  • Merging a commit triggers a webhook (or is detected via polling).
  • Pullbase stores the new deployed_commit for the environment.
  • Agents poll on a fixed 60-second interval (configurable via PULLBASE_GIT_POLL_INTERVAL).
  • Agents reconcile to the new commit and report status history entries.
  • Operators review drift, roll back, or adjust configuration via Git.
  • Notification webhooks fire for drift or apply errors (when configured).

Network architecture

Pullbase Network Architecture

Pullbase supports two TLS approaches: (A) reverse proxy termination, or (B) native TLS via `PULLBASE_TLS_ENABLED=true`. For production, always use TLS. Agents connect to the HTTPS endpoint regardless of which approach you choose.

Scaling considerations

  • Single-node: SQLite is the default — no external database required. Perfect for single-instance deployments.
  • Production scale: Switch to PostgreSQL (PULLBASE_DB_TYPE=postgres) when you need high availability or manage hundreds of servers.
  • High availability: Run multiple Pullbase replicas behind a load balancer (requires PostgreSQL). Sessions are JWT-based and stateless.
  • Networking: Agents require outbound HTTPS to the reverse proxy and Git provider. Pullbase requires outbound HTTPS to Git provider (for GitHub Apps and webhooks).

Rollback mechanics

  • Rollbacks (POST /api/v1/environments/{id}/rollback) create a record, set the environment's deployed commit to the selected hash, and notify agents on their next poll.
  • Agents revert state to the specified commit. Package downgrades rely on package manager capabilities; test in staging before production rollbacks.

Observability hooks

  • Logs: Central server logs are structured (JSON when configured). Agents log reconciliation details at info/debug levels.
  • Health endpoint: /api/v1/healthz returns status and service name.
  • Future metrics: Prometheus metrics are on the roadmap; integrate container logs with your monitoring pipeline meanwhile.

Understanding these components prepares you for installation, environment management, and operational tasks described in subsequent guides.