AppTown v1.0.0-rc.12

Flokkit AppTown v1.0.0-rc.12

RC12 removes machinery that nothing used, makes cleanup of leftover containers
the default, narrows what AppTown counts as its own at a deployment target, and
builds a release once, as a candidate, before its version tag exists. A project
can now adopt several packs. It includes all changes since RC11. Several changes are breaking; read
"Breaking changes" before upgrading. Take matching database and file backups
before upgrading, as described in the
upgrade guide.

Breaking changes

Startup and operation:

• Cleanup is on by default; -reap is removed. The periodic cleanup of step,
  service and chat containers and networks, unwatched previews and their kept
  builds, images, toolchain caches and finished workspaces now deletes instead
  of only logging. apptownd -disable-reap (APPTOWN_DISABLE_REAP=true) turns
  deletion off. A command line that still passes -reap stops apptownd;
  APPTOWN_REAP is no longer read. Remove both from service files, including a
  systemd drop-in that sets APPTOWN_REAP. Cleanup cannot tell two AppTowns'
  containers apart: give a second AppTown on the same Docker daemon its own
  daemon, or run both with -disable-reap.
• The update supervisor is removed. The -update-supervisor-socket flag is
  gone (passing it fails start-up), bin/apptown-update is no longer shipped and
  the managed supervisor guide is removed. The Updates page still checks signed
  release information and shows how to install a newer release.
  UPDATE-MANIFEST.json is format 2; builds before RC12 cannot read it and show
  the release check as failed or stale, so update those by hand once. The
  notification cache moves to <data>/release-checks; delete the old
  <data>/instance-updates folder.
• Host-process execution is removed. apptownd -agent-executor and
  -host-scripts are unknown flags and APPTOWN_AGENT_EXECUTOR and
  APPTOWN_HOST_SCRIPTS are not read. Agents and scripts run only in
  containers. A workflow that names an executor other than docker is refused
  when saved; a run admitted earlier with executor: local stops at that step.
• Private Docker is on by default. -no-private-docker is removed and
  APPTOWN_NO_PRIVATE_DOCKER is ignored. Use -private-docker=false
  (APPTOWN_PRIVATE_DOCKER=false). With a worker, docker: true steps and release
  builds run there without opting in.
• Docker's buildx plugin is required. AppTown no longer falls back to
  Docker's legacy builder when docker buildx version fails: the build is refused
  before anything is sent. Install docker-buildx-plugin beside the docker CLI
  AppTown runs (AppTown's published images include it). Check-image and
  agent-image builds now also require buildx and the daemon's own builder, as
  deployment builds already did.
• PostgreSQL major version is checked at start. AppTown supports a range of
  PostgreSQL majors for its own database, built in or -db-url (today 16 only).
  apptownd refuses to start on a server outside the range and names it.
  Backups and restores check the same range.
• Data folders from before 1.0.0-rc.9 are refused. Upgrade with RC9 to RC11
  first. Whole-AppTown restore accepts only backups taken by RC9 or later; an
  archive with linked or borrowed workspace Git metadata is refused. The
  data-folder layout 1-to-2 upgrade is removed; new installs write layout 2.

Backups:

• Whole-AppTown backups hold AppTown only. Built-in deployments are filled on
  restore from their own newest whole deployment backup. One whose data did not
  come back is kept out of automatic rebuilds (a new restore check, not-filled)
  so a restart does not start it on empty data; releasing it is the decision to
  start it without that data. The manifest no longer lists deployments.
• pg_dump runs in a pinned container, on AppTown's own Docker when it has
  one, otherwise on its worker. The host's pg_dump is no longer used. A
  -db-url database must be reachable from a container: a loopback host is
  refused. sslrootcert in -db-url is honoured; verify-ca and verify-full
  without one verify against the image's system roots. On a worker the gzipped
  dump is one result of at most 64 MiB; a larger one is refused. Backups with
  -no-local-docker need the worker and AppTown upgraded together. The first
  backup on a host pulls the pinned postgres image.
• scripts/apptown-db-backup.sh is removed from archives and the image. Take
  apptownd backup before upgrading; the upgrade guide describes rolling back from
  that archive.

Targets and deployments:

• Inventory counts only resources carrying this installation's mark. Every
  resource AppTown makes at a target carries the installation's id (a Docker label,
  a Portainer stack variable, an App Platform spec variable, a DigitalOcean database
  tag, or a private _apptown/instance object in a bucket-website bucket).
  Resources without the mark only confirm recorded deployments; only a marked
  resource that nothing records is reported as not accounted for or can be removed
  from the infrastructure page. Resources made by a person or script, such as the
  database AppTown runs on, are no longer listed. At each start AppTown marks
  managed database clusters and bucket-website buckets that deployment records
  name; Docker objects, Portainer stacks and App Platform apps gain the mark at
  their next release. A target kind with no inventory reader shows as unknown
  rather than an error.
