For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/guide/quick-start.md.
  • English
  • Docker Compose Quick Start

    Public Beta Notice

    Yearning v4.0 is currently in Public Beta. Please deploy in staging or evaluation environments first, and always back up the PostgreSQL data volume and keyring.json before testing with important data.

    Yearning v4 ships an all-in-one docker-compose.yml that bootstraps PostgreSQL 18, internal PostgreSQL TLS certificates, a 6-purpose AES-256-GCM AEAD keyring, automated versioned schema migrations, and the Yearning v4 control plane with embedded React UI in a single command.

    Prerequisites

    • Docker Engine 24+ and Docker Compose v2
    • Available port 8080 (override with YEARNING_PORT)
    • Minimum 2 vCPU / 2 GiB RAM (4 GiB+ recommended for large batch SQL fingerprinting)

    Launch in Three Commands

    # 1. Clone the v4 branch
    git clone --single-branch --branch v4 https://github.com/cookieY/Yearning.git
    cd Yearning
    
    # 2. (Optional) Customize the initial admin password (min 12 chars) and port
    export YEARNING_ADMIN_PASSWORD="YourStrongPassword@2026!"
    export YEARNING_PORT="8080"
    
    # 3. Start the full stack
    docker compose up -d

    Verify startup health:

    docker compose ps
    docker compose logs -f yearning

    Open http://<your-host-ip>:8080:

    • Default admin username: admin
    • Default initial password: Yearning@2026! (or your YEARNING_ADMIN_PASSWORD)
    Recommended First-Boot Checklist
    1. Add and test at least one OpenAI-compatible AI Provider in Review Engine -> Providers (/admin/review-engine/providers).
    2. Compose a Rule Set in /admin/rule-sets from built-in or custom skills.
    3. Register target databases in Admin -> Datasources (/admin/datasources) with separated read-only and execution credentials.
    4. Create change_review and query_access flows in /admin/flows and assign them via Permission Groups (/admin/permission-groups). :::

    Service Topology

    ServicePurposeSecret & Privilege Boundary
    bootstrapIdempotent one-shot initializerGenerates internal PG TLS certs, 6-purpose keyring.json, and initial admin password file
    postgresPostgreSQL 18 metadata storeMounts TLS server cert/key only (ssl=on); zero access to the application keyring
    migrateOne-shot versioned migration JobRuns yearning migrate apply non-root with read-only rootfs and validates the column catalog
    yearningControl plane + embedded Web UIRuns yearning serve in a Distroless read-only container mounting read-only secrets

    :::danger Never run docker compose down -v during upgrades Deleting the yearning_app_secrets volume permanently destroys your AEAD keyring (keyring.json), making all encrypted datasource passwords, AI provider keys, order SQL payloads, and rollback artifacts undecryptable.

    Production Hardening Checklist

    1. Terminate HTTPS in front of Yearning (Nginx / Envoy / Ingress) and set YEARNING_ENVIRONMENT=production plus YEARNING_SESSION_SECURE=true.
    2. Configure YEARNING_TRUSTED_PROXIES so audit trails capture real client IP addresses.
    3. Provision PostgreSQL 3-role isolation (yearning_app, yearning_migrator, yearning_retention) and supply YEARNING_RETENTION_DATABASE_DSN. See Kubernetes Production Deployment.
    4. Back up keyring.json in an external KMS or encrypted vault alongside PostgreSQL backups.