From 9e7a52d2689635d68b83a4d6754155041fe96449 Mon Sep 17 00:00:00 2001 From: Cameron Reeves Date: Wed, 7 Oct 2026 15:29:48 +1100 Subject: [PATCH 01/16] feat: PPT-526 seed the management partner and own the placeholder estate start creates the management partner and its staff organisation and attaches the first domain to it, so the seeded admin has cluster reach once tenancy enforcement is on. Placeholder rows are created owned by that organisation. Builds and clones migrations from the models tenancy branch until models #332 merges. --- Dockerfile | 3 ++- shard.override.yml | 5 +++++ src/sam.cr | 4 +++- src/tasks/entities.cr | 44 +++++++++++++++++++++++++++++++++++-- src/tasks/initialization.cr | 3 ++- 5 files changed, 54 insertions(+), 5 deletions(-) diff --git a/Dockerfile b/Dockerfile index 0708a3a..ffeb5c6 100644 --- a/Dockerfile +++ b/Dockerfile @@ -81,7 +81,8 @@ RUN for binary in /app/bin/* /usr/bin/pg_dump /usr/bin/pg_restore /usr/bin/psql; xargs -I % sh -c 'mkdir -p $(dirname deps%); cp % deps%;'; \ done -RUN git clone https://github.com/PlaceOS/models +# PPT-526: the tenancy migrations live on this branch until models #332 merges +RUN git clone --branch PPT-526-partner-client https://github.com/PlaceOS/models # Create tmp directory with proper permissions RUN rm -rf /tmp && mkdir -p /tmp && chmod 1777 /tmp diff --git a/shard.override.yml b/shard.override.yml index 9c17593..a8bb7aa 100644 --- a/shard.override.yml +++ b/shard.override.yml @@ -1,4 +1,9 @@ dependencies: + # PPT-526: build against the multi-tenancy data layer until models #332 merges + placeos-models: + github: placeos/models + branch: PPT-526-partner-client + retriable: github: Sija/retriable.cr db: diff --git a/src/sam.cr b/src/sam.cr index 06aed5e..b864ef1 100644 --- a/src/sam.cr +++ b/src/sam.cr @@ -275,7 +275,9 @@ namespace "create" do desc "Creates a representative set of documents in PostgreSQL DB" task "placeholders" do - PlaceOS::Tasks.create_placeholders + # placeholders belong to the staff organisation when one exists + staff = PlaceOS::Model::Organisation.where(partner_staff: true).first? + PlaceOS::Tasks.create_placeholders(staff.try(&.id)) end desc "Creates an authority" diff --git a/src/tasks/entities.cr b/src/tasks/entities.cr index 6f46dc1..b222b5f 100644 --- a/src/tasks/entities.cr +++ b/src/tasks/entities.cr @@ -35,6 +35,41 @@ module PlaceOS::Tasks::Entities raise e end + # The platform operator's partner and staff organisation. The first domain + # belongs to that organisation, so its admins have cluster reach once + # tenancy enforcement is on. + def create_management_organisation( + authority : Model::Authority, + partner_name : String = "PlaceOS", + ) : Model::Organisation + partner = upsert_document(Model::Partner.where(management: true)) do + Log.info { {message: "creating management Partner", name: partner_name} } + Model::Partner.new(name: partner_name, description: "Platform operator (management partner)").tap do |new_partner| + new_partner.management = true + end + end + + organisation = upsert_document(Model::Organisation.where(partner_id: partner.id, partner_staff: true)) do + Log.info { {message: "creating staff Organisation", name: authority.name} } + Model::Organisation.new(name: "#{partner_name} staff", description: "Staff of the management partner").tap do |new_org| + new_org.partner_id = partner.id + new_org.partner_staff = true + new_org.payer = Model::Organisation::PAYER_ORGANISATION + end + end + + if authority.organisation_id.nil? + authority.organisation_id = organisation.id + authority.save! + Log.info { {message: "attached Authority to staff Organisation", authority: authority.id, organisation: organisation.id.to_s} } + end + + organisation + rescue e + log_fail("Organisation", e) + raise e + end + def create_interface( name : String, folder_name : String, @@ -141,7 +176,7 @@ module PlaceOS::Tasks::Entities raise e end - def create_placeholders + def create_placeholders(organisation_id : UUID? = nil) version = UUID.random.to_s.split('-').first private_repository_uri = "https://github.com/placeos/private-drivers" @@ -201,6 +236,7 @@ module PlaceOS::Tasks::Entities Model::Zone.new.tap do |zone| zone.name = "Zone-#{tag}-#{version}" zone.tags = Set{tag} + zone.organisation_id = organisation_id end end end @@ -213,7 +249,9 @@ module PlaceOS::Tasks::Entities zones[2].save! control_system = upsert_document(Model::ControlSystem.all) do - Model::ControlSystem.new(name: "System-#{version}") + Model::ControlSystem.new(name: "System-#{version}").tap do |sys| + sys.organisation_id = organisation_id + end end upsert_document(Model::Settings.for_parent(control_system.id.as(String))) do @@ -227,6 +265,7 @@ module PlaceOS::Tasks::Entities mod = upsert_document(Model::Module.where(driver_id: driver.id.as(String), control_system_id: control_system.id.as(String))) do Model::Generator.module(driver: driver, control_system: control_system).tap do |new_module| new_module.custom_name = "Module-#{version}" + new_module.organisation_id = organisation_id end end @@ -241,6 +280,7 @@ module PlaceOS::Tasks::Entities trigger_description = "An automatically generated Trigger." new_trigger = Model::Trigger.new(name: trigger_name, description: trigger_description) new_trigger.control_system = control_system + new_trigger.organisation_id = organisation_id new_trigger end diff --git a/src/tasks/initialization.cr b/src/tasks/initialization.cr index ad2199e..0bbf5e8 100644 --- a/src/tasks/initialization.cr +++ b/src/tasks/initialization.cr @@ -33,6 +33,7 @@ module PlaceOS::Tasks::Initialization start_lock.synchronize do authority = Entities.create_authority(name: application_base, domain: application_base, config: metrics_config) + organisation = Entities.create_management_organisation(authority) Entities.create_user(authority: authority, name: username, email: email, password: password, sys_admin: true) Entities.create_application(authority: authority, name: application_name, base: application_base) @@ -53,7 +54,7 @@ module PlaceOS::Tasks::Initialization unless PlaceOS::Tasks.production? || PlaceOS::SKIP_PLACEHOLDERS Log.info { "creating placeholder documents" } - Entities.create_placeholders + Entities.create_placeholders(organisation.id) end end end From 0a66f58c910f8a4dc4d0d186dd85b6cfafbfba23 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Fri, 6 Nov 2026 15:04:46 +1100 Subject: [PATCH 02/16] chore: PPT-526 track the rebased models tenancy branch at b502009 Picks up pg-orm 2.5.3, which models now requires. Co-Authored-By: Claude Opus 5.5 --- shard.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/shard.lock b/shard.lock index 7eb8504..23a9d0b 100644 --- a/shard.lock +++ b/shard.lock @@ -143,7 +143,7 @@ shards: pg-orm: git: https://github.com/spider-gazelle/pg-orm.git - version: 2.5.2 + version: 2.5.3 place_calendar: git: https://github.com/placeos/calendar.git @@ -153,9 +153,9 @@ shards: git: https://github.com/place-labs/log-backend.git version: 0.13.0 - placeos-models: + placeos-models: # Overridden git: https://github.com/placeos/models.git - version: 9.123.3 + version: 9.123.4+git.commit.b50200942c7e6bf30d999c1f500ce1375408edc0 sam: git: https://github.com/imdrasil/sam.cr.git From a0a409d1ad935f5e1956e71a9b401368fe416d2b Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Fri, 6 Nov 2026 15:04:46 +1100 Subject: [PATCH 03/16] test: PPT-526 migrate the spec database from the models tenancy branch The spec migrator cloned models master, so specs ran without the tenancy columns the seeding code writes. Co-Authored-By: Claude Opus 5.5 --- spec/migration/Dockerfile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/migration/Dockerfile b/spec/migration/Dockerfile index 11531ab..76b4070 100644 --- a/spec/migration/Dockerfile +++ b/spec/migration/Dockerfile @@ -5,7 +5,8 @@ WORKDIR /app COPY . /app # NOTE:: add `--branch my-new-model-branch` if you want to test a particular branch -RUN git clone https://github.com/PlaceOS/models +# PPT-526: the tenancy migrations live on this branch until models #332 merges +RUN git clone --branch PPT-526-partner-client https://github.com/PlaceOS/models RUN mv ./models/migration/db ./db ENV PATH /app/bin:$PATH From e156c1c7f91690a1f1451fd778ddbe91ed7cf747 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Fri, 6 Nov 2026 15:11:07 +1100 Subject: [PATCH 04/16] feat: PPT-526 move a backfilled first domain into the staff organisation On a cluster that predates tenancy the backfill migration runs before `start` and gives the first domain an organisation of its own, so the seeding never attached it to the staff organisation and its admins would have no cluster reach once enforcement is on. While that organisation is still as the backfill created it (no partner, no other domain, the backfill's description), move everything it owns and the grants scoped to it into the staff organisation and remove it, in one transaction. Organisations an operator has changed are left alone. Co-Authored-By: Claude Opus 5.5 --- spec/entities_spec.cr | 92 +++++++++++++++++++++++++++++++++++++++++++ spec/spec_helper.cr | 3 +- src/tasks/entities.cr | 44 +++++++++++++++++++++ 3 files changed, 138 insertions(+), 1 deletion(-) create mode 100644 spec/entities_spec.cr diff --git a/spec/entities_spec.cr b/spec/entities_spec.cr new file mode 100644 index 0000000..2966037 --- /dev/null +++ b/spec/entities_spec.cr @@ -0,0 +1,92 @@ +require "./spec_helper" +require "../src/tasks/entities" + +module PlaceOS::Tasks + # The organisation the backfill migration creates for a domain that has none + def self.backfilled_organisation(authority : Model::Authority) : Model::Organisation + organisation = Model::Organisation.new( + name: "#{authority.name} (#{authority.domain})", + description: "Auto-created from authority #{authority.id} during PPT-526 organisation backfill", + ).save! + authority.organisation_id = organisation.id + authority.save! + organisation + end + + def self.owned_zone(organisation : Model::Organisation) : Model::Zone + zone = Model::Zone.new(name: "zone-#{Random::Secure.hex(4)}", tags: Set{"org"}) + zone.organisation_id = organisation.id + zone.save! + end + + def self.organisation_grant(organisation : Model::Organisation) : Model::Grant + user = Model::Generator.user.save! + Model::Generator.grant(user, Model::Grant::SCOPE_ORGANISATION, organisation.id.to_s) + end + + describe Entities do + describe "create_management_organisation" do + it "seeds the management partner and attaches an unowned domain to its staff organisation" do + authority = Model::Generator.authority("https://first.example.com").save! + + organisation = Entities.create_management_organisation(authority) + + organisation.partner_staff.should be_true + organisation.partner.not_nil!.management.should be_true + Model::Authority.find!(authority.id.as(String)).organisation_id.should eq organisation.id + end + + it "is idempotent" do + authority = Model::Generator.authority("https://first.example.com").save! + + first = Entities.create_management_organisation(authority) + second = Entities.create_management_organisation(Model::Authority.find!(authority.id.as(String))) + + second.id.should eq first.id + Model::Partner.where(management: true).count.should eq 1 + Model::Organisation.where(partner_staff: true).count.should eq 1 + end + + it "moves a backfilled estate into the staff organisation" do + authority = Model::Generator.authority("https://first.example.com").save! + backfilled = backfilled_organisation(authority) + zone = owned_zone(backfilled) + grant = organisation_grant(backfilled).save! + + organisation = Entities.create_management_organisation(authority) + + authority.organisation_id.should eq organisation.id + Model::Authority.find!(authority.id.as(String)).organisation_id.should eq organisation.id + Model::Zone.find!(zone.id.as(String)).organisation_id.should eq organisation.id + Model::Grant.find!(grant.id.not_nil!).scope_id.should eq organisation.id.to_s + Model::Organisation.find?(backfilled.id.not_nil!).should be_nil + end + + it "leaves an organisation an operator has changed" do + authority = Model::Generator.authority("https://first.example.com").save! + backfilled = backfilled_organisation(authority) + backfilled.description = "Acme, merged by hand" + backfilled.save! + zone = owned_zone(backfilled) + + Entities.create_management_organisation(authority) + + Model::Authority.find!(authority.id.as(String)).organisation_id.should eq backfilled.id + Model::Zone.find!(zone.id.as(String)).organisation_id.should eq backfilled.id + end + + it "leaves an organisation that owns other domains" do + authority = Model::Generator.authority("https://first.example.com").save! + backfilled = backfilled_organisation(authority) + other = Model::Generator.authority("https://second.example.com") + other.organisation_id = backfilled.id + other.save! + + Entities.create_management_organisation(authority) + + Model::Authority.find!(authority.id.as(String)).organisation_id.should eq backfilled.id + Model::Organisation.find?(backfilled.id.not_nil!).should_not be_nil + end + end + end +end diff --git a/spec/spec_helper.cr b/spec/spec_helper.cr index 41cb4df..fdeae80 100644 --- a/spec/spec_helper.cr +++ b/spec/spec_helper.cr @@ -8,7 +8,8 @@ PgORM::Database.configure { |_| } def clear_tables PgORM::Database.exec_sql <<-SQL TRUNCATE "asset", "asset_type", "asset_category", "metadata", "zone", - "booking_instances", "bookings", "tenants", "shortener", "user", "authority", "history" CASCADE + "booking_instances", "bookings", "tenants", "shortener", "user", "authority", "history", + "grants", "partners" CASCADE SQL end diff --git a/src/tasks/entities.cr b/src/tasks/entities.cr index b222b5f..6c90a33 100644 --- a/src/tasks/entities.cr +++ b/src/tasks/entities.cr @@ -35,9 +35,16 @@ module PlaceOS::Tasks::Entities raise e end + # Tables whose rows an organisation owns through `organisation_id` + OWNED_TABLES = {"authority", "zone", "sys", "mod", "trigger", "edge", "broker"} + # The platform operator's partner and staff organisation. The first domain # belongs to that organisation, so its admins have cluster reach once # tenancy enforcement is on. + # + # On a cluster that predates tenancy the backfill migration has already + # given the first domain an organisation of its own. While that organisation + # is untouched, its estate moves into the staff organisation. def create_management_organisation( authority : Model::Authority, partner_name : String = "PlaceOS", @@ -62,6 +69,10 @@ module PlaceOS::Tasks::Entities authority.organisation_id = organisation.id authority.save! Log.info { {message: "attached Authority to staff Organisation", authority: authority.id, organisation: organisation.id.to_s} } + elsif backfilled = backfilled_organisation(authority) + adopt_estate(from: backfilled, into: organisation) + authority.organisation_id = organisation.id + Log.info { {message: "moved the backfilled estate into the staff Organisation", authority: authority.id, from: backfilled.id.to_s, organisation: organisation.id.to_s} } end organisation @@ -70,6 +81,39 @@ module PlaceOS::Tasks::Entities raise e end + # The organisation the backfill migration created for this authority, while + # it is still as created: no partner, no other domain and the backfill's own + # description. Anything an operator has since changed is left alone. + protected def backfilled_organisation(authority : Model::Authority) : Model::Organisation? + organisation_id = authority.organisation_id + return unless organisation_id + + organisation = Model::Organisation.find?(organisation_id) + return unless organisation + return unless organisation.partner_id.nil? + return unless organisation.description == "Auto-created from authority #{authority.id} during PPT-526 organisation backfill" + return unless organisation.authorities.count == 1 + + organisation + end + + # Moves every row and grant owned by `from` to `into`, then removes `from` + protected def adopt_estate(from : Model::Organisation, into : Model::Organisation) : Nil + from_id = from.id.to_s + into_id = into.id.to_s + + PgORM::Database.transaction do |tx| + OWNED_TABLES.each do |table| + tx.connection.exec(%(UPDATE "#{table}" SET organisation_id = $1::uuid WHERE organisation_id = $2::uuid), args: [into_id, from_id]) + end + tx.connection.exec( + %(UPDATE "grants" SET scope_id = $1 WHERE scope_type = $2 AND scope_id = $3), + args: [into_id, Model::Grant::SCOPE_ORGANISATION, from_id], + ) + from.destroy + end + end + def create_interface( name : String, folder_name : String, From b28f7f2f4f4f1009ec0a7ce7b17bae0a49328210 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Mon, 16 Nov 2026 14:16:20 +1100 Subject: [PATCH 05/16] fix: limit image compiler threads --- Dockerfile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Dockerfile b/Dockerfile index ffeb5c6..f0f84dd 100644 --- a/Dockerfile +++ b/Dockerfile @@ -43,8 +43,10 @@ COPY src src RUN mkdir -p /app/bin +# Limit LLVM workers while Buildx compiles both architectures concurrently. # Build init RUN shards build \ + --threads 1 \ --debug \ --ignore-crystal-version \ --skip-postinstall \ @@ -55,6 +57,7 @@ RUN shards build \ --link-flags "-no-pie -Wl,-no-pie -Wl,--eh-frame-hdr -Wl,--build-id -rdynamic -Wl,--export-dynamic -lunwind -llzma" RUN crystal build src/sam.cr -o bin/task \ + --threads 1 \ --debug \ --error-trace \ --no-color \ @@ -63,6 +66,7 @@ RUN crystal build src/sam.cr -o bin/task \ --link-flags "-no-pie -Wl,-no-pie -Wl,--eh-frame-hdr -Wl,--build-id -rdynamic -Wl,--export-dynamic -lunwind -llzma" RUN crystal build src/generate-secrets.cr -o bin/generate-secrets \ + --threads 1 \ --debug \ --error-trace \ --no-color \ From 8b67d6cbbde09e46b1f1b4868fdbe466a269a6e0 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Mon, 16 Nov 2026 14:18:42 +1100 Subject: [PATCH 06/16] fix: forward compiler thread limit --- Dockerfile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Dockerfile b/Dockerfile index f0f84dd..0bb0e61 100644 --- a/Dockerfile +++ b/Dockerfile @@ -46,7 +46,7 @@ RUN mkdir -p /app/bin # Limit LLVM workers while Buildx compiles both architectures concurrently. # Build init RUN shards build \ - --threads 1 \ + --threads=1 \ --debug \ --ignore-crystal-version \ --skip-postinstall \ @@ -57,7 +57,7 @@ RUN shards build \ --link-flags "-no-pie -Wl,-no-pie -Wl,--eh-frame-hdr -Wl,--build-id -rdynamic -Wl,--export-dynamic -lunwind -llzma" RUN crystal build src/sam.cr -o bin/task \ - --threads 1 \ + --threads=1 \ --debug \ --error-trace \ --no-color \ @@ -66,7 +66,7 @@ RUN crystal build src/sam.cr -o bin/task \ --link-flags "-no-pie -Wl,-no-pie -Wl,--eh-frame-hdr -Wl,--build-id -rdynamic -Wl,--export-dynamic -lunwind -llzma" RUN crystal build src/generate-secrets.cr -o bin/generate-secrets \ - --threads 1 \ + --threads=1 \ --debug \ --error-trace \ --no-color \ From e7c8aed860be695d37068d6f8c42be956709874a Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:36:28 +1100 Subject: [PATCH 07/16] test: preserve customer tenancy during bootstrap --- spec/entities_spec.cr | 28 +++++++++++---- spec/initialization_tenancy_spec.cr | 54 +++++++++++++++++++++++++++++ spec/spec_helper.cr | 2 +- 3 files changed, 76 insertions(+), 8 deletions(-) create mode 100644 spec/initialization_tenancy_spec.cr diff --git a/spec/entities_spec.cr b/spec/entities_spec.cr index 2966037..6aa16f2 100644 --- a/spec/entities_spec.cr +++ b/spec/entities_spec.cr @@ -47,19 +47,33 @@ module PlaceOS::Tasks Model::Organisation.where(partner_staff: true).count.should eq 1 end - it "moves a backfilled estate into the staff organisation" do + it "preserves a backfilled customer's estate and grants" do authority = Model::Generator.authority("https://first.example.com").save! backfilled = backfilled_organisation(authority) zone = owned_zone(backfilled) grant = organisation_grant(backfilled).save! - organisation = Entities.create_management_organisation(authority) + Entities.create_management_organisation(authority) - authority.organisation_id.should eq organisation.id - Model::Authority.find!(authority.id.as(String)).organisation_id.should eq organisation.id - Model::Zone.find!(zone.id.as(String)).organisation_id.should eq organisation.id - Model::Grant.find!(grant.id.not_nil!).scope_id.should eq organisation.id.to_s - Model::Organisation.find?(backfilled.id.not_nil!).should be_nil + Model::Authority.find!(authority.id.as(String)).organisation_id.should eq backfilled.id + Model::Zone.find!(zone.id.as(String)).organisation_id.should eq backfilled.id + Model::Grant.find!(grant.id.not_nil!).scope_id.should eq backfilled.id.to_s + Model::Organisation.find?(backfilled.id.not_nil!).should_not be_nil + end + + it "preserves a renamed and configured customer organisation with its generated description" do + authority = Model::Generator.authority("https://customer.example.com").save! + backfilled = backfilled_organisation(authority) + backfilled.name = "Customer organisation" + backfilled.config["billing_reference"] = JSON::Any.new("customer-owned") + backfilled.save! + + Entities.create_management_organisation(authority) + + persisted = Model::Organisation.find!(backfilled.id.not_nil!) + persisted.name.should eq "Customer organisation" + persisted.config["billing_reference"].as_s.should eq "customer-owned" + Model::Authority.find!(authority.id.as(String)).organisation_id.should eq backfilled.id end it "leaves an organisation an operator has changed" do diff --git a/spec/initialization_tenancy_spec.cr b/spec/initialization_tenancy_spec.cr new file mode 100644 index 0000000..427962a --- /dev/null +++ b/spec/initialization_tenancy_spec.cr @@ -0,0 +1,54 @@ +require "./spec_helper" +require "../src/tasks/initialization" + +module PlaceOS + module Tasks + def self.production? : Bool + true + end + + def self.start_customer_install(domain : String) + Initialization.start( + application_name: "backoffice", + domain: domain, + tls: false, + email: "administrator@example.com", + username: "Administrator", + password: "a-test-password-12345", + auth_host: "auth", + metrics_route: "monitor", + backoffice_branch: "master", + backoffice_commit: "HEAD", + ) + end + + describe "customer tenancy bootstrap" do + it "keeps an existing customer's configured domain out of management staff" do + authority = Model::Generator.authority("customer.example.com").save! + organisation = Model::Organisation.new( + name: "Existing customer", + description: "Auto-created from authority #{authority.id} during PPT-526 organisation backfill", + ).save! + authority.organisation_id = organisation.id + authority.save! + + start_customer_install(authority.domain) + + persisted = Model::Authority.find!(authority.id.as(String)) + persisted.organisation_id.should eq organisation.id + persisted.organisation.not_nil!.partner_staff.should be_false + Model::Partner.where(management: true).count.should eq 0 + end + + it "creates an ordinary organisation for a fresh default customer install" do + start_customer_install("fresh-customer.example.com") + + authority = Model::Authority.find_by_domain("fresh-customer.example.com").not_nil! + organisation = authority.organisation.not_nil! + organisation.partner_staff.should be_false + organisation.partner_id.should be_nil + Model::Partner.where(management: true).count.should eq 0 + end + end + end +end diff --git a/spec/spec_helper.cr b/spec/spec_helper.cr index fdeae80..0b9c65c 100644 --- a/spec/spec_helper.cr +++ b/spec/spec_helper.cr @@ -9,7 +9,7 @@ def clear_tables PgORM::Database.exec_sql <<-SQL TRUNCATE "asset", "asset_type", "asset_category", "metadata", "zone", "booking_instances", "bookings", "tenants", "shortener", "user", "authority", "history", - "grants", "partners" CASCADE + "grants", "organisations", "partners" CASCADE SQL end From 1ce02b1c97ef4311270b0f7b27ccd9f041bb8a4e Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:37:55 +1100 Subject: [PATCH 08/16] test: preserve fresh platform bootstrap privileges --- spec/initialization_tenancy_spec.cr | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/initialization_tenancy_spec.cr b/spec/initialization_tenancy_spec.cr index 427962a..c98b4ef 100644 --- a/spec/initialization_tenancy_spec.cr +++ b/spec/initialization_tenancy_spec.cr @@ -40,14 +40,14 @@ module PlaceOS Model::Partner.where(management: true).count.should eq 0 end - it "creates an ordinary organisation for a fresh default customer install" do + it "preserves management privileges for a fresh platform bootstrap" do start_customer_install("fresh-customer.example.com") authority = Model::Authority.find_by_domain("fresh-customer.example.com").not_nil! organisation = authority.organisation.not_nil! - organisation.partner_staff.should be_false - organisation.partner_id.should be_nil - Model::Partner.where(management: true).count.should eq 0 + organisation.partner_staff.should be_true + organisation.partner.not_nil!.management.should be_true + Model::User.find_by_email(authority.id.as(String), "administrator@example.com").not_nil!.sys_admin.should be_true end end end From d5b5083d0f0f1e56f7200a5c4315765157ea04cc Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:42:23 +1100 Subject: [PATCH 09/16] fix: preserve existing customer organisations at bootstrap --- src/tasks/entities.cr | 62 +++++++--------------------------------- tasks/lessons.md | 3 ++ tasks/tenancy-upgrade.md | 6 ++++ 3 files changed, 19 insertions(+), 52 deletions(-) create mode 100644 tasks/lessons.md create mode 100644 tasks/tenancy-upgrade.md diff --git a/src/tasks/entities.cr b/src/tasks/entities.cr index 6c90a33..200ec8d 100644 --- a/src/tasks/entities.cr +++ b/src/tasks/entities.cr @@ -35,20 +35,17 @@ module PlaceOS::Tasks::Entities raise e end - # Tables whose rows an organisation owns through `organisation_id` - OWNED_TABLES = {"authority", "zone", "sys", "mod", "trigger", "edge", "broker"} - - # The platform operator's partner and staff organisation. The first domain - # belongs to that organisation, so its admins have cluster reach once - # tenancy enforcement is on. - # - # On a cluster that predates tenancy the backfill migration has already - # given the first domain an organisation of its own. While that organisation - # is untouched, its estate moves into the staff organisation. + # Preserve an existing customer's ownership and configuration. Only a newly + # created bootstrap authority without an organisation seeds platform staff. + # Moving a legacy customer into management requires explicit reconciliation. def create_management_organisation( authority : Model::Authority, partner_name : String = "PlaceOS", ) : Model::Organisation + if organisation_id = authority.organisation_id + return Model::Organisation.find!(organisation_id) + end + partner = upsert_document(Model::Partner.where(management: true)) do Log.info { {message: "creating management Partner", name: partner_name} } Model::Partner.new(name: partner_name, description: "Platform operator (management partner)").tap do |new_partner| @@ -65,15 +62,9 @@ module PlaceOS::Tasks::Entities end end - if authority.organisation_id.nil? - authority.organisation_id = organisation.id - authority.save! - Log.info { {message: "attached Authority to staff Organisation", authority: authority.id, organisation: organisation.id.to_s} } - elsif backfilled = backfilled_organisation(authority) - adopt_estate(from: backfilled, into: organisation) - authority.organisation_id = organisation.id - Log.info { {message: "moved the backfilled estate into the staff Organisation", authority: authority.id, from: backfilled.id.to_s, organisation: organisation.id.to_s} } - end + authority.organisation_id = organisation.id + authority.save! + Log.info { {message: "attached new bootstrap Authority to staff Organisation", authority: authority.id, organisation: organisation.id.to_s} } organisation rescue e @@ -81,39 +72,6 @@ module PlaceOS::Tasks::Entities raise e end - # The organisation the backfill migration created for this authority, while - # it is still as created: no partner, no other domain and the backfill's own - # description. Anything an operator has since changed is left alone. - protected def backfilled_organisation(authority : Model::Authority) : Model::Organisation? - organisation_id = authority.organisation_id - return unless organisation_id - - organisation = Model::Organisation.find?(organisation_id) - return unless organisation - return unless organisation.partner_id.nil? - return unless organisation.description == "Auto-created from authority #{authority.id} during PPT-526 organisation backfill" - return unless organisation.authorities.count == 1 - - organisation - end - - # Moves every row and grant owned by `from` to `into`, then removes `from` - protected def adopt_estate(from : Model::Organisation, into : Model::Organisation) : Nil - from_id = from.id.to_s - into_id = into.id.to_s - - PgORM::Database.transaction do |tx| - OWNED_TABLES.each do |table| - tx.connection.exec(%(UPDATE "#{table}" SET organisation_id = $1::uuid WHERE organisation_id = $2::uuid), args: [into_id, from_id]) - end - tx.connection.exec( - %(UPDATE "grants" SET scope_id = $1 WHERE scope_type = $2 AND scope_id = $3), - args: [into_id, Model::Grant::SCOPE_ORGANISATION, from_id], - ) - from.destroy - end - end - def create_interface( name : String, folder_name : String, diff --git a/tasks/lessons.md b/tasks/lessons.md new file mode 100644 index 0000000..1fffbf4 --- /dev/null +++ b/tasks/lessons.md @@ -0,0 +1,3 @@ +# Lessons + +- Preserve fresh platform bootstrap administration when correcting legacy adoption. Existing customer ownership and new platform setup are different cases; protect both with explicit regression assertions before changing startup defaults. diff --git a/tasks/tenancy-upgrade.md b/tasks/tenancy-upgrade.md new file mode 100644 index 0000000..3f12851 --- /dev/null +++ b/tasks/tenancy-upgrade.md @@ -0,0 +1,6 @@ +# Tenancy bootstrap upgrade safety + +- [x] Obtain CI assertion failures for existing customer preservation and default bootstrap (1ce02b1, CI 43971923707). +- [x] Preserve customer ownership, names, configuration and grants on every normal startup. +- [x] Preserve fresh platform-management bootstrap privileges; refuse implicit legacy customer adoption. +- [ ] Verify formatting, lint, native semantic checks and GitHub CI. From 6bbdbd8f9bfa9cb0088847f940053cb8336a42c9 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:45:23 +1100 Subject: [PATCH 10/16] test: persist customer configuration in bootstrap fixture --- spec/entities_spec.cr | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/entities_spec.cr b/spec/entities_spec.cr index 6aa16f2..afd931f 100644 --- a/spec/entities_spec.cr +++ b/spec/entities_spec.cr @@ -65,8 +65,9 @@ module PlaceOS::Tasks authority = Model::Generator.authority("https://customer.example.com").save! backfilled = backfilled_organisation(authority) backfilled.name = "Customer organisation" - backfilled.config["billing_reference"] = JSON::Any.new("customer-owned") + backfilled.config = {"billing_reference" => JSON::Any.new("customer-owned")} backfilled.save! + Model::Organisation.find!(backfilled.id.not_nil!).config["billing_reference"].as_s.should eq "customer-owned" Entities.create_management_organisation(authority) From 3472c3bebf5978c230d04cbadf7409f0b1053b58 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:50:37 +1100 Subject: [PATCH 11/16] test: distinguish existing unowned authorities from bootstrap --- spec/initialization_tenancy_spec.cr | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/spec/initialization_tenancy_spec.cr b/spec/initialization_tenancy_spec.cr index c98b4ef..d959667 100644 --- a/spec/initialization_tenancy_spec.cr +++ b/spec/initialization_tenancy_spec.cr @@ -49,6 +49,15 @@ module PlaceOS organisation.partner.not_nil!.management.should be_true Model::User.find_by_email(authority.id.as(String), "administrator@example.com").not_nil!.sys_admin.should be_true end + + it "does not treat an existing unowned authority as a fresh management bootstrap" do + authority = Model::Generator.authority("legacy-unowned.example.com").save! + + start_customer_install(authority.domain) + + Model::Authority.find!(authority.id.as(String)).organisation_id.should be_nil + Model::Partner.where(management: true).count.should eq 0 + end end end end From a51674babf65c5ba40daba1eca5e35b889182639 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:56:28 +1100 Subject: [PATCH 12/16] fix: preserve unowned legacy authorities during startup --- src/tasks/initialization.cr | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/tasks/initialization.cr b/src/tasks/initialization.cr index 0bbf5e8..225333e 100644 --- a/src/tasks/initialization.cr +++ b/src/tasks/initialization.cr @@ -32,8 +32,16 @@ module PlaceOS::Tasks::Initialization metrics_config = {"metrics" => JSON::Any.new(metrics_url)} start_lock.synchronize do - authority = Entities.create_authority(name: application_base, domain: application_base, config: metrics_config) - organisation = Entities.create_management_organisation(authority) + existing_authority = Model::Authority.find_by_domain(application_base) + authority = existing_authority || Entities.create_authority(name: application_base, domain: application_base, config: metrics_config) + organisation = if existing_authority + authority.organisation + else + Entities.create_management_organisation(authority) + end + unless organisation + Log.warn { {message: "existing authority has no organisation; explicit reconciliation is required", authority: authority.id} } + end Entities.create_user(authority: authority, name: username, email: email, password: password, sys_admin: true) Entities.create_application(authority: authority, name: application_name, base: application_base) @@ -52,7 +60,7 @@ module PlaceOS::Tasks::Initialization description: "Admin interface for PlaceOS", ) - unless PlaceOS::Tasks.production? || PlaceOS::SKIP_PLACEHOLDERS + unless PlaceOS::Tasks.production? || PlaceOS::SKIP_PLACEHOLDERS || organisation.nil? Log.info { "creating placeholder documents" } Entities.create_placeholders(organisation.id) end From f59ba80feb5202771de97d64ab6da79f72388420 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:14:50 +1100 Subject: [PATCH 13/16] test: isolate placeholder provisioning by organisation --- spec/entities_spec.cr | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/spec/entities_spec.cr b/spec/entities_spec.cr index afd931f..62890b7 100644 --- a/spec/entities_spec.cr +++ b/spec/entities_spec.cr @@ -25,6 +25,28 @@ module PlaceOS::Tasks end describe Entities do + it "creates organisation-specific placeholders while sharing driver and repository catalogs" do + first = Model::Generator.organisation.save! + second = Model::Generator.organisation.save! + Entities.create_placeholders(first.id) + first_zones = Model::Zone.where(organisation_id: first.id).to_a + original_parents = first_zones.to_h { |zone| {zone.id.as(String), zone.parent_id} } + driver_count = Model::Driver.all.count + repository_count = Model::Repository.all.count + + Entities.create_placeholders(second.id) + + second_zones = Model::Zone.where(organisation_id: second.id).to_a + second_zones.size.should eq 4 + second_system = Model::ControlSystem.where(organisation_id: second.id).first.not_nil! + second_system.zones.to_set.should eq second_zones.map(&.id.as(String)).to_set + Model::Module.where(organisation_id: second.id).count.should eq 1 + Model::Trigger.where(organisation_id: second.id).count.should eq 1 + Model::Zone.where(organisation_id: first.id).to_a.to_h { |zone| {zone.id.as(String), zone.parent_id} }.should eq original_parents + Model::Driver.all.count.should eq driver_count + Model::Repository.all.count.should eq repository_count + end + describe "create_management_organisation" do it "seeds the management partner and attaches an unowned domain to its staff organisation" do authority = Model::Generator.authority("https://first.example.com").save! From bc5f63f1dfee0091826d1c4ba2715df46f02dbe3 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:26:51 +1100 Subject: [PATCH 14/16] fix: scope placeholder provisioning to its organisation --- src/tasks/entities.cr | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/tasks/entities.cr b/src/tasks/entities.cr index 200ec8d..7205bc1 100644 --- a/src/tasks/entities.cr +++ b/src/tasks/entities.cr @@ -234,7 +234,9 @@ module PlaceOS::Tasks::Entities # Create default entities for each element of the hierarchy zones = {"building", "org", "level", "area"}.map do |tag| - upsert_document(Model::Zone.with_tag(tag)) do + query = Model::Zone.where("? = ANY(tags)", tag) + query = query.where(organisation_id: organisation_id) if organisation_id + upsert_document(query) do Model::Zone.new.tap do |zone| zone.name = "Zone-#{tag}-#{version}" zone.tags = Set{tag} @@ -250,7 +252,9 @@ module PlaceOS::Tasks::Entities zones[2].parent_id = zones.first.id zones[2].save! - control_system = upsert_document(Model::ControlSystem.all) do + system_query = Model::ControlSystem.all + system_query = system_query.where(organisation_id: organisation_id) if organisation_id + control_system = upsert_document(system_query) do Model::ControlSystem.new(name: "System-#{version}").tap do |sys| sys.organisation_id = organisation_id end @@ -264,7 +268,9 @@ module PlaceOS::Tasks::Entities settings end - mod = upsert_document(Model::Module.where(driver_id: driver.id.as(String), control_system_id: control_system.id.as(String))) do + module_query = Model::Module.where(driver_id: driver.id.as(String), control_system_id: control_system.id.as(String)) + module_query = module_query.where(organisation_id: organisation_id) if organisation_id + mod = upsert_document(module_query) do Model::Generator.module(driver: driver, control_system: control_system).tap do |new_module| new_module.custom_name = "Module-#{version}" new_module.organisation_id = organisation_id @@ -276,7 +282,9 @@ module PlaceOS::Tasks::Entities control_system.zones = control_system.zones | zones.compact_map &.id control_system.save! - trigger = upsert_document(Model::Trigger.where(control_system_id: control_system.id.as(String))) do + trigger_query = Model::Trigger.where(control_system_id: control_system.id.as(String)) + trigger_query = trigger_query.where(organisation_id: organisation_id) if organisation_id + trigger = upsert_document(trigger_query) do # Trigger metadata trigger_name = "Trigger-#{version}" trigger_description = "An automatically generated Trigger." From bb2efe10982513eaedd8ef57bd95b5dce3913a81 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:48:33 +1100 Subject: [PATCH 15/16] docs: explain explicit legacy management bootstrap --- README.md | 30 ++++++++++++++++++++++++++++++ spec/entities_spec.cr | 9 +++++++++ 2 files changed, 39 insertions(+) diff --git a/README.md b/README.md index af17525..3dcfdbb 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,36 @@ The default entrypoint to the init container generates a User, Authority, and Ap - `backoffice_branch`: `PLACE_BACKOFFICE_BRANCH`, `build/prod` or `build/dev` dependent on environment. - `backoffice_commmit`: `PLACE_BACKOFFICE_COMMIT` ||`"HEAD"` +### Management access on an existing cluster + +Normal startup preserves an existing authority's organisation, including its name, +configuration and grants. An existing unowned authority remains unowned for explicit +reconciliation; rerunning init does not promote it to management staff. + +If a legacy cluster has no management-domain administrator, choose a **new** +management hostname routed to the existing deployment. It must not already have an +Authority record: do not pre-create it with `create:authority`. Run the normal init +startup against that hostname using the existing cluster's database connection and +platform secrets, with dedicated administrator credentials: + +```bash +# Set NEW_PLATFORM_PASSWORD to a new strong password before running this command. +docker compose run --rm --no-deps \ + -e PLACE_DOMAIN=management.example.com \ + -e PLACE_TLS=true \ + -e PLACE_EMAIL=platform-admin@example.com \ + -e PLACE_USERNAME="Platform administrator" \ + -e PLACE_PASSWORD="$NEW_PLATFORM_PASSWORD" \ + -e PLACE_SKIP_PLACEHOLDERS=true \ + init /app/bin/start +``` + +Only the newly created authority is attached to the management partner's staff +organisation, and its seeded administrator retains platform administration rights. +Sign in through the management hostname and use the REST tenancy inventory and +explicit reconciliation operations before enabling `PLACE_TENANCY_ENFORCE` for +customer traffic. Existing customer domains are never adopted or merged implicitly. + ## Backup Container `Dockerfile.pg-backup` generates a container that will backup the state of PG to `S3` or `Azure Storage` depending on the environment variables. diff --git a/spec/entities_spec.cr b/spec/entities_spec.cr index 62890b7..a8ee3af 100644 --- a/spec/entities_spec.cr +++ b/spec/entities_spec.cr @@ -26,6 +26,8 @@ module PlaceOS::Tasks describe Entities do it "creates organisation-specific placeholders while sharing driver and repository catalogs" do + previous_mode = ENV["PLACE_TENANCY_ENFORCE"]? + ENV["PLACE_TENANCY_ENFORCE"] = "false" first = Model::Generator.organisation.save! second = Model::Generator.organisation.save! Entities.create_placeholders(first.id) @@ -38,6 +40,7 @@ module PlaceOS::Tasks second_zones = Model::Zone.where(organisation_id: second.id).to_a second_zones.size.should eq 4 + (second_zones.map(&.name).to_set & first_zones.map(&.name).to_set).should be_empty second_system = Model::ControlSystem.where(organisation_id: second.id).first.not_nil! second_system.zones.to_set.should eq second_zones.map(&.id.as(String)).to_set Model::Module.where(organisation_id: second.id).count.should eq 1 @@ -45,6 +48,12 @@ module PlaceOS::Tasks Model::Zone.where(organisation_id: first.id).to_a.to_h { |zone| {zone.id.as(String), zone.parent_id} }.should eq original_parents Model::Driver.all.count.should eq driver_count Model::Repository.all.count.should eq repository_count + ensure + if previous_mode + ENV["PLACE_TENANCY_ENFORCE"] = previous_mode + else + ENV.delete("PLACE_TENANCY_ENFORCE") + end end describe "create_management_organisation" do From 2a986f86e0888fae6782ef09d5a63d566ce6e404 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:53:38 +1100 Subject: [PATCH 16/16] fix: pin reviewed ownership migrations --- shard.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shard.lock b/shard.lock index 4010a04..c571a7c 100644 --- a/shard.lock +++ b/shard.lock @@ -155,7 +155,7 @@ shards: placeos-models: # Overridden git: https://github.com/placeos/models.git - version: 9.123.5+git.commit.5adba67b9eb9a35fa007a5914074738fa47dcb39 + version: 9.123.5+git.commit.716ca764f68e09a72b9028aa3380fdb06a50a635 sam: git: https://github.com/imdrasil/sam.cr.git