• Health is judged one way. With no declared expect, a 4xx or 5xx answer at
  the health path is no longer ready on Docker and Portainer, for HTTP liveness
  probes, or in a restore rehearsal's sealed boot. An app whose health path
  answers 404 must fix the path or declare expect: 404. On App Platform a
  redirect at the health path now counts as ready (it is not followed).
• .forge/app.yaml is no longer read. Only .apptown/app.yaml at a commit
  is the app contract (a regular file, at most 1 MiB; links are refused). A commit
  whose contract is only at .forge/app.yaml reads as having none, which affects
  redeploying or restoring a release built from it.
• Resource limits are flattened to three levels: the deployment's override,
  else what the app declares for its profile, else AppTown's default. A pack can no
  longer declare resources; clears: [resources] is refused. An app part that
  declares no memory gets 512Mi at its next release. An unattended pack update from
  a publication that declared memory is refused.
• secretsDelivery and deploymentPolicy are removed. secretsDelivery is
  gone from target responses and the target page (migration 183). deploymentPolicy
  is refused when creating a deployment (400, unknown key) and no longer appears in
  deployment, tier, target-page or MCP get_project responses.
• Release setup and promoteAfter are removed. The apptown release-setup
  command, the route, imported setup state and the per-deployment promotion toggle
  are gone. Promotion permission is needed only for protected deployments;
  admitted releases keep their recorded requirement. The promoteAfter attribute
  is removed.
• Legacy Portainer confirmation is removed. Other Portainer targets without a
  recorded endpoint must be attached again. A deployment whose stored URL does not
  match the recorded hostname rule, or whose host another deployment claims, gets
  a new generated hostname at its next release.
• The storage-bindings routes are removed; the next deploy records the binding.

Ways of working (a project takes several packs):

• A project adopts one or more packs, none above another, and packs no longer
  include one another. Migration 192 drops the single primary pack name and
  pack inclusion. New receipts carry packs (sorted names, platform included)
  instead of pack; an old receipt's pack key is no longer read.
• Stock packs are reorganised. Retired (turned off at sync; a project on one
  keeps working until moved): go-small, node-fullstack, django-htmx,
  java-spring, rust-service and wordpress-bedrock. New: server-base,
  go, node, django, java, rust, wordpress, postgres, vite-react
  and server-rendered. rails and dotnet keep their names but hold only
  backend content, and their old contents clash with server-base. Guidance
  blocks withdrawn: frontend/vite-typescript and
  lang/selection/typescript-for-web (now frontend/vite-react),
  frontend/hypermedia-htmx (now frontend/server-rendered) and
  observability/error-reporting (its rules are in the errors integration's
  generated steering section). Starter folders take the backend pack names.
• Pack declarations lose includes, replaces, drops, clears and
  starter; saving one that has them is refused.
• Operator steps after upgrading. A release never recommends a stock version
  by itself: recommend the new versions of rails and dotnet (and of
  frontend-only, conventions-only, video-game and godot-3d), then move
  projects off the retired packs. Until then a project with a revision shows an
  adoption drift note (display only). Moving a project drops its own guidance
  additions. An uplift change opened before the upgrade and not landed cannot
  settle: it is closed as superseded when the project moves; open it again after. An eval running across the
  upgrade must be run again.
• HTTP, MCP and CLI use pack lists. POST /projects/{slug}/pack takes
  {"names": [...]} ({"name"} is refused) and answers packs;
  POST /projects takes packs; POST /packs/interview decisions carry
  packs; POST /projects/{slug}/pack/pull requires pack. MCP
  create_project takes packs and get_project and list_projects answer
  packs. CLI: apptown pack -p <slug> <pack>..., apptown new --pack a,b,c,
  and apptown pack versions no longer prints inclusion.
• A chat whose project guidance cannot be compiled is refused at open; it
  used to open with the guidance silently left out.

