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/operations/binary-deploy.md.
  • English
  • Binary & Standalone PostgreSQL Deployment

    Deploy the single yearning binary directly with systemd against an existing HA PostgreSQL 14–18 cluster (RDS / Patroni / self-managed).

    1. Create PostgreSQL Least-Privilege Roles

    In production (environment: production), Yearning enforces database_role_self_check and rejects superuser, CREATEDB, postgres, or migrator roles on the runtime connection:

    CREATE ROLE yearning_schema_owner NOLOGIN;
    CREATE ROLE yearning_migrator LOGIN PASSWORD 'STRONG_MIGRATOR_PASS';
    CREATE ROLE yearning_app LOGIN PASSWORD 'STRONG_APP_PASS';
    CREATE ROLE yearning_retention LOGIN PASSWORD 'STRONG_RETENTION_PASS';
    CREATE ROLE yearning_migration_workbench LOGIN PASSWORD 'STRONG_WORKBENCH_PASS';
    
    CREATE DATABASE yearning OWNER yearning_schema_owner ENCODING 'UTF8';
    GRANT yearning_schema_owner TO yearning_migrator;

    2. Generate 6-Purpose keyring.json (0400 / 0440 required)

    sudo mkdir -p /etc/yearning/secrets /etc/yearning/tls
    sudo useradd --system --no-create-home --shell /usr/sbin/nologin yearning
    
    NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
    gen_key() { head -c 32 /dev/urandom | base64 | tr -d '\n'; }
    
    sudo tee /etc/yearning/secrets/keyring.json >/dev/null <<EOF
    {
      "contract_version": 1,
      "deployment_id": "yearning-prod-01",
      "keys": [
        {"key_id": "prod-k1-payload",  "purpose": "payload",               "status": "encrypt_decrypt", "created_at": "${NOW}", "key_base64": "$(gen_key)"},
        {"key_id": "prod-k1-sql-fp",   "purpose": "sql_fingerprint",       "status": "encrypt_decrypt", "created_at": "${NOW}", "key_base64": "$(gen_key)"},
        {"key_id": "prod-k1-identity", "purpose": "identifier_token",      "status": "encrypt_decrypt", "created_at": "${NOW}", "key_base64": "$(gen_key)"},
        {"key_id": "prod-k1-settings", "purpose": "settings_impact_token", "status": "encrypt_decrypt", "created_at": "${NOW}", "key_base64": "$(gen_key)"},
        {"key_id": "prod-k1-oidc",     "purpose": "oidc_state",            "status": "encrypt_decrypt", "created_at": "${NOW}", "key_base64": "$(gen_key)"},
        {"key_id": "prod-k1-affinity", "purpose": "cursor_affinity",       "status": "encrypt_decrypt", "created_at": "${NOW}", "key_base64": "$(gen_key)"}
      ]
    }
    EOF
    sudo chown yearning:yearning /etc/yearning/secrets/keyring.json
    sudo chmod 0400 /etc/yearning/secrets/keyring.json

    3. Apply Versioned Migrations & db/roles/grants.sql

    /opt/yearning/yearning migrate apply \
      --config /etc/yearning/migrate-schema.json \
      --migrations-dir /opt/yearning/db/migrations \
      --catalog /opt/yearning/api/contracts/postgresql-column-catalog.json
    
    PGPASSWORD="STRONG_MIGRATOR_PASS" psql \
      "host=pg.internal.example.com port=5432 dbname=yearning user=yearning_migrator sslmode=verify-full sslrootcert=/etc/yearning/tls/pg-ca.pem" \
      -f /opt/yearning/db/roles/grants.sql

    4. Runtime /etc/yearning/config.yaml & systemd Unit

    environment: production
    server:
      listen_address: 127.0.0.1:8080
      shutdown_grace_seconds: 20
    database:
      host: pg.internal.example.com
      port: "5432"
      user: yearning_app
      password: STRONG_APP_PASS
      dbname: yearning
      sslmode: verify-full
      sslrootcert: /etc/yearning/tls/pg-ca.pem
    retention:
      database_dsn: "host=pg.internal.example.com port=5432 dbname=yearning user=yearning_retention password=STRONG_RETENTION_PASS sslmode=verify-full sslrootcert=/etc/yearning/tls/pg-ca.pem"
    logging:
      level: info
      format: json
    observability:
      service_name: yearning
      deployment_id: yearning-prod-01
    session:
      cookie_name: yearning_session
      secure: true
    key_provider:
      kind: file
      path: /etc/yearning/secrets/keyring.json
    trusted_proxies:
      - 127.0.0.1/32

    Start with YEARNING_SCHEMA_MIGRATIONS_DIR=/opt/yearning/db/migrations /opt/yearning/yearning serve --config /etc/yearning/config.yaml --bootstrap-admin-password-file /etc/yearning/secrets/admin-password, verify GET /api/v4/health/ready, and place behind HTTPS Nginx with proxy_buffering off on /api/v4/events/stream.