[{"data":1,"prerenderedAt":461},["ShallowReactive",2],{"navigation":3,"\u002Finstallation\u002Fupgrades":194,"\u002Finstallation\u002Fupgrades-surround":456},[4,18,31,64,81,102,111,132,149],{"title":5,"path":6,"stem":7,"children":8,"page":17},"Getting started","\u002Fgetting-started","1.getting-started",[9,13],{"title":10,"path":11,"stem":12},"Introduction","\u002Fgetting-started\u002Fintroduction","1.getting-started\u002F1.introduction",{"title":14,"path":15,"stem":16},"Run your first workflow","\u002Fgetting-started\u002Fquickstart","1.getting-started\u002F2.quickstart",false,{"title":19,"path":20,"stem":21,"children":22,"page":17},"Core concepts","\u002Fconcepts","2.concepts",[23,27],{"title":24,"path":25,"stem":26},"The platform model","\u002Fconcepts\u002Fplatform","2.concepts\u002F1.platform",{"title":28,"path":29,"stem":30},"Architecture and boundaries","\u002Fconcepts\u002Farchitecture","2.concepts\u002F2.architecture",{"title":32,"path":33,"stem":34,"children":35,"page":17},"Installation","\u002Finstallation","3.installation",[36,40,44,48,52,56,60],{"title":37,"path":38,"stem":39},"Overview and requirements","\u002Finstallation\u002Foverview","3.installation\u002F1.overview",{"title":41,"path":42,"stem":43},"Local evaluation","\u002Finstallation\u002Flocal-evaluation","3.installation\u002F2.local-evaluation",{"title":45,"path":46,"stem":47},"Install the server","\u002Finstallation\u002Fserver","3.installation\u002F3.server",{"title":49,"path":50,"stem":51},"Install a runner","\u002Finstallation\u002Frunner","3.installation\u002F4.runner",{"title":53,"path":54,"stem":55},"Verify the installation","\u002Finstallation\u002Fverification","3.installation\u002F5.verification",{"title":57,"path":58,"stem":59},"Upgrade the platform","\u002Finstallation\u002Fupgrades","3.installation\u002F6.upgrades",{"title":61,"path":62,"stem":63},"Guided installer","\u002Finstallation\u002Finstaller","3.installation\u002F7.installer",{"title":65,"path":66,"stem":67,"children":68,"page":17},"Build workflows","\u002Fworkflows","4.workflows",[69,73,77],{"title":70,"path":71,"stem":72},"Build a Definition","\u002Fworkflows\u002Fdefinitions","4.workflows\u002F0.definitions",{"title":74,"path":75,"stem":76},"Deploy and run workflows","\u002Fworkflows\u002Fruns","4.workflows\u002F1.runs",{"title":78,"path":79,"stem":80},"Inputs, context, and secrets","\u002Fworkflows\u002Finputs-and-secrets","4.workflows\u002F2.inputs-and-secrets",{"title":82,"path":83,"stem":84,"children":85,"page":17},"Run and recover","\u002Foperations","5.operations",[86,90,94,98],{"title":87,"path":88,"stem":89},"Monitor Runs","\u002Foperations\u002Fmonitoring","5.operations\u002F1.monitoring",{"title":91,"path":92,"stem":93},"Approve prepared steps","\u002Foperations\u002Fapprovals","5.operations\u002F2.approvals",{"title":95,"path":96,"stem":97},"Recover or cancel execution","\u002Foperations\u002Frecovery","5.operations\u002F3.recovery",{"title":99,"path":100,"stem":101},"Troubleshooting","\u002Foperations\u002Ftroubleshooting","5.operations\u002F4.troubleshooting",{"title":103,"path":104,"stem":105,"children":106,"page":17},"Action catalog","\u002Fcatalog","6.catalog",[107],{"title":108,"path":109,"stem":110},"Find and use Actions","\u002Fcatalog\u002Foverview","6.catalog\u002F1.overview",{"title":112,"path":113,"stem":114,"children":115,"page":17},"Administration","\u002Fadministration","7.administration",[116,120,124,128],{"title":117,"path":118,"stem":119},"Registries and Environments","\u002Fadministration\u002Fenvironments","7.administration\u002F2.environments",{"title":121,"path":122,"stem":123},"Manage runners","\u002Fadministration\u002Frunners","7.administration\u002F3.runners",{"title":125,"path":126,"stem":127},"Access and approval policies","\u002Fadministration\u002Faccess","7.administration\u002F4.access",{"title":129,"path":130,"stem":131},"Backups and upgrades","\u002Fadministration\u002Fmaintenance","7.administration\u002F5.maintenance",{"title":133,"path":134,"stem":135,"children":136,"page":17},"Develop Actions","\u002Factions","8.actions",[137,141,145],{"title":138,"path":139,"stem":140},"Build your first Action","\u002Factions\u002Fquickstart","8.actions\u002F1.quickstart",{"title":142,"path":143,"stem":144},"Local development","\u002Factions\u002Flocal-development","8.actions\u002F2.local-development",{"title":146,"path":147,"stem":148},"Publish an Action","\u002Factions\u002Fpublishing","8.actions\u002F3.publishing",{"title":150,"path":151,"stem":152,"children":153,"page":17},"Reference","\u002Freference","9.reference",[154,158,162,166,170,174,178,182,186,190],{"title":155,"path":156,"stem":157},"Operator CLI","\u002Freference\u002Foperator-cli","9.reference\u002F1.operator-cli",{"title":159,"path":160,"stem":161},"Installer CLI","\u002Freference\u002Finstaller-cli","9.reference\u002F10.installer-cli",{"title":163,"path":164,"stem":165},"Definition syntax","\u002Freference\u002Fdefinition","9.reference\u002F2.definition",{"title":167,"path":168,"stem":169},"CLI configuration","\u002Freference\u002Fconfiguration","9.reference\u002F3.configuration",{"title":171,"path":172,"stem":173},"API integration","\u002Freference\u002Fapi","9.reference\u002F4.api",{"title":175,"path":176,"stem":177},"Action CLI","\u002Freference\u002Faction-cli","9.reference\u002F5.action-cli",{"title":179,"path":180,"stem":181},"Action SDK","\u002Freference\u002Fsdk","9.reference\u002F6.sdk",{"title":183,"path":184,"stem":185},"Contracts and compatibility","\u002Freference\u002Fcontracts","9.reference\u002F7.contracts",{"title":187,"path":188,"stem":189},"Server configuration","\u002Freference\u002Fserver-configuration","9.reference\u002F8.server-configuration",{"title":191,"path":192,"stem":193},"Runner configuration","\u002Freference\u002Frunner-configuration","9.reference\u002F9.runner-configuration",{"id":195,"title":57,"body":196,"description":450,"extension":451,"meta":452,"navigation":453,"path":58,"seo":454,"stem":59,"__hash__":455},"docs\u002F3.installation\u002F6.upgrades.md",{"type":197,"value":198,"toc":443},"minimark",[199,203,206,211,240,252,256,267,297,300,310,330,333,337,353,356,376,379,394,398,405,420,423,427,430,439],[200,201,202],"p",{},"Server and runner ship together in a platform release. Upgrade them to the same target version. The operator CLI and Action tooling belong to a separate tooling release; consult the supported combination and release notes rather than assuming their numeric versions must match.",[200,204,205],{},"Use the version selector to review the target release's installation\u002Fconfiguration instructions. Test representative workflows in an isolated installation before changing a shared service.",[207,208,210],"h2",{"id":209},"prepare-a-maintenance-window","Prepare a maintenance window",[212,213,214,218,221,224,237],"ol",{},[215,216,217],"li",{},"Stop new operational submissions through your team's maintenance process; there is no installation-wide maintenance-mode command.",[215,219,220],{},"Inspect Runs, settle active work, and reconcile any uncertain execution with its owning runner.",[215,222,223],{},"Stop the runners, then stop the server. Retain runner work volumes and identities.",[215,225,226,227,231,232,236],{},"Take a consistent backup of the ",[228,229,230],"strong",{},"complete"," server data directory, including its encryption key, logs, database, and NATS state. Preserve runner state separately. Follow ",[233,234,235],"a",{"href":130},"backup and recovery guidance",".",[215,238,239],{},"Retain the previous artifact versions and record the new platform\u002Ftooling pair.",[200,241,242,243,247,248,251],{},"An idle, approved, non-ephemeral runner can be stopped normally and restarted with the same identity. If you explicitly used ",[244,245,246],"code",{},"pyplines runner drain",", that identity remains administratively draining: the current server does not implement resume. Follow ",[233,249,250],{"href":122},"runner replacement guidance",", enrolling a new identity with a separate work volume after the old one has settled. Do not erase old state to force replacement.",[207,253,255],{"id":254},"upgrade-container-deployments","Upgrade container deployments",[200,257,258,259,262,263,266],{},"On the server host, update ",[244,260,261],{},"PLATFORM_VERSION"," in its ",[244,264,265],{},".env"," to the selected plain version. With services already stopped and the backup complete:",[268,269,275],"pre",{"className":270,"code":271,"filename":272,"language":273,"meta":274,"style":274},"language-sh shiki shiki-themes pyplines-light pyplines-light pyplines-dark","docker compose pull server\ndocker compose up -d server\ndocker compose logs --tail 100 server\n","Terminal","sh","",[244,276,277,285,291],{"__ignoreMap":274},[278,279,282],"span",{"class":280,"line":281},"line",1,[278,283,284],{},"docker compose pull server\n",[278,286,288],{"class":280,"line":287},2,[278,289,290],{},"docker compose up -d server\n",[278,292,294],{"class":280,"line":293},3,[278,295,296],{},"docker compose logs --tail 100 server\n",[200,298,299],{},"The new server opens the existing data volume and applies database migrations. Check HTTPS health and administrator login before starting runners.",[200,301,302,303,305,306,309],{},"On each runner host, set its ",[244,304,265],{}," to the ",[228,307,308],{},"same"," platform version:",[268,311,313],{"className":270,"code":312,"filename":272,"language":273,"meta":274,"style":274},"docker compose pull runner\ndocker compose up -d runner\ndocker compose logs --tail 100 runner\n",[244,314,315,320,325],{"__ignoreMap":274},[278,316,317],{"class":280,"line":281},[278,318,319],{},"docker compose pull runner\n",[278,321,322],{"class":280,"line":287},[278,323,324],{},"docker compose up -d runner\n",[278,326,327],{"class":280,"line":293},[278,328,329],{},"docker compose logs --tail 100 runner\n",[200,331,332],{},"Retain the original state volume and server URL for a normally stopped runner. It reuses its saved identity without a new enrollment token. Do not run mixed server\u002Frunner versions as an assumed rolling-upgrade strategy; such compatibility is not promised by these guides.",[207,334,336],{"id":335},"upgrade-linux-services","Upgrade Linux services",[200,338,339,340,344,345,349,350,236],{},"Download and verify both target binaries using the procedure in ",[233,341,343],{"href":342},"\u002Finstallation\u002Fserver#option-b-linux-service","server installation"," and ",[233,346,348],{"href":347},"\u002Finstallation\u002Frunner#option-b-linux-service","runner installation",". Stop services and back up their data before replacing binaries in ",[244,351,352],{},"\u002Fusr\u002Flocal\u002Fbin",[200,354,355],{},"Opening the server applies migrations automatically. To run them explicitly while the server is stopped:",[268,357,359],{"className":270,"code":358,"filename":272,"language":273,"meta":274,"style":274},"sudo -u pyplines-server \u002Fusr\u002Flocal\u002Fbin\u002Fpyplines-server migrate --data \u002Fvar\u002Flib\u002Fpyplines\nsudo systemctl start pyplines-server\nsudo journalctl -u pyplines-server -n 100 --no-pager\n",[244,360,361,366,371],{"__ignoreMap":274},[278,362,363],{"class":280,"line":281},[278,364,365],{},"sudo -u pyplines-server \u002Fusr\u002Flocal\u002Fbin\u002Fpyplines-server migrate --data \u002Fvar\u002Flib\u002Fpyplines\n",[278,367,368],{"class":280,"line":287},[278,369,370],{},"sudo systemctl start pyplines-server\n",[278,372,373],{"class":280,"line":293},[278,374,375],{},"sudo journalctl -u pyplines-server -n 100 --no-pager\n",[200,377,378],{},"Once the server is healthy, start the runner on each host:",[268,380,382],{"className":270,"code":381,"filename":272,"language":273,"meta":274,"style":274},"sudo systemctl start pyplines-runner\nsudo journalctl -u pyplines-runner -n 100 --no-pager\n",[244,383,384,389],{"__ignoreMap":274},[278,385,386],{"class":280,"line":281},[278,387,388],{},"sudo systemctl start pyplines-runner\n",[278,390,391],{"class":280,"line":287},[278,392,393],{},"sudo journalctl -u pyplines-runner -n 100 --no-pager\n",[207,395,397],{"id":396},"verify-before-resuming-operations","Verify before resuming operations",[200,399,400,401,404],{},"Check reported component versions, runner admission and heartbeats, retained historical Runs, and the ",[233,402,403],{"href":54},"verification workflow",". Upgrade workstation tooling separately when the selected supported combination requires it:",[268,406,408],{"className":270,"code":407,"filename":272,"language":273,"meta":274,"style":274},"python -m pip install --upgrade \"pyplines-cli==$TOOLING_VERSION\"\npyplines version\n",[244,409,410,415],{"__ignoreMap":274},[278,411,412],{"class":280,"line":281},[278,413,414],{},"python -m pip install --upgrade \"pyplines-cli==$TOOLING_VERSION\"\n",[278,416,417],{"class":280,"line":287},[278,418,419],{},"pyplines version\n",[200,421,422],{},"Existing Action images carry their SDK\u002Fruntime; a CLI upgrade does not rebuild them. Update Action dependencies and republish only when required by that Action's maintenance or compatibility requirements.",[207,424,426],{"id":425},"recovery-after-an-unsuccessful-upgrade","Recovery after an unsuccessful upgrade",[200,428,429],{},"Stop accepting work and preserve the failed installation's state for investigation. An older server binary is not guaranteed to understand a migrated database; changing the image tag back is not a complete rollback procedure.",[200,431,432,433,344,436,236],{},"Restore only a compatible, complete backup in a controlled recovery process. Server state may lag effects already performed in external systems. Reconcile those effects and the owning runners before enabling new work. See ",[233,434,435],{"href":130},"backups",[233,437,438],{"href":96},"execution recovery",[440,441,442],"style",{},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":274,"searchDepth":287,"depth":287,"links":444},[445,446,447,448,449],{"id":209,"depth":287,"text":210},{"id":254,"depth":287,"text":255},{"id":335,"depth":287,"text":336},{"id":396,"depth":287,"text":397},{"id":425,"depth":287,"text":426},"Replace server and runner artifacts while preserving execution state and a supported tooling combination.","md",{},true,{"title":57,"description":450},"byf0Hb9CRHFPadBogcE0r_5qaYwpZ5kPeTkG6hsTMW8",[457,459],{"title":53,"path":54,"stem":55,"description":458,"children":-1},"Connect a registry and Environment, execute a known Action, and check retained evidence.",{"title":61,"path":62,"stem":63,"description":460,"children":-1},"Configure and install Pyplines services and development tools from one YAML document.",1792213697213]