Commands, containers and jobs:

• Docker settings are read one way. apptown dev, apptown config validate
  and apptown-worker use DOCKER_HOST, DOCKER_CONTEXT and the saved context.
  A tcp:// or ssh:// Docker context now counts as another machine (before,
  only a tcp:// DOCKER_HOST). A Docker setting that cannot be read is an error:
  the worker refuses to start and the CLI refuses.
• apptown config validate sends the secrets file the contract declares
  (secrets.spec), not always secretspec.toml.
• Step containers are named apptown-step-<id>-<what>. Containers running
  under the old names at upgrade are not stopped by an interrupt.
• Jobs queued under the old narrative keys fail once at upgrade:
  workflow-completion <run>/narrative and workflow-abandonment
run/<id>/narrative. The narrative refreshes on the next trigger; a "landing
  ended" chat note queued before upgrade is lost.
• Scanner health, connector health and the integration list say "could not be
  read" when Docker cannot answer an image inspect, instead of "missing", and
  no longer pull.
• The agent's repository on a worker takes its base branch from the fork point
  from main. A change with no history in common reads against its recorded base.
• The agent-reported artifact kind is reserved: gates and artifact
  requirements no longer see artifacts of that kind. The stored request gap holds
  up to 700 bytes (was 400).
• New small containers. AppTown starts one standing disk reader per Docker
  host it reads (apptown-reader-disk-reader-*) and one readiness container per
  Portainer-managed deployment (class readiness-<deployment id>, removed with the
  deployment). The capacity view counts them as AppTown's own.
• A command given an unknown flag prints its usage lines from the help table.
• scripts/chat-check.py opens and abandons a change in the project it checks,
  which must be repository-backed.

Records, roles and identifiers:

• Tables and records removed (migrations 182, 183, 185 to 191): allowed
  authorization decisions (the decision object has no receiptId; a denial is
  still written to the activity log), one stored row per model call (usage reports
  and apptown_inference_* telemetry are unchanged; the gateway no longer answers
  503 "cannot record inference admission"), an integration's earlier
  configurations, deployment need-fulfilment passes, the old integer ID table and
  audit references, project address aliases, and unused delegation columns. The
  tables are dropped with their contents.
• Pre-1.0 integer links stop resolving. Links and API paths naming a change,
  run, step, ADR or guidance block by its integer return 400 with no redirect.
• A renamed project's old address resolves nowhere (pages, API, MCP, Git URLs,
  slug#N, CLI inference from a folder name), and another project can take it.
  PATCH /api/v1/projects/{slug} no longer uses requestId. Backup and rebuild
  jobs queued by an older build fail once and are asked again.
• Roles removed: integration-administrator, group-viewer,
  group-project-creator, group-maintainer and group-auditor, and grants at
  change, run or dimension scope, are refused and existing ones are deleted.
  Release manager is granted at a release target. OAuth connection records drop
  unused fields.
• The worker qualification verdict is removed. Agent-step evidence no longer
  has privateDocker; a release bundle's build record replaces qualification
  with profile, the worker's measured facts for that build. Earlier records keep
  their old text, which nothing reads. External-worker test settings are now
  APPTOWN_EXTERNAL_WORKER_* and APPTOWN_EXTERNAL_WORKER_DISK (were
  APPTOWN_QUAL_WORKER_* and APPTOWN_QUAL_DISK).
• CLI wording: apptown changes and apptown show print "in progress"
  rather than in_progress, and a change closed as a record reads "finished". Their
  --json output gains stateLabel.

New and improved

• Cleanup removes leftovers by default, so installs that never set a flag no
  longer fill their disks. What each sweep selects is unchanged: only resources with
  AppTown's labels or in its data folder, never deployments, and nothing in use or
  whose owner cannot be read.
• Chats on a worker keep their files. The worker's start-up cleanup keeps a
  blob that any chat container, running or stopped, still mounts, and removes none
  when Docker cannot say. Waiting for the chat terminal ends at once with its reason
  on any failure other than "not started yet", instead of waiting ten minutes.
• Backups of large files. Backup store files upload in parts with no
  single-upload size limit, each part and the whole object checked, and nothing
  left behind on failure. A whole-AppTown backup is possible again with
  -no-local-docker on a managed database.
• Bucket-website targets have an inventory reader, so their pages and the
  inventory job no longer fail with "has no inventory".
