[{"data":1,"prerenderedAt":2533},["ShallowReactive",2],{"navigation":3,"banner":339,"\u002Fdocs\u002Fgetting-started\u002Flicence-configuration":354,"\u002Fdocs\u002Fgetting-started\u002Flicence-configuration-surround":2528},[4,43,91,154,181,224,267,298],{"title":5,"path":6,"stem":7,"children":8,"icon":42},"Getting Started","\u002Fdocs\u002Fgetting-started","1.docs\u002F1.getting-started\u002F1.index",[9,12,17,22,27,32,37],{"title":10,"path":6,"stem":7,"icon":11},"Getting started","i-lucide-flag",{"title":13,"path":14,"stem":15,"icon":16},"Modules overview","\u002Fdocs\u002Fgetting-started\u002Fmodules-overview","1.docs\u002F1.getting-started\u002F2.modules-overview","i-lucide-boxes",{"title":18,"path":19,"stem":20,"icon":21},"Installation","\u002Fdocs\u002Fgetting-started\u002Finstallation","1.docs\u002F1.getting-started\u002F3.installation","i-lucide-download",{"title":23,"path":24,"stem":25,"icon":26},"Licence configuration","\u002Fdocs\u002Fgetting-started\u002Flicence-configuration","1.docs\u002F1.getting-started\u002F4.licence-configuration","i-lucide-key-round",{"title":28,"path":29,"stem":30,"icon":31},"Your first app","\u002Fdocs\u002Fgetting-started\u002Ffirst-app","1.docs\u002F1.getting-started\u002F5.first-app","i-lucide-square-play",{"title":33,"path":34,"stem":35,"icon":36},"Project setup","\u002Fdocs\u002Fgetting-started\u002Fproject-setup","1.docs\u002F1.getting-started\u002F6.project-setup","i-lucide-package",{"title":38,"path":39,"stem":40,"icon":41},"AI assistants","\u002Fdocs\u002Fgetting-started\u002Fai-assistants","1.docs\u002F1.getting-started\u002F7.ai-assistants","i-lucide-bot",false,{"title":44,"path":45,"stem":46,"children":47,"icon":50},"Core Concepts","\u002Fdocs\u002Fconcepts","1.docs\u002F2.concepts\u002F1.index",[48,51,56,61,66,71,76,81,86],{"title":49,"path":45,"stem":46,"icon":50},"Core concepts","i-lucide-book-open",{"title":52,"path":53,"stem":54,"icon":55},"Architecture","\u002Fdocs\u002Fconcepts\u002Farchitecture","1.docs\u002F2.concepts\u002F2.architecture","i-lucide-layers",{"title":57,"path":58,"stem":59,"icon":60},"Exactly-once semantics","\u002Fdocs\u002Fconcepts\u002Fexactly-once","1.docs\u002F2.concepts\u002F3.exactly-once","i-lucide-shield-check",{"title":62,"path":63,"stem":64,"icon":65},"Lanes and parallelism","\u002Fdocs\u002Fconcepts\u002Flanes-and-parallelism","1.docs\u002F2.concepts\u002F4.lanes-and-parallelism","i-lucide-split",{"title":67,"path":68,"stem":69,"icon":70},"State and thread-safety","\u002Fdocs\u002Fconcepts\u002Fstate-and-thread-safety","1.docs\u002F2.concepts\u002F5.state-and-thread-safety","i-lucide-lock",{"title":72,"path":73,"stem":74,"icon":75},"Event time and watermarks","\u002Fdocs\u002Fconcepts\u002Fevent-time-and-watermarks","1.docs\u002F2.concepts\u002F6.event-time-and-watermarks","i-lucide-clock",{"title":77,"path":78,"stem":79,"icon":80},"The configuration model","\u002Fdocs\u002Fconcepts\u002Fconfiguration-model","1.docs\u002F2.concepts\u002F7.configuration-model","i-lucide-sliders-horizontal",{"title":82,"path":83,"stem":84,"icon":85},"The error-handling model","\u002Fdocs\u002Fconcepts\u002Ferror-handling-model","1.docs\u002F2.concepts\u002F8.error-handling-model","i-lucide-triangle-alert",{"title":87,"path":88,"stem":89,"icon":90},"How StoatFlow differs from Kafka Streams","\u002Fdocs\u002Fconcepts\u002Fhow-stoatflow-differs-from-ks","1.docs\u002F2.concepts\u002F9.how-stoatflow-differs-from-ks","i-lucide-arrow-left-right",{"title":92,"path":93,"stem":94,"children":95,"icon":98},"Building Topologies","\u002Fdocs\u002Fbuilding","1.docs\u002F3.building\u002F1.index",[96,99,104,109,114,119,124,129,134,139,144,149],{"title":97,"path":93,"stem":94,"icon":98},"Building topologies","i-lucide-blocks",{"title":100,"path":101,"stem":102,"icon":103},"Error handling and DLQ","\u002Fdocs\u002Fbuilding\u002Ferror-handling-dlq","1.docs\u002F3.building\u002F10.error-handling-dlq","i-lucide-circle-x",{"title":105,"path":106,"stem":107,"icon":108},"State stores","\u002Fdocs\u002Fbuilding\u002Fstate-stores","1.docs\u002F3.building\u002F11.state-stores","i-lucide-database",{"title":110,"path":111,"stem":112,"icon":113},"Testing topologies","\u002Fdocs\u002Fbuilding\u002Ftesting","1.docs\u002F3.building\u002F12.testing","i-lucide-flask-conical",{"title":115,"path":116,"stem":117,"icon":118},"Sources and sinks","\u002Fdocs\u002Fbuilding\u002Fstreams-builder","1.docs\u002F3.building\u002F2.streams-builder","i-lucide-import",{"title":120,"path":121,"stem":122,"icon":123},"KStream and KTable operations","\u002Fdocs\u002Fbuilding\u002Fkstream-ktable","1.docs\u002F3.building\u002F3.kstream-ktable","i-lucide-waypoints",{"title":125,"path":126,"stem":127,"icon":128},"Aggregations","\u002Fdocs\u002Fbuilding\u002Faggregations","1.docs\u002F3.building\u002F4.aggregations","i-lucide-sigma",{"title":130,"path":131,"stem":132,"icon":133},"Windowing","\u002Fdocs\u002Fbuilding\u002Fwindowing","1.docs\u002F3.building\u002F5.windowing","i-lucide-calendar-clock",{"title":135,"path":136,"stem":137,"icon":138},"Joins","\u002Fdocs\u002Fbuilding\u002Fjoins","1.docs\u002F3.building\u002F6.joins","i-lucide-git-merge",{"title":140,"path":141,"stem":142,"icon":143},"The Processor API","\u002Fdocs\u002Fbuilding\u002Fprocessor-api","1.docs\u002F3.building\u002F7.processor-api","i-lucide-cpu",{"title":145,"path":146,"stem":147,"icon":148},"Scheduled sources","\u002Fdocs\u002Fbuilding\u002Fscheduled-sources","1.docs\u002F3.building\u002F8.scheduled-sources","i-lucide-timer",{"title":150,"path":151,"stem":152,"icon":153},"Serdes and Avro","\u002Fdocs\u002Fbuilding\u002Fserdes","1.docs\u002F3.building\u002F9.serdes","i-lucide-binary",{"title":155,"path":156,"stem":157,"children":158,"icon":80},"Configuration","\u002Fdocs\u002Fconfiguration","1.docs\u002F4.configuration\u002F1.index",[159,161,166,171,176],{"title":160,"path":156,"stem":157,"icon":80},"How configuration works",{"title":162,"path":163,"stem":164,"icon":165},"Engine configuration (:core)","\u002Fdocs\u002Fconfiguration\u002Fcore-config","1.docs\u002F4.configuration\u002F2.core-config","i-lucide-settings-2",{"title":167,"path":168,"stem":169,"icon":170},"Runtime configuration (:runtime)","\u002Fdocs\u002Fconfiguration\u002Fruntime-config","1.docs\u002F4.configuration\u002F3.runtime-config","i-lucide-server-cog",{"title":172,"path":173,"stem":174,"icon":175},"Defaults, adaptivity, and presets","\u002Fdocs\u002Fconfiguration\u002Fdefaults-and-presets","1.docs\u002F4.configuration\u002F4.defaults-and-presets","i-lucide-gauge",{"title":177,"path":178,"stem":179,"icon":180},"Kafka client configuration","\u002Fdocs\u002Fconfiguration\u002Fkafka-client-config","1.docs\u002F4.configuration\u002F5.kafka-client-config","i-lucide-plug",{"title":182,"path":183,"stem":184,"children":185,"icon":188},"Running in Production","\u002Fdocs\u002Fruntime","1.docs\u002F5.runtime\u002F1.index",[186,189,194,199,204,209,214,219],{"title":187,"path":183,"stem":184,"icon":188},"The runtime","i-lucide-server",{"title":190,"path":191,"stem":192,"icon":193},"The REST API","\u002Fdocs\u002Fruntime\u002Frest-api","1.docs\u002F5.runtime\u002F2.rest-api","i-lucide-globe",{"title":195,"path":196,"stem":197,"icon":198},"Health checks","\u002Fdocs\u002Fruntime\u002Fhealth-checks","1.docs\u002F5.runtime\u002F3.health-checks","i-lucide-heart-pulse",{"title":200,"path":201,"stem":202,"icon":203},"Metrics","\u002Fdocs\u002Fruntime\u002Fmetrics","1.docs\u002F5.runtime\u002F4.metrics","i-lucide-activity",{"title":205,"path":206,"stem":207,"icon":208},"Pause and resume","\u002Fdocs\u002Fruntime\u002Fpause-unpause","1.docs\u002F5.runtime\u002F5.pause-unpause","i-lucide-pause",{"title":210,"path":211,"stem":212,"icon":213},"Plugins and lifecycle hooks","\u002Fdocs\u002Fruntime\u002Fplugins","1.docs\u002F5.runtime\u002F6.plugins","i-lucide-puzzle",{"title":215,"path":216,"stem":217,"icon":218},"Docker images","\u002Fdocs\u002Fruntime\u002Fdocker","1.docs\u002F5.runtime\u002F7.docker","i-lucide-container",{"title":220,"path":221,"stem":222,"icon":223},"GraalVM native image","\u002Fdocs\u002Fruntime\u002Fnative-image","1.docs\u002F5.runtime\u002F8.native-image","i-lucide-zap",{"title":225,"path":226,"stem":227,"children":228,"icon":231},"Deploying & Operating","\u002Fdocs\u002Foperating","1.docs\u002F6.operating\u002F1.index",[229,232,237,242,247,252,257,262],{"title":230,"path":226,"stem":227,"icon":231},"Deploying and operating","i-lucide-life-buoy",{"title":233,"path":234,"stem":235,"icon":236},"Running on Kubernetes","\u002Fdocs\u002Foperating\u002Fkubernetes","1.docs\u002F6.operating\u002F2.kubernetes","i-lucide-ship",{"title":238,"path":239,"stem":240,"icon":241},"High availability","\u002Fdocs\u002Foperating\u002Fhigh-availability","1.docs\u002F6.operating\u002F3.high-availability","i-lucide-copy",{"title":243,"path":244,"stem":245,"icon":246},"Liveness and readiness probes","\u002Fdocs\u002Foperating\u002Fprobes","1.docs\u002F6.operating\u002F4.probes","i-lucide-stethoscope",{"title":248,"path":249,"stem":250,"icon":251},"Observability","\u002Fdocs\u002Foperating\u002Fobservability","1.docs\u002F6.operating\u002F5.observability","i-lucide-telescope",{"title":253,"path":254,"stem":255,"icon":256},"Tuning under load","\u002Fdocs\u002Foperating\u002Ftuning","1.docs\u002F6.operating\u002F6.tuning","i-lucide-sliders",{"title":258,"path":259,"stem":260,"icon":261},"Production checklist","\u002Fdocs\u002Foperating\u002Fproduction-checklist","1.docs\u002F6.operating\u002F7.production-checklist","i-lucide-clipboard-check",{"title":263,"path":264,"stem":265,"icon":266},"The licence tool","\u002Fdocs\u002Foperating\u002Flicence-tool","1.docs\u002F6.operating\u002F8.licence-tool","i-lucide-badge-check",{"title":268,"path":269,"stem":270,"children":271,"icon":90},"Migrating from Kafka Streams","\u002Fdocs\u002Fmigration","1.docs\u002F7.migration\u002F1.index",[272,273,278,283,288,293],{"title":268,"path":269,"stem":270,"icon":90},{"title":274,"path":275,"stem":276,"icon":277},"Automated port","\u002Fdocs\u002Fmigration\u002Fautomated-port","1.docs\u002F7.migration\u002F2.automated-port","i-lucide-wand-sparkles",{"title":279,"path":280,"stem":281,"icon":282},"Migration without carrying state","\u002Fdocs\u002Fmigration\u002Fwithout-data-migration","1.docs\u002F7.migration\u002F3.without-data-migration","i-lucide-sparkles",{"title":284,"path":285,"stem":286,"icon":287},"Migration carrying state","\u002Fdocs\u002Fmigration\u002Fwith-data-migration","1.docs\u002F7.migration\u002F4.with-data-migration","i-lucide-database-backup",{"title":289,"path":290,"stem":291,"icon":292},"The migration tool","\u002Fdocs\u002Fmigration\u002Fmigration-tool","1.docs\u002F7.migration\u002F5.migration-tool","i-lucide-truck",{"title":294,"path":295,"stem":296,"icon":297},"Reusing your Kafka Streams dashboards","\u002Fdocs\u002Fmigration\u002Freusing-kafka-streams-dashboards","1.docs\u002F7.migration\u002F6.reusing-kafka-streams-dashboards","i-lucide-line-chart",{"title":299,"path":300,"stem":301,"children":302,"icon":304},"Reference","\u002Fdocs\u002Freference","1.docs\u002F8.reference\u002F1.index",[303,305,310,315,320,325,330,334],{"title":299,"path":300,"stem":301,"icon":304},"i-lucide-list",{"title":306,"path":307,"stem":308,"icon":309},"Configuration reference","\u002Fdocs\u002Freference\u002Fconfiguration-reference","1.docs\u002F8.reference\u002F2.configuration-reference","i-lucide-table",{"title":311,"path":312,"stem":313,"icon":314},"REST API reference","\u002Fdocs\u002Freference\u002Frest-api-reference","1.docs\u002F8.reference\u002F3.rest-api-reference","i-lucide-network",{"title":316,"path":317,"stem":318,"icon":319},"Gradle plugin reference","\u002Fdocs\u002Freference\u002Fgradle-plugin-reference","1.docs\u002F8.reference\u002F4.gradle-plugin-reference","i-lucide-box",{"title":321,"path":322,"stem":323,"icon":324},"Maven reference","\u002Fdocs\u002Freference\u002Fmaven-reference","1.docs\u002F8.reference\u002F5.maven-reference","i-simple-icons-apachemaven",{"title":326,"path":327,"stem":328,"icon":329},"Kafka Streams compatibility matrix","\u002Fdocs\u002Freference\u002Fks-compatibility-matrix","1.docs\u002F8.reference\u002F6.ks-compatibility-matrix","i-lucide-table-2",{"title":331,"path":332,"stem":333,"icon":175},"Metrics reference","\u002Fdocs\u002Freference\u002Fmetrics-reference","1.docs\u002F8.reference\u002F7.metrics-reference",{"title":335,"path":336,"stem":337,"icon":338},"Glossary","\u002Fdocs\u002Freference\u002Fglossary","1.docs\u002F8.reference\u002F8.glossary","i-lucide-book-a",{"id":340,"cta":341,"enabled":342,"event":343,"extension":344,"invite":345,"key":346,"lead":347,"meta":348,"slot":349,"stem":350,"talk":351,"to":352,"__hash__":353},"banner\u002F8.banner.yml","Get the StoatFlow 1.0 launch email →",true,"Current San Francisco?","yml","Catch my talk","current-sf-2026","At",{},"Wed 4 Nov · 4:15 PM · Room 2012","8.banner","Kafka Streams Needs Real Timers","\u002Flaunch-list?src=banner","8xQWDSTSRv0J-LCPpHS5tuTxGF0xsQ8wMt5x2ajR2W0",{"id":355,"title":23,"body":356,"description":2519,"extension":2520,"meta":2521,"navigation":2522,"ogImage":2523,"pageType":2524,"path":24,"seo":2525,"sitemap":2526,"stem":25,"__hash__":2527},"docs\u002F1.docs\u002F1.getting-started\u002F4.licence-configuration.md",{"type":357,"value":358,"toc":2500},"minimark",[359,384,521,526,549,555,559,573,611,614,631,793,800,804,809,846,886,890,897,957,971,995,999,1020,1031,1035,1042,1089,1095,1103,1117,1124,1128,1131,1172,1210,1216,1323,1335,1349,1362,1400,1406,1416,1422,1444,1453,1457,1467,1514,1520,1567,1577,1581,1584,1677,1686,1690,1693,1747,1751,1778,1875,1879,1954,1958,1968,2221,2225,2236,2454,2458,2496],[360,361,362,363,367,368,371,372,375,376,379,380,383],"p",{},"StoatFlow verifies its licence ",[364,365,366],"strong",{},"offline",", at start: the licence is a small signed string, and the engine checks its signature with a public key it carries. There is no licence server and no egress needed to run — StoatFlow runs in air-gapped estates as it does anywhere else (a trial reports its usage once a day unless you turn that off; no other licence sends anything). Each running instance registers itself in a small topic in ",[364,369,370],{},"your own Kafka cluster",", so every instance knows how many services run under the licence, and a start that would exceed it is refused. You give each deployment two or three things: your ",[364,373,374],{},"licence",", an ",[364,377,378],{},"environment"," label, and — unless it runs in production — its ",[364,381,382],{},"environment class",".",[385,386,387],"tldr-panel",{},[388,389,390,417,429,454,473,483,495,501],"ul",{},[391,392,393,394,396,397,401,402,405,406,409,410,413,414,383],"li",{},"Set your ",[364,395,374],{}," (",[398,399,400],"code",{},"sfl1.…",") via ",[398,403,404],{},"STOATFLOW_LICENCE_KEY",", the ",[398,407,408],{},"stoatflow.licence.key"," system property, a ",[398,411,412],{},"~\u002F.stoatflow\u002Flicence.key"," file, or ",[398,415,416],{},"application.yaml",[391,418,419,422,423,428],{},[364,420,421],{},"No network access is needed."," The signature is verified offline in microseconds. Only ",[424,425,427],"a",{"href":426},"#usage-reporting","usage reporting"," sends anything — on by default for a trial, off for every other licence.",[391,430,431,432,434,435,438,439,442,443,446,447,450,451,383],{},"Every deployment declares an ",[364,433,382],{}," — ",[398,436,437],{},"production"," (the default), ",[398,440,441],{},"staging",", ",[398,444,445],{},"development"," or ",[398,448,449],{},"other",". Your licence prices the classes it lists; a class it does not list is ",[364,452,453],{},"free",[391,455,456,396,459,462,463,466,467,469,470,472],{},[364,457,458],{},"Production, enterprise and trial licences need an explicit environment label",[398,460,461],{},"STOATFLOW_LICENCE_ENVIRONMENT","), e.g. ",[398,464,465],{},"prd-eu",", in every class the licence counts — ",[398,468,437],{},", unless it lists more. A class it does not list (CI on ",[398,471,449],{},") needs none.",[391,474,475,478,479,482],{},[364,476,477],{},"Your licence counts production services"," — a service counts once per production environment — in the ",[398,480,481],{},"__stoatflow_licence"," topic of your Kafka cluster. A start past the licensed count is refused; a running instance is never stopped by the count.",[391,484,485,488,489,491,492,383],{},[364,486,487],{},"Grant the application DESCRIBE, READ and WRITE"," (and CREATE, to let it create them) on ",[398,490,481],{}," and ",[398,493,494],{},"__stoatflow_licence_history",[391,496,497,500],{},[364,498,499],{},"Expiry never stops a running paid instance."," For 30 days after expiry, services that ran during the licence term restart (with an error) and new ones are refused; after that no instance starts. A trial stops one hour after it expires.",[391,502,503,506,507,512,513,516,517,520],{},[364,504,505],{},"Renew without a restart:"," ",[424,508,509],{"href":264},[398,510,511],{},"stoatflow-licence-tool","'s ",[398,514,515],{},"java -jar stoatflow-licence-tool-all.jar apply"," writes the renewed licence to the registry topic, and every running instance switches to it once it is valid (from its ",[398,518,519],{},"validFrom",", at once for a licence already valid).",[522,523,525],"h2",{"id":524},"get-a-licence","Get a licence",[388,527,528,539],{},[391,529,530,533,534,538],{},[364,531,532],{},"Free trial:"," start one at ",[424,535,537],{"href":536},"\u002Ftrial","stoatflow.io\u002Ftrial",", self-serve; the licence and your Maven repository credentials arrive by email. A trial covers up to 10 production services for 30 days; every other environment class is free.",[391,540,541,544,545,383],{},[364,542,543],{},"Commercial licence:"," contact ",[424,546,548],{"href":547},"mailto:sales@stoatflow.io","sales@stoatflow.io",[360,550,551,552,383],{},"Your licence arrives in your onboarding email: a single line that starts with ",[398,553,554],{},"sfl1.",[522,556,558],{"id":557},"the-licence","The licence",[360,560,561,562,565,566,569,570,572],{},"The runtime looks for an explicit ",[364,563,564],{},"key"," first, then a ",[364,567,568],{},"file"," — and within each, an environment variable beats a system property (which is what an ",[398,571,416],{}," value becomes):",[574,575,576,592],"ol",{},[391,577,578,434,581,583,584,586,587,512,589,591],{},[364,579,580],{},"An explicit licence",[398,582,404],{}," (environment variable), else the ",[398,585,408],{}," system property (which ",[398,588,416],{},[398,590,408],{}," feeds).",[391,593,594,434,597,583,600,603,604,512,606,608,609,383],{},[364,595,596],{},"A licence file",[398,598,599],{},"STOATFLOW_LICENCE_FILE",[398,601,602],{},"stoatflow.licence.file"," system property (fed by ",[398,605,416],{},[398,607,602],{},"), else the default ",[398,610,412],{},[360,612,613],{},"So an explicit licence always wins over a file, regardless of where each came from.",[615,616,618],"callout",{"icon":617},"i-lucide-info",[360,619,620,622,623,626,627,630],{},[398,621,416],{}," values are applied ",[364,624,625],{},"below"," environment variables and ",[398,628,629],{},"-D"," system properties — so an env var always wins over YAML. This lets you commit a YAML default and override it per environment without touching the file.",[632,633,634,679,750],"code-group",{},[635,636,642],"pre",{"className":637,"code":638,"filename":639,"language":640,"meta":641,"style":641},"language-bash shiki shiki-themes vitesse-light","# Highest precedence. Good for containers, CI, and one-off local runs.\nexport STOATFLOW_LICENCE_KEY=\"sfl1....your licence from the onboarding email...\"\n","Shell env","bash","",[398,643,644,653],{"__ignoreMap":641},[645,646,649],"span",{"class":647,"line":648},"line",1,[645,650,652],{"class":651},"s8zF2","# Highest precedence. Good for containers, CI, and one-off local runs.\n",[645,654,656,660,664,668,672,676],{"class":647,"line":655},2,[645,657,659],{"class":658},"si04Y","export",[645,661,663],{"class":662},"svycV"," STOATFLOW_LICENCE_KEY",[645,665,667],{"class":666},"sYZai","=",[645,669,671],{"class":670},"sSP4y","\"",[645,673,675],{"class":674},"spphp","sfl1....your licence from the onboarding email...",[645,677,678],{"class":670},"\"\n",[635,680,683],{"className":637,"code":681,"filename":682,"language":640,"meta":641,"style":641},"# Set once, every local app picks it up — no env var needed.\n# Must be owner-only (chmod 600) on Linux\u002FmacOS, or startup is refused.\nmkdir -p ~\u002F.stoatflow\nprintf '%s' 'sfl1....your licence...' > ~\u002F.stoatflow\u002Flicence.key\nchmod 600 ~\u002F.stoatflow\u002Flicence.key\n","Licence file",[398,684,685,690,695,709,738],{"__ignoreMap":641},[645,686,687],{"class":647,"line":648},[645,688,689],{"class":651},"# Set once, every local app picks it up — no env var needed.\n",[645,691,692],{"class":647,"line":655},[645,693,694],{"class":651},"# Must be owner-only (chmod 600) on Linux\u002FmacOS, or startup is refused.\n",[645,696,698,702,706],{"class":647,"line":697},3,[645,699,701],{"class":700},"sySUi","mkdir",[645,703,705],{"class":704},"sEi1f"," -p",[645,707,708],{"class":674}," ~\u002F.stoatflow\n",[645,710,712,716,719,722,725,727,730,732,735],{"class":647,"line":711},4,[645,713,715],{"class":714},"su6XF","printf",[645,717,718],{"class":670}," '",[645,720,721],{"class":674},"%s",[645,723,724],{"class":670},"'",[645,726,718],{"class":670},[645,728,729],{"class":674},"sfl1....your licence...",[645,731,724],{"class":670},[645,733,734],{"class":658}," >",[645,736,737],{"class":674}," ~\u002F.stoatflow\u002Flicence.key\n",[645,739,741,744,748],{"class":647,"line":740},5,[645,742,743],{"class":700},"chmod",[645,745,747],{"class":746},"s-TwI"," 600",[645,749,737],{"class":674},[635,751,755],{"className":752,"code":753,"filename":416,"language":754,"meta":641,"style":641},"language-yaml shiki shiki-themes vitesse-light","# Runtime module only. Interpolate from an env var so the licence\n# never lands in source control.\nstoatflow:\n  licence:\n    key: ${STOATFLOW_LICENCE_KEY}\n","yaml",[398,756,757,762,767,775,782],{"__ignoreMap":641},[645,758,759],{"class":647,"line":648},[645,760,761],{"class":651},"# Runtime module only. Interpolate from an env var so the licence\n",[645,763,764],{"class":647,"line":655},[645,765,766],{"class":651},"# never lands in source control.\n",[645,768,769,772],{"class":647,"line":697},[645,770,771],{"class":714},"stoatflow",[645,773,774],{"class":666},":\n",[645,776,777,780],{"class":647,"line":711},[645,778,779],{"class":714},"  licence",[645,781,774],{"class":666},[645,783,784,787,790],{"class":647,"line":740},[645,785,786],{"class":714},"    key",[645,788,789],{"class":666},":",[645,791,792],{"class":674}," ${STOATFLOW_LICENCE_KEY}\n",[360,794,795,796,799],{},"The licence is readable: its payload is plain JSON (licensee, tier, allowances, expiry) under a signature, so changing any of it makes the signature fail. Every start logs who it is ",[364,797,798],{},"licensed to"," — the licensee's name, the tier and the expiry.",[522,801,803],{"id":802},"what-each-deployment-declares","What each deployment declares",[805,806,808],"h3",{"id":807},"environment-label","Environment label",[360,810,811,812,814,815,442,817,442,820,442,823,826,827,830,831,834,835,405,837,840,841,843,844,383],{},"The ",[364,813,378],{}," is a label for the environment a deployment runs in — ",[398,816,465],{},[398,818,819],{},"prd-us",[398,821,822],{},"stg",[398,824,825],{},"dev",". With the ",[398,828,829],{},"application.id"," it forms the deployment's fingerprint, ",[398,832,833],{},"SHA-256(application-id || environment)",", so the same application in two environments is two deployments. Set it with ",[398,836,461],{},[398,838,839],{},"stoatflow.licence.environment"," system property, or ",[398,842,839],{}," in ",[398,845,416],{},[388,847,848,854,873],{},[391,849,850,853],{},[364,851,852],{},"Production, enterprise and trial licences require an explicit environment in every class they count"," — the start is refused if it would have to auto-generate one there. In Kubernetes the auto-generated name is the pod name, which changes on every redeploy.",[391,855,856,859,860,862,863,866,867,446,869,872],{},[364,857,858],{},"A class the licence does not list is free"," and counts nothing, so it needs no label: a CI run on class ",[398,861,449],{}," keeps the auto-generated ",[398,864,865],{},"cicd-\u003Crun id>"," — unless your licence lists ",[398,868,449],{},[398,870,871],{},"*",", which counts it.",[391,874,875,878,879,882,883,885],{},[364,876,877],{},"Developer and internal licences"," default it to ",[398,880,881],{},"\u003Cusername>-\u003Chostname>",", or ",[398,884,865],{}," on GitHub Actions.",[805,887,889],{"id":888},"environment-class","Environment class",[360,891,892,893,896],{},"Every deployment declares the ",[364,894,895],{},"class"," of its environment — one of four:",[898,899,900,913],"table",{},[901,902,903],"thead",{},[904,905,906,910],"tr",{},[907,908,909],"th",{},"Class",[907,911,912],{},"For",[914,915,916,930,939,948],"tbody",{},[904,917,918,923],{},[919,920,921],"td",{},[398,922,437],{},[919,924,925,926,929],{},"production — ",[364,927,928],{},"the default"," when nothing is set",[904,931,932,936],{},[919,933,934],{},[398,935,441],{},[919,937,938],{},"pre-production, often production-like",[904,940,941,945],{},[919,942,943],{},[398,944,445],{},[919,946,947],{},"development environments",[904,949,950,954],{},[919,951,952],{},[398,953,449],{},[919,955,956],{},"everything else: test, previews, CI, DR drills",[360,958,959,960,405,963,840,966,843,968,970],{},"Set it with ",[398,961,962],{},"STOATFLOW_LICENCE_ENVIRONMENT_CLASS",[398,964,965],{},"stoatflow.licence.environment-class",[398,967,965],{},[398,969,416],{},". Any other value is refused at start.",[360,972,973,974,977,978,980,981,442,983,491,985,987,988,991,992,994],{},"Your licence lists an ",[364,975,976],{},"allowance"," per class it prices. The standard shape prices only ",[398,979,437],{},": ",[398,982,441],{},[398,984,445],{},[398,986,449],{}," are then ",[364,989,990],{},"free and unlimited",". A developer licence covers every class except ",[398,993,437],{},", and refuses a production-class start. Declaring the class truthfully is part of your licence agreement.",[805,996,998],{"id":997},"service","Service",[360,1000,1001,1002,1004,1005,1007,1008,1011,1012,1015,1016,1019],{},"A deployment counts as the ",[364,1003,997],{}," named by its ",[398,1006,829],{},", unless you set ",[398,1009,1010],{},"STOATFLOW_LICENCE_SERVICE"," (or ",[398,1013,1014],{},"stoatflow.licence.service","): that merges two application ids that are one service in one environment, such as a blue\u002Fgreen pair or an application being renamed. Application ids that carry their environment (",[398,1017,1018],{},"orders-prd",") need nothing set, because the environment label already separates them.",[360,1021,1022,1023,1026,1027,1030],{},"The merge is bounded: a service counts once for ",[364,1024,1025],{},"up to two"," live application ids; a third counts as a second service, and so on. Nothing is refused for merging — the extra application ids are simply counted, and ",[398,1028,1029],{},"\u002Flicence"," lists the application ids of every service.",[522,1032,1034],{"id":1033},"how-the-licence-counts","How the licence counts",[360,1036,1037,1038,1041],{},"Every running instance registers in the ",[364,1039,1040],{},"licence registry",", a small compacted topic in the Kafka cluster it already uses, and heartbeats every 30 seconds. Every instance reads it, so each one knows what runs under the licence:",[388,1043,1044,1064,1070,1083],{},[391,1045,1046,1047,1050,1051,1055,1056,1058,1059,442,1061,1063],{},"A ",[364,1048,1049],{},"production service"," is a distinct ",[1052,1053,1054],"em",{},"(service, environment)"," pair with at least one live instance in an environment of class ",[398,1057,437],{},". A service in two production environments (",[398,1060,465],{},[398,1062,819],{},") is two production services; its replicas count once.",[391,1065,1066,1069],{},[364,1067,1068],{},"Other classes"," are counted the same way and shown, but they are free and unlimited unless your licence lists them.",[391,1071,1072,1075,1076,1079,1080,1082],{},[364,1073,1074],{},"HA standbys:"," whether a hot-standby replica counts is a term of your licence — all free (the default), every standby counted, or the first ",[1052,1077,1078],{},"n"," per service free. ",[398,1081,1029],{}," shows the standbys running and counted.",[391,1084,1085,1088],{},[364,1086,1087],{},"Liveness is judged by your brokers' clock:"," an instance whose last heartbeat is more than 90 seconds old by the brokers' clock no longer counts, so a pod that crashed leaves the count within 90 seconds, and one that stops gracefully leaves it at once.",[360,1090,1091,1094],{},[364,1092,1093],{},"At start",", an instance counts its environment class with itself in it. If that is within the licence, it registers and runs; if not, the start is refused:",[635,1096,1101],{"className":1097,"code":1099,"language":1100,"meta":641},[1098],"language-text","StoatFlow licence for ACME Corp allows 25 production services, and 25 are running. Stop a production service,\ndeclare this deployment's environment class if it is not production, or contact sales@stoatflow.io to raise the\nlicence.\n","text",[398,1102,1099],{"__ignoreMap":641},[360,1104,1105,1106,1109,1110,1113,1114,1116],{},"On Kubernetes, that deployment's pods crash-loop on this message; the running fleet is unaffected. ",[364,1107,1108],{},"A restart, a rolling update or a replacement pod of a service that is already registered is never refused",", so the cap never takes down what already runs — even while the class is over its cap. A service is registered while one of its instances runs, and for 7 days after it was last seen: a graceful restart, a ",[398,1111,1112],{},"Recreate"," rollout, a StatefulSet roll or a pod that crash-loops for a while all start again. A service not seen for 7 days starts as a new one. HA standbys that your licence counts come back the same way, up to as many as the service ran in those 7 days: a counted standby's restart starts even over the cap, while a standby beyond that is refused like a new service. Two services that start at the same moment for the last slot both run: each logs a warning about the overage, ",[398,1115,1029],{}," shows it, and nothing stops.",[360,1118,1119,1120,1123],{},"The cap is the licensed count. A licence can carry a published ",[364,1121,1122],{},"burst"," for rollout slack (a burst of 10 % lets a 25-service licence run 28); the default is none.",[522,1125,1127],{"id":1126},"the-licence-registry-topics","The licence registry topics",[360,1129,1130],{},"StoatFlow creates two topics in each Kafka cluster it runs against, shared by every StoatFlow application on that cluster:",[898,1132,1133,1146],{},[901,1134,1135],{},[904,1136,1137,1140,1143],{},[907,1138,1139],{},"Topic",[907,1141,1142],{},"Holds",[907,1144,1145],{},"Read",[914,1147,1148,1160],{},[904,1149,1150,1154,1157],{},[919,1151,1152],{},[398,1153,481],{},[919,1155,1156],{},"the live instances, the services seen during the licence term, licences applied to the cluster",[919,1158,1159],{},"at every start, then tailed",[904,1161,1162,1166,1169],{},[919,1163,1164],{},[398,1165,494],{},[919,1167,1168],{},"daily and hourly usage history, kept 400 days",[919,1170,1171],{},"by usage reports only, never at start",[360,1173,1174,1177,1178,1181,1182,1185,1186,1189,1190,1193,1194,1197,1198,1201,1202,1205,1206,1209],{},[364,1175,1176],{},"ACLs."," The application needs ",[364,1179,1180],{},"DESCRIBE, READ and WRITE"," on both topics, and ",[364,1183,1184],{},"CREATE"," if StoatFlow is to create them; ",[364,1187,1188],{},"DESCRIBE_CONFIGS"," lets the start check the timestamp type — without it, StoatFlow reads the type from the records on the topic, and on an empty topic uses the ",[398,1191,1192],{},"CreateTime"," fallback below until the first record shows it. The registry's clients authenticate like the application's own: the producer with ",[398,1195,1196],{},"producer.*",", the admin client with ",[398,1199,1200],{},"admin.*",", the consumer with ",[398,1203,1204],{},"restore.consumer.*"," (each falling back to ",[398,1207,1208],{},"consumer.*",").",[360,1211,1212,1215],{},[364,1213,1214],{},"Pre-creating them"," on a cluster that denies topic creation — exactly these settings, then restart (the error at start prints them too):",[635,1217,1219],{"className":637,"code":1218,"language":640,"meta":641,"style":641},"kafka-topics.sh --create --topic __stoatflow_licence --partitions 1 --replication-factor 3 \\\n  --config cleanup.policy=compact --config retention.ms=-1 \\\n  --config message.timestamp.type=LogAppendTime --config min.insync.replicas=2 \\\n  --config segment.ms=300000 --config min.compaction.lag.ms=0 \\\n  --config max.compaction.lag.ms=300000 --config min.cleanable.dirty.ratio=0.1\n",[398,1220,1221,1250,1269,1286,1306],{"__ignoreMap":641},[645,1222,1223,1226,1229,1232,1235,1238,1241,1244,1247],{"class":647,"line":648},[645,1224,1225],{"class":700},"kafka-topics.sh",[645,1227,1228],{"class":704}," --create",[645,1230,1231],{"class":704}," --topic",[645,1233,1234],{"class":674}," __stoatflow_licence",[645,1236,1237],{"class":704}," --partitions",[645,1239,1240],{"class":746}," 1",[645,1242,1243],{"class":704}," --replication-factor",[645,1245,1246],{"class":746}," 3",[645,1248,1249],{"class":704}," \\\n",[645,1251,1252,1255,1258,1261,1264,1267],{"class":647,"line":655},[645,1253,1254],{"class":704},"  --config",[645,1256,1257],{"class":674}," cleanup.policy=compact",[645,1259,1260],{"class":704}," --config",[645,1262,1263],{"class":674}," retention.ms=",[645,1265,1266],{"class":746},"-1",[645,1268,1249],{"class":704},[645,1270,1271,1273,1276,1278,1281,1284],{"class":647,"line":697},[645,1272,1254],{"class":704},[645,1274,1275],{"class":674}," message.timestamp.type=LogAppendTime",[645,1277,1260],{"class":704},[645,1279,1280],{"class":674}," min.insync.replicas=",[645,1282,1283],{"class":746},"2",[645,1285,1249],{"class":704},[645,1287,1288,1290,1293,1296,1298,1301,1304],{"class":647,"line":711},[645,1289,1254],{"class":704},[645,1291,1292],{"class":674}," segment.ms=",[645,1294,1295],{"class":746},"300000",[645,1297,1260],{"class":704},[645,1299,1300],{"class":674}," min.compaction.lag.ms=",[645,1302,1303],{"class":746},"0",[645,1305,1249],{"class":704},[645,1307,1308,1310,1313,1315,1317,1320],{"class":647,"line":740},[645,1309,1254],{"class":704},[645,1311,1312],{"class":674}," max.compaction.lag.ms=",[645,1314,1295],{"class":746},[645,1316,1260],{"class":704},[645,1318,1319],{"class":674}," min.cleanable.dirty.ratio=",[645,1321,1322],{"class":746},"0.1\n",[360,1324,1325,1328,1329,1331,1332,383],{},[398,1326,1327],{},"message.timestamp.type=LogAppendTime"," matters: liveness and expiry follow your brokers' clock, so rolling back a host's clock does not extend a licence. On a topic created with ",[398,1330,1192],{},", StoatFlow falls back to each host's own clock, waits 90 seconds at a start that finds other instances' records before it counts, logs a warning every hour, and reports ",[398,1333,1334],{},"stoatflow.licence.registry.broker.clock = 0",[360,1336,1337,1340,1341,1344,1345,1348],{},[364,1338,1339],{},"A separate registry per tenant."," On a shared cluster, ",[398,1342,1343],{},"stoatflow.licence.registry.topic"," names a different registry topic (the history topic follows as ",[398,1346,1347],{},"\u003Ctopic>_history","), so one team's licence and instances stay apart from another's.",[360,1350,1351,506,1354,506,1358,1361],{},[364,1352,1353],{},"Applying a licence to the cluster.",[424,1355,1356],{"href":264},[398,1357,511],{},[398,1359,1360],{},"apply"," verifies a licence offline and writes it to the registry topic:",[635,1363,1365],{"className":637,"code":1364,"language":640,"meta":641,"style":641},"java -jar stoatflow-licence-tool-all.jar apply licence.sfl1 --bootstrap-server kafka:9092 \\\n  --command-config client.properties\n",[398,1366,1367,1392],{"__ignoreMap":641},[645,1368,1369,1372,1375,1378,1381,1384,1387,1390],{"class":647,"line":648},[645,1370,1371],{"class":700},"java",[645,1373,1374],{"class":704}," -jar",[645,1376,1377],{"class":674}," stoatflow-licence-tool-all.jar",[645,1379,1380],{"class":674}," apply",[645,1382,1383],{"class":674}," licence.sfl1",[645,1385,1386],{"class":704}," --bootstrap-server",[645,1388,1389],{"class":674}," kafka:9092",[645,1391,1249],{"class":704},[645,1393,1394,1397],{"class":647,"line":655},[645,1395,1396],{"class":704},"  --command-config",[645,1398,1399],{"class":674}," client.properties\n",[360,1401,1402,1403,1405],{},"Every running instance of the same licence id — and every instance that starts later — uses the applied licence once it is valid (from its ",[398,1404,519],{},") when its sequence number is higher than its own: renewals, band changes and trial extensions arrive this way, with no redeploy and no restart. A lower sequence number is ignored (no rollback), and the tool refuses one.",[360,1407,1408,1411,1412,1415],{},[364,1409,1410],{},"Adopting the applied licence"," (opt-in). With ",[398,1413,1414],{},"stoatflow.licence.source: registry",", an application that configures no licence of its own adopts the one licence applied to the registry topic. Without that setting an application never picks up a licence someone else applied — on a shared cluster, an unlicensed team's application would otherwise consume another team's allowance.",[360,1417,1418,1421],{},[364,1419,1420],{},"When the registry is unavailable"," — a missing ACL, an unreachable cluster at start, a topic deleted under a running application:",[388,1423,1424,1438],{},[391,1425,1426,1429,1430,1433,1434,1437],{},[364,1427,1428],{},"Paid licences keep running."," The licence is still verified and its expiry enforced, but the service count is not: the status is ",[398,1431,1432],{},"UNVERIFIED",", readiness stays UP, ",[398,1435,1436],{},"stoatflow.licence.registry.available"," reads 0, a warning is logged every hour, and the instance retries in the background, counting again as soon as the topic is back.",[391,1439,1440,1443],{},[364,1441,1442],{},"A trial refuses to start"," without the registry. A trial that loses it while running keeps running until its expiry.",[360,1445,1446,1449,1450,1452],{},[364,1447,1448],{},"Bound to Kafka clusters."," A licence can name the Kafka cluster ids it may run on; an instance on any other cluster refuses to start. ",[398,1451,1029],{}," shows the cluster id.",[522,1454,1456],{"id":1455},"usage-history-and-reports","Usage history and reports",[360,1458,1459,1460,1462,1463,1466],{},"Each deployment records its usage in the history topic — one of its instances writes it, every instance while the licence registry is unavailable — ",[398,1461,494],{}," (kept 400 days by your brokers, never read at start): which services ran each UTC day, and the peak count of its environment class in each hour. From it, the ",[364,1464,1465],{},"usage report"," — a JSON document you produce and can read every byte of before sending it — states what a licence used on one Kafka cluster over a period:",[635,1468,1470],{"className":637,"code":1469,"language":640,"meta":641,"style":641},"java -jar stoatflow-licence-tool-all.jar report --bootstrap-server kafka:9092 \\\n  --licence lic_7Q2… --from 2026-10-01 --to 2027-09-30 > usage-2027.json\n",[398,1471,1472,1489],{"__ignoreMap":641},[645,1473,1474,1476,1478,1480,1483,1485,1487],{"class":647,"line":648},[645,1475,1371],{"class":700},[645,1477,1374],{"class":704},[645,1479,1377],{"class":674},[645,1481,1482],{"class":674}," report",[645,1484,1386],{"class":704},[645,1486,1389],{"class":674},[645,1488,1249],{"class":704},[645,1490,1491,1494,1497,1500,1503,1506,1509,1511],{"class":647,"line":655},[645,1492,1493],{"class":704},"  --licence",[645,1495,1496],{"class":674}," lic_7Q2…",[645,1498,1499],{"class":704}," --from",[645,1501,1502],{"class":674}," 2026-10-01",[645,1504,1505],{"class":704}," --to",[645,1507,1508],{"class":674}," 2027-09-30",[645,1510,734],{"class":658},[645,1512,1513],{"class":674}," usage-2027.json\n",[360,1515,1516,1517,383],{},"A running application serves the same report at ",[398,1518,1519],{},"GET \u002Flicence\u002Fusage?from=2026-10-01&to=2026-10-31",[388,1521,1522,1528,1541,1558],{},[391,1523,1524,1527],{},[364,1525,1526],{},"Per environment class:"," the peak concurrent count, the distinct services, and for the classes your licence prices the 95th-percentile and average daily peak, the days over the licensed count and the standbys running and counted; also per environment, per day and per engine version.",[391,1529,1530,1533,1534,396,1537,1540],{},[364,1531,1532],{},"Application ids and services appear only as hashes",", unless you add ",[398,1535,1536],{},"--include-app-names",[398,1538,1539],{},"include-app-names=true","). Environment labels and classes appear in clear: the class declaration is what the report attests.",[391,1542,1543,506,1546,1549,1550,1553,1554,1557],{},[364,1544,1545],{},"How far to trust it:",[398,1547,1548],{},"registry.brokerClock"," (whether the history topic carries your brokers' clock), ",[398,1551,1552],{},"unverifiedHours"," (hours an instance ran without the registry) and ",[398,1555,1556],{},"historyGapHours"," (hours the history could not be written).",[391,1559,1560,506,1563,1566],{},[364,1561,1562],{},"Many clusters:",[398,1564,1565],{},"java -jar stoatflow-licence-tool-all.jar fleet-report report-a.json report-b.json …"," merges one licence's per-cluster reports of the same period — each class's daily total is the sum of each cluster's daily peak — and lists the clusters.",[360,1568,1569,1570,1573,1574,1576],{},"If the history topic cannot be written, the instance runs as before; the history has a gap, and ",[398,1571,1572],{},"stoatflow.licence.history.available"," reads 0 on every instance of the deployment (one instance writes its history and the others report its state). ",[398,1575,1556],{}," counts the hours an instance ran without writing its history only up to the last hour it wrote: an instance that stops while the history is still unwritable leaves its last hours out, so alert on the gauge.",[522,1578,1580],{"id":1579},"usage-reporting","Usage reporting",[360,1582,1583],{},"Usage reporting sends the usage report to StoatFlow automatically, so nobody has to run the tool by hand.",[388,1585,1586,1606,1620,1626,1635,1645],{},[391,1587,1588,506,1591,1594,1595,1598,1599,446,1602,1605],{},[364,1589,1590],{},"Off by default, except for trials.",[398,1592,1593],{},"stoatflow.licence.reporting.enabled"," (env ",[398,1596,1597],{},"STOATFLOW_LICENCE_REPORTING_ENABLED",") turns it on or off — ",[398,1600,1601],{},"true",[398,1603,1604],{},"false","; unset (or any other value, which logs a warning), a trial reports and every other licence does not. A licence agreement may ask for reporting: such a licence logs a warning once a day while it is off — and nothing stops.",[391,1607,1608,1611,1612,1615,1616,1619],{},[364,1609,1610],{},"What is sent:"," once a day, the previous UTC day's usage report — exactly what ",[398,1613,1614],{},"GET \u002Flicence\u002Fusage"," shows for that day, application ids and services hashed — together with the licence it is for. A trial also sends one ",[398,1617,1618],{},"activated"," event when it first runs on a cluster (its environment class and the engine version).",[391,1621,1622,1625],{},[364,1623,1624],{},"When and from where:"," after 02:00 UTC — by the clock that stamps the usage history, the Kafka brokers' — plus a delay of up to an hour, fixed per instance, from one instance per cluster and licence: of the instances that report, the one with the lowest live fingerprint — so a deployment that turns reporting on sends even when another deployment of the licence has it off. The report covers every deployment of the licence on that cluster. A licence used on two registry topics of one cluster reports once per topic. Nothing is sent while the instance cannot read the Kafka cluster id. Each send logs one INFO line with the report's summary.",[391,1627,1628,506,1631,1634],{},[364,1629,1630],{},"Where:",[398,1632,1633],{},"POST https:\u002F\u002Flicensing.stoatflow.io\u002Fv1\u002Fusage"," — allow egress to that host where reporting is on.",[391,1636,1637,1640,1641,1644],{},[364,1638,1639],{},"If it fails"," — a firewall, an outage, a history topic it cannot read — the instance logs a warning, counts it in ",[398,1642,1643],{},"stoatflow.licence.reporting.sent.total{result=\"failed\"}",", and tries again the next day, catching up the days it missed (up to 7); a trial's activation likewise, once a day. It never affects the licence status, readiness or processing.",[391,1646,1647,1650,1651,1654,1655,1661,1662,1665,1666,396,1669,1672,1673,1676],{},[364,1648,1649],{},"Air-gapped estates"," produce the report with ",[398,1652,1653],{},"stoatflow-licence-tool report"," and upload it at ",[424,1656,1660],{"href":1657,"rel":1658},"https:\u002F\u002Flicensing.stoatflow.io\u002F",[1659],"nofollow","licensing.stoatflow.io",", from any machine that can reach it. To send it without the page, ",[398,1663,1664],{},"POST"," it wrapped with its licence: ",[398,1667,1668],{},"{\"kind\": \"report\", \"licence\": \"sfl1…\", \"report\": \u003Cthe report>}",[398,1670,1671],{},"\"kind\": \"fleet-report\""," for a fleet report) to ",[398,1674,1675],{},"https:\u002F\u002Flicensing.stoatflow.io\u002Fv1\u002Fusage","; a report covers at most 400 days.",[360,1678,1679,1681,1682,1685],{},[398,1680,1029],{}," shows ",[398,1683,1684],{},"reporting"," — whether it is on, whether the licence asks for it, the last day sent and the last result.",[522,1687,1689],{"id":1688},"local-development","Local development",[360,1691,1692],{},"Use your developer licence and declare the class — the simplest setup is the licence file plus one variable:",[635,1694,1696],{"className":637,"code":1695,"language":640,"meta":641,"style":641},"mkdir -p ~\u002F.stoatflow\nprintf '%s' 'sfl1....your developer licence...' > ~\u002F.stoatflow\u002Flicence.key\nchmod 600 ~\u002F.stoatflow\u002Flicence.key\nexport STOATFLOW_LICENCE_ENVIRONMENT_CLASS=development\n",[398,1697,1698,1706,1727,1735],{"__ignoreMap":641},[645,1699,1700,1702,1704],{"class":647,"line":648},[645,1701,701],{"class":700},[645,1703,705],{"class":704},[645,1705,708],{"class":674},[645,1707,1708,1710,1712,1714,1716,1718,1721,1723,1725],{"class":647,"line":655},[645,1709,715],{"class":714},[645,1711,718],{"class":670},[645,1713,721],{"class":674},[645,1715,724],{"class":670},[645,1717,718],{"class":670},[645,1719,1720],{"class":674},"sfl1....your developer licence...",[645,1722,724],{"class":670},[645,1724,734],{"class":658},[645,1726,737],{"class":674},[645,1728,1729,1731,1733],{"class":647,"line":697},[645,1730,743],{"class":700},[645,1732,747],{"class":746},[645,1734,737],{"class":674},[645,1736,1737,1739,1742,1744],{"class":647,"line":711},[645,1738,659],{"class":658},[645,1740,1741],{"class":662}," STOATFLOW_LICENCE_ENVIRONMENT_CLASS",[645,1743,667],{"class":666},[645,1745,1746],{"class":662},"development\n",[522,1748,1750],{"id":1749},"cicd","CI\u002FCD",[360,1752,1753,1754,1756,1757,446,1759,1761,1762,1764,1765,1767,1768,1770,1771,1773,1774,1777],{},"A CI run verifies its licence like any other start, and nothing reaches a licence server. Declare the class ",[398,1755,449],{}," and store the licence as an encrypted secret — any of your licences covers it (an unlisted class is free on a production licence, and a developer licence covers every non-production class). No environment label is needed while your licence does not list ",[398,1758,449],{},[398,1760,871],{}," (the standard shape lists only ",[398,1763,437],{},"): a class it does not list counts nothing, so the auto-generated ",[398,1766,865],{}," is fine. If it lists either, ",[398,1769,449],{}," is counted and needs a stable label — set ",[398,1772,461],{}," (e.g. ",[398,1775,1776],{},"ci","):",[635,1779,1781],{"className":752,"code":1780,"language":754,"meta":641,"style":641},"# .github\u002Fworkflows\u002Fyour-workflow.yml\njobs:\n  integration-test:\n    runs-on: ubuntu-latest\n    env:\n      STOATFLOW_LICENCE_KEY: ${{ secrets.STOATFLOW_LICENCE }}\n      STOATFLOW_LICENCE_ENVIRONMENT_CLASS: other\n      # STOATFLOW_LICENCE_ENVIRONMENT: ci   # only when your licence lists `other` or `*`\n    steps:\n      - uses: actions\u002Fcheckout@v4\n      # ... build + run StoatFlow tests ...\n",[398,1782,1783,1788,1795,1802,1812,1819,1830,1841,1847,1855,1869],{"__ignoreMap":641},[645,1784,1785],{"class":647,"line":648},[645,1786,1787],{"class":651},"# .github\u002Fworkflows\u002Fyour-workflow.yml\n",[645,1789,1790,1793],{"class":647,"line":655},[645,1791,1792],{"class":714},"jobs",[645,1794,774],{"class":666},[645,1796,1797,1800],{"class":647,"line":697},[645,1798,1799],{"class":714},"  integration-test",[645,1801,774],{"class":666},[645,1803,1804,1807,1809],{"class":647,"line":711},[645,1805,1806],{"class":714},"    runs-on",[645,1808,789],{"class":666},[645,1810,1811],{"class":674}," ubuntu-latest\n",[645,1813,1814,1817],{"class":647,"line":740},[645,1815,1816],{"class":714},"    env",[645,1818,774],{"class":666},[645,1820,1822,1825,1827],{"class":647,"line":1821},6,[645,1823,1824],{"class":714},"      STOATFLOW_LICENCE_KEY",[645,1826,789],{"class":666},[645,1828,1829],{"class":674}," ${{ secrets.STOATFLOW_LICENCE }}\n",[645,1831,1833,1836,1838],{"class":647,"line":1832},7,[645,1834,1835],{"class":714},"      STOATFLOW_LICENCE_ENVIRONMENT_CLASS",[645,1837,789],{"class":666},[645,1839,1840],{"class":674}," other\n",[645,1842,1844],{"class":647,"line":1843},8,[645,1845,1846],{"class":651},"      # STOATFLOW_LICENCE_ENVIRONMENT: ci   # only when your licence lists `other` or `*`\n",[645,1848,1850,1853],{"class":647,"line":1849},9,[645,1851,1852],{"class":714},"    steps",[645,1854,774],{"class":666},[645,1856,1858,1861,1864,1866],{"class":647,"line":1857},10,[645,1859,1860],{"class":666},"      -",[645,1862,1863],{"class":714}," uses",[645,1865,789],{"class":666},[645,1867,1868],{"class":674}," actions\u002Fcheckout@v4\n",[645,1870,1872],{"class":647,"line":1871},11,[645,1873,1874],{"class":651},"      # ... build + run StoatFlow tests ...\n",[522,1876,1878],{"id":1877},"expiry-and-renewal","Expiry and renewal",[388,1880,1881,1917,1941],{},[391,1882,1883,1886,1887,1890,1891,1894,1895,1898,1899,1902,1903,1906,1907,1681,1909,1912,1913,1916],{},[364,1884,1885],{},"Paid licences"," (developer, production, enterprise): from 30 days before expiry the log carries a daily warning and the ",[398,1888,1889],{},"stoatflow.licence.days.remaining"," gauge counts down; readiness is unaffected. ",[364,1892,1893],{},"A running instance is never stopped by expiry."," For the ",[364,1896,1897],{},"30 days after expiry",", a service that ran during the licence term restarts — a pod rescheduled after a node drain, an eviction, an upgrade — with an error in its log, and a ",[364,1900,1901],{},"new"," service is refused: the fleet cannot grow on an expired licence. ",[364,1904,1905],{},"After those 30 days, no instance starts",", so an expired fleet goes down at its next reschedule. ",[398,1908,1029],{},[398,1910,1911],{},"restartGraceEndsAt"," once the licence has expired; ",[398,1914,1915],{},"stoatflow.licence.grace.remaining.seconds"," counts down to that same instant (expiry + 30 days) through the whole term, so an alert on it fires in time whatever the date. (If the registry is unavailable during those 30 days, a restart is allowed with an error, because whether the service ran during the term cannot be checked.)",[391,1918,1919,1922,1923,1926,1927,396,1929,1932,1933,1936,1937,1940],{},[364,1920,1921],{},"Trials:"," from five days before expiry the log names the trial's end date. At expiry the instance logs an error and ",[364,1924,1925],{},"stops one hour later","; a restart after expiry is refused unless an extension was applied. Ask for an extension or a licence before then: an extension applied with ",[398,1928,515],{},[424,1930,1931],{"href":264},"the licence tool",") cancels the stop, and an instance that restarts later starts on it. A Kafka cluster runs ",[364,1934,1935],{},"one trial",": a trial licence that starts on a cluster after another trial there ended is refused (",[398,1938,1939],{},"SERIAL_TRIAL","); one that was already running when the other ended is not, and neither is an extension of the same trial.",[391,1942,1943,1946,1947,1950,1951,1953],{},[364,1944,1945],{},"Renewal:"," a renewal is a new licence string with the same licence id and a higher sequence number. ",[364,1948,1949],{},"Apply it"," with ",[398,1952,515],{},": running instances switch to it once it is valid, which also ends a restart grace, and an instance that restarts later starts on it — also once the configured licence has expired, or on a Kafka cluster or environment class only the renewal covers. Or put it where the old one was configured; each instance picks it up when it restarts.",[522,1955,1957],{"id":1956},"all-licence-settings","All licence settings",[360,1959,1960,1961,1963,1964,1967],{},"Every setting, with its environment variable, system property, and ",[398,1962,416],{}," key (under ",[398,1965,1966],{},"stoatflow.licence","). Environment variable wins over system property wins over YAML.",[898,1969,1970,1994],{},[901,1971,1972],{},[904,1973,1974,1982,1985,1988,1991],{},[907,1975,1976,396,1978,1981],{},[398,1977,416],{},[398,1979,1980],{},"stoatflow.licence.*",")",[907,1983,1984],{},"Environment variable",[907,1986,1987],{},"System property",[907,1989,1990],{},"Default",[907,1992,1993],{},"Purpose",[914,1995,1996,2018,2047,2073,2101,2123,2147,2175,2200],{},[904,1997,1998,2002,2006,2010,2013],{},[919,1999,2000],{},[398,2001,564],{},[919,2003,2004],{},[398,2005,404],{},[919,2007,2008],{},[398,2009,408],{},[919,2011,2012],{},"—",[919,2014,2015,2016,1209],{},"The licence (",[398,2017,400],{},[904,2019,2020,2024,2028,2032,2036],{},[919,2021,2022],{},[398,2023,568],{},[919,2025,2026],{},[398,2027,599],{},[919,2029,2030],{},[398,2031,602],{},[919,2033,2034],{},[398,2035,412],{},[919,2037,2038,2039,2042,2043,2046],{},"Path to an owner-only (",[398,2040,2041],{},"chmod 600",") file holding the licence; a root-owned mount, such as a Kubernetes Secret with ",[398,2044,2045],{},"fsGroup",", may also be group-readable.",[904,2048,2049,2053,2057,2061,2066],{},[919,2050,2051],{},[398,2052,378],{},[919,2054,2055],{},[398,2056,461],{},[919,2058,2059],{},[398,2060,839],{},[919,2062,2063,2065],{},[398,2064,881],{}," (auto)",[919,2067,2068,2069,2072],{},"Environment label; ",[364,2070,2071],{},"required"," for production, enterprise and trial licences in a class they count.",[904,2074,2075,2079,2083,2087,2091],{},[919,2076,2077],{},[398,2078,888],{},[919,2080,2081],{},[398,2082,962],{},[919,2084,2085],{},[398,2086,965],{},[919,2088,2089],{},[398,2090,437],{},[919,2092,2093,442,2095,442,2097,446,2099,383],{},[398,2094,437],{},[398,2096,441],{},[398,2098,445],{},[398,2100,449],{},[904,2102,2103,2107,2111,2115,2120],{},[919,2104,2105],{},[398,2106,997],{},[919,2108,2109],{},[398,2110,1010],{},[919,2112,2113],{},[398,2114,1014],{},[919,2116,2117,2118],{},"the ",[398,2119,829],{},[919,2121,2122],{},"The service this deployment counts as.",[904,2124,2125,2130,2135,2140,2144],{},[919,2126,2127],{},[398,2128,2129],{},"verbose-banner",[919,2131,2132],{},[398,2133,2134],{},"STOATFLOW_LICENCE_VERBOSE_BANNER",[919,2136,2137],{},[398,2138,2139],{},"stoatflow.licence.verbose-banner",[919,2141,2142],{},[398,2143,1604],{},[919,2145,2146],{},"Also log the licence's terms (allowances, standbys, cluster binding) at start.",[904,2148,2149,2154,2159,2164,2169],{},[919,2150,2151],{},[398,2152,2153],{},"source",[919,2155,2156],{},[398,2157,2158],{},"STOATFLOW_LICENCE_SOURCE",[919,2160,2161],{},[398,2162,2163],{},"stoatflow.licence.source",[919,2165,2166],{},[398,2167,2168],{},"configured",[919,2170,2171,2174],{},[398,2172,2173],{},"registry"," adopts the one licence applied to the registry topic when the application configures none.",[904,2176,2177,2182,2187,2191,2195],{},[919,2178,2179],{},[398,2180,2181],{},"registry.topic",[919,2183,2184],{},[398,2185,2186],{},"STOATFLOW_LICENCE_REGISTRY_TOPIC",[919,2188,2189],{},[398,2190,1343],{},[919,2192,2193],{},[398,2194,481],{},[919,2196,2197,2198,383],{},"The registry topic; the history topic is ",[398,2199,1347],{},[904,2201,2202,2207,2211,2215,2218],{},[919,2203,2204],{},[398,2205,2206],{},"reporting.enabled",[919,2208,2209],{},[398,2210,1597],{},[919,2212,2213],{},[398,2214,1593],{},[919,2216,2217],{},"on for a trial, else off",[919,2219,2220],{},"Send the previous day's usage report to StoatFlow once a day.",[522,2222,2224],{"id":2223},"troubleshooting","Troubleshooting",[360,2226,2227,2228,2231,2232,2235],{},"Every refusal throws a ",[398,2229,2230],{},"LicenceValidationException"," from ",[398,2233,2234],{},"start()",", before anything is built, with a code and a message that names the fix.",[388,2237,2238,2250,2267,2275,2283,2294,2310,2323,2334,2342,2353,2364,2371,2381,2396,2404,2412,2427,2448],{},[391,2239,2240,2245,2246,2249],{},[364,2241,2242,383],{},[398,2243,2244],{},"StoatFlow licence not found"," No licence is configured; the message lists every place that was checked. Note the British spelling: ",[398,2247,2248],{},"STOATFLOW_LICENSE_KEY"," is not read.",[391,2251,2252,2258,2259,2262,2263,2266],{},[364,2253,2254,2257],{},[398,2255,2256],{},"MALFORMED"," — \"this is a Keygen licence key\"."," A licence from before offline licensing (",[398,2260,2261],{},"key\u002F…","). Ask for it to be re-issued as an ",[398,2264,2265],{},"sfl1"," licence.",[391,2268,2269,2274],{},[364,2270,2271,383],{},[398,2272,2273],{},"INVALID_SIGNATURE"," The licence was altered, truncated when copied, or was not issued by StoatFlow. Copy it again from the onboarding email.",[391,2276,2277,2282],{},[364,2278,2279,383],{},[398,2280,2281],{},"UNKNOWN_KEY"," The licence is signed with a key this StoatFlow version does not have — usually a licence newer than the engine. Upgrade StoatFlow.",[391,2284,2285,2290,2291,2293],{},[364,2286,2287,383],{},[398,2288,2289],{},"ENVIRONMENT_REQUIRED"," Set ",[398,2292,461],{}," to a stable label for the deployment.",[391,2295,2296,2301,2302,442,2304,442,2306,446,2308,383],{},[364,2297,2298,383],{},[398,2299,2300],{},"ENVIRONMENT_CLASS_UNKNOWN"," The class must be ",[398,2303,437],{},[398,2305,441],{},[398,2307,445],{},[398,2309,449],{},[391,2311,2312,2317,2318,2320,2321,383],{},[364,2313,2314,383],{},[398,2315,2316],{},"CLASS_NOT_LICENSED"," Your licence refuses this deployment's class — typically a developer licence in a deployment that did not declare its class, so it counts as ",[398,2319,437],{},". Set ",[398,2322,962],{},[391,2324,2325,2330,2331,2333],{},[364,2326,2327,383],{},[398,2328,2329],{},"SERVICE_LIMIT"," The licence's environment class is full. Stop a service of that class, check that deployments outside production declare their class, or contact sales to raise the licence. ",[398,2332,1029],{}," on any running instance lists what counts.",[391,2335,2336,2341],{},[364,2337,2338,383],{},[398,2339,2340],{},"NEW_SERVICE_AFTER_EXPIRY"," The licence has expired: services that ran during its term restart for 30 days, a new one does not start. Apply the renewed licence.",[391,2343,2344,2352],{},[364,2345,2346,442,2349,383],{},[398,2347,2348],{},"EXPIRED",[398,2350,2351],{},"TRIAL_EXPIRED"," The licence's term is over and so is any grace it has. Apply the renewed licence.",[391,2354,2355,2360,2361,2363],{},[364,2356,2357,383],{},[398,2358,2359],{},"REGISTRY_UNAVAILABLE"," A trial cannot read the licence registry topic, or a licence was to be adopted from it and it cannot be read. Grant DESCRIBE, READ and WRITE on ",[398,2362,481],{}," (and CREATE).",[391,2365,2366,2370],{},[364,2367,2368,383],{},[398,2369,1939],{}," This Kafka cluster already ran a different StoatFlow trial, which has ended; the message says when. Ask sales for an extension of that trial, or for a licence.",[391,2372,2373,506,2378,2380],{},[364,2374,2375,383],{},[398,2376,2377],{},"NO_REGISTRY_LICENCE",[398,2379,1414],{},", and the registry topic holds no licence, or more than one current licence (an expired one beside a current one is left out): configure the application's licence.",[391,2382,2383,2388,2389,2391,2392,446,2394,383],{},[364,2384,2385,383],{},[398,2386,2387],{},"INVALID_SETTING"," A licence setting has a value it does not take — ",[398,2390,2163],{}," is ",[398,2393,2168],{},[398,2395,2173],{},[391,2397,2398,2403],{},[364,2399,2400,383],{},[398,2401,2402],{},"CLUSTER_NOT_LICENSED"," The licence is bound to other Kafka clusters; the message names this cluster's id.",[391,2405,2406,2411],{},[364,2407,2408,2409,383],{},"Status ",[398,2410,1432],{}," The registry is unavailable — the topic cannot be ensured, read or written: the instance runs, but the licence's service count is not checked. Grant the ACLs above; counting resumes on its own once the topic can be read again from its start.",[391,2413,2414,2419,2420,2423,2424,2426],{},[364,2415,2416,383],{},[398,2417,2418],{},"licence file has insecure permissions"," The file must be owner-only: ",[398,2421,2422],{},"chmod 600 ~\u002F.stoatflow\u002Flicence.key",". Only a root-owned file — a Kubernetes Secret mounted with ",[398,2425,2045],{}," — may also be group-readable; no licence file may be writable by its group or readable by others.",[391,2428,2429,2434,2435,2437,2438,2441,2442,2445,2446,1209],{},[364,2430,2431,383],{},[398,2432,2433],{},"licence file is not readable"," The user StoatFlow runs as cannot read it. For a file it owns, ",[398,2436,2041],{},"; for a Kubernetes Secret mounted as a file, set the pod's ",[398,2439,2440],{},"securityContext.fsGroup"," to the image's group and ",[398,2443,2444],{},"defaultMode: 0440"," (see ",[424,2447,233],{"href":234},[391,2449,2450,2453],{},[364,2451,2452],{},"Lost your licence?"," We re-issue rather than retrieve — reply to your onboarding email.",[522,2455,2457],{"id":2456},"next-steps","Next steps",[388,2459,2460,2475,2482,2489],{},[391,2461,2462,2466,2467,2474],{},[364,2463,2464],{},[424,2465,195],{"href":196}," and the ",[364,2468,2469],{},[424,2470,2471,2473],{"href":191},[398,2472,1029],{}," endpoint"," — what the runtime reports about its licence.",[391,2476,2477,2481],{},[364,2478,2479],{},[424,2480,263],{"href":264}," — apply, check and report on licences.",[391,2483,2484,2488],{},[364,2485,2486],{},[424,2487,52],{"href":53}," — how the engine runs your topology.",[391,2490,2491,2492,383],{},"Questions about your licence? ",[424,2493,2495],{"href":2494},"\u002Fcontact","Get in touch",[2497,2498,2499],"style",{},"html pre.shiki code .s8zF2, html code.shiki .s8zF2{--shiki-default:#A0ADA0}html pre.shiki code .si04Y, html code.shiki .si04Y{--shiki-default:#AB5959}html pre.shiki code .svycV, html code.shiki .svycV{--shiki-default:#B07D48}html pre.shiki code .sYZai, html code.shiki .sYZai{--shiki-default:#999999}html pre.shiki code .sSP4y, html code.shiki .sSP4y{--shiki-default:#B5695977}html pre.shiki code .spphp, html code.shiki .spphp{--shiki-default:#B56959}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 pre.shiki code .sySUi, html code.shiki .sySUi{--shiki-default:#59873A}html pre.shiki code .sEi1f, html code.shiki .sEi1f{--shiki-default:#A65E2B}html pre.shiki code .su6XF, html code.shiki .su6XF{--shiki-default:#998418}html pre.shiki code .s-TwI, html code.shiki .s-TwI{--shiki-default:#2F798A}",{"title":641,"searchDepth":655,"depth":655,"links":2501},[2502,2503,2504,2509,2510,2511,2512,2513,2514,2515,2516,2517,2518],{"id":524,"depth":655,"text":525},{"id":557,"depth":655,"text":558},{"id":802,"depth":655,"text":803,"children":2505},[2506,2507,2508],{"id":807,"depth":697,"text":808},{"id":888,"depth":697,"text":889},{"id":997,"depth":697,"text":998},{"id":1033,"depth":655,"text":1034},{"id":1126,"depth":655,"text":1127},{"id":1455,"depth":655,"text":1456},{"id":1579,"depth":655,"text":1580},{"id":1688,"depth":655,"text":1689},{"id":1749,"depth":655,"text":1750},{"id":1877,"depth":655,"text":1878},{"id":1956,"depth":655,"text":1957},{"id":2223,"depth":655,"text":2224},{"id":2456,"depth":655,"text":2457},"Provide your StoatFlow licence — a signed file verified offline — and declare each deployment's environment and environment class, for local development, CI\u002FCD and production.","md",{},{"icon":26},null,"how-to",{"title":23,"description":2519},{"loc":24},"Oh8v5NILcpS-Fz3mThjZhCl54GF1QjO73m9xaclOXw4",[2529,2531],{"title":18,"path":19,"stem":20,"description":2530,"icon":21,"children":-1},"Add the private StoatFlow Maven repository, pull the dependency, and set up your Gradle or Maven build.",{"title":28,"path":29,"stem":30,"description":2532,"icon":31,"children":-1},"Build and run a complete word-count stream processor on the StoatFlow runtime — in Kotlin or Java.",1795299032460]