• One rule each for five things that several places judged differently:
  readiness, step spend ("Where the time goes" now sums each step's usage ledger
  and says "at least" or "spend unknown"), change state words (the server sends
  stateLabel), the app contract at a commit, and image builds.
• Release process. A release is built once as a candidate before its version
  tag exists and those bytes are qualified (an upgrade rehearsal, a native Mac
  install and a chat on a worker) and then published. CI reuses Go test results from
  main's fresh runs for identical inputs. The frozen RC11 upgrade fixture is
  included, and the upgrade rehearsal is restored.
• Superseded adoption changes close themselves. When a project's pack set
  changes, its open uplift changes that take a pack the set no longer has (or an
  older version) are abandoned in the same transaction, with the reason
  "superseded: ...". A blocked change carries an abandon next act, and the
  change page and the Home "Needs you" row show "Close it" to a reader who may
  abandon it.
• Several packs per project. A project can adopt more than one pack, and the
  stock packs are split into a shared server-base plus one pack per language,
  framework or database, so a project composes what it uses.
• Guidance items can carry on-demand skills. An item's always-read part stays
  short; its how-to moves to a named skill an agent loads when needed. MCP
  get_project_guidance returns the shortened text and a new skills list, and
  the HTTP project guidance sizes show what agents read up front.
  build/container-image and data/networked-database have new stock versions.
• Change summaries and refusals are more honest. A change summary reads the
  whole request and diff, says what it did not read, and says what would satisfy
  it. Refusals say what would satisfy them (text only; codes are unchanged).
  request_change_landing takes an optional report argument.
• Quieter hosts. An idle toolchain-cache sweep starts no containers (it reads
  volumes again only after a change closes or a run stops), disk readings use one
  standing reader container per Docker host, and Portainer readiness samples start
  no container each time.
• apptown wait says "reworking" correctly. Run snapshots carry
  sentBack {stepId, step, by, note}, so a person's send-back reads as reworking.
  A Docker or Portainer release marker with surrounding white space is accepted.
• Split installs with Docker. Compose files for AppTown and for the worker are
  shipped in deploy/split-install/.
• Release downloads. Each release archive is its own candidate artifact, and
  the recovery rehearsal takes the candidate from a file on the target host.
  Published bytes and SHA256SUMS are unchanged.
• Backup guide and apptownd backup describe restoring an archive taken from
  an external database on a new host's built-in database.

Declaration changes

Packs can no longer declare resources, and no longer use includes, replaces,
drops, clears or starter (see Breaking changes). Guidance items may carry
skills. No other application-contract, workflow, check, scanner or pack
declaration fields are added.

HTTP API changes

These changes are relative to RC11. The HTTP API remains experimental. The
OpenAPI description
contains the available route definitions.

• Removed: GET and POST /api/v1/targets/{name}/provider-association,
  .../deployments/{id}/address/observation,
  GET and POST /api/v1/projects/{slug}/deployments/{name}/storage-bindings,
  POST /api/v1/projects/{slug}/release/default/setup and
  PUT .../deployments/{id}/promotion-policy.
• Removed: the integer-ID routes /adrs/{id}, /changes/{id} and
  /guidance/{id}.
• GET /api/v1/instance-updates and POST /api/v1/instance-updates/check no
  longer return supervisorState, supervisorReason, supervisorPhase,
  automaticReplacement or replacementReason.
• Deployment responses drop requirePromotion, policyRevision and
  promoteAfter; release/default drops legacySetup; address responses drop
  verified and legacyEvidence; target responses drop secretsDelivery;
  deployment, tier, target-page and MCP responses drop deploymentPolicy, and
  POST .../deployments refuses it.
• The authorization decision object has no receiptId.
• Agent-step evidence drops privateDocker; release bundle builtFrom.build
  drops qualification and adds profile.
• Change state responses (change detail, board and lists, chat changes, an
  integration's wiring change) carry stateLabel.
• PATCH /api/v1/projects/{slug} no longer uses requestId.
• Pack lists replace the single pack name as described under Breaking changes;
  GET /wow loses notOn, GET /packs/{name} loses followRefused,
  includedPack and includedVersion, and the current adoption view loses pack.
• Run snapshots gain sentBack; activity run rows carry next; project guidance
  effective.text holds only the always-read part, with skills listed separately.
• Target inventory reads report a target kind with no reader as unknown.

Deprecations

None.