AppTown v1.0.0-rc.7

Flokkit AppTown v1.0.0-rc.7

The seventh candidate for 1.0. It replaces RC6 as the candidate running in
production with the maintainers, and the two-week run before 1.0 starts on
it, on 24 October 2026.

RC6 was never run for its two weeks. The maintainers' production AppTown
left RC6 on its first day, 23 October, and ran builds of main until this
candidate. So RC7 is also the first candidate to run in production with
RC6's own changes, including its fixes.

RC7 gives the certificates of a company's TLS-inspecting proxy to every
container and build AppTown starts. It backs up and restores a whole
AppTown with one command each way. It removes the move from the names
things had before 1.0, which RC6 added. It fixes two defects that showed
up as intermittent test failures, clears the open dependency advisories,
and makes the shipped guides' links work on GitHub.

In short

• Behind a company's TLS-inspecting proxy, everything AppTown starts
  trusts the company's certificate authority. Agent, script, test and
  check steps, chats, screenshots, scanners, image builds, previews and
  deployed apps get the certificates given with -trust-deployments. RC6
  covered only AppTown's own connections.
• apptownd backup and apptownd restore back up and restore a whole
  AppTown. The archive is always encrypted with a passphrase. After a
  restore, AppTown checks App Platform and Portainer deployments against
  what their providers run and takes them over again.
• apptown move-names and its route are removed. They came in RC6.
  Every deployment must be named by its key before upgrading; migration 167
  stops the upgrade otherwise and names each one.
• Fixes: a landing's deploy is no longer cut short when its run is
  abandoned, and a cancelled database statement now fails as cancelled
  instead of as a network timeout.
• Dependencies: the open Go and npm advisories are fixed, and CI fails
  on a new high or critical npm advisory.
• The WordPress starter's theme is apptown-site for new projects.
• The tour on apptown.dev is made by the release itself, from the
  tagged source.
• RC7 has two database migrations, 166 and 167.

What changed

Extra certificate authorities in containers and builds

RC6 let AppTown's own connections trust extra certificate authorities, with
-trust-inference, -trust-deployments and -trust-apptown. The
containers AppTown started did not trust them, so a step that downloaded a
package behind a TLS-inspecting proxy failed. Now the -trust-deployments
certificates go to everything AppTown starts. With -local-tls, AppTown's
own local authority goes too, but only to containers on that machine.

• One script, APPTOWN_TRUST, adds the certificates beside the image's
  own roots, never in place of them. It sets the variables programs read
  (SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE and
  others), apt's setting, the JVM's trust store (through
  JAVA_TOOL_OPTIONS), Chromium's store, and, as root outside a build, the
  system store. With no certificates set, it does nothing.
• Agent, script, tests and check steps, chats and screenshots run it
  before their command, and again after installing the project's declared
  toolchain, so a JVM that mise installs trusts the certificates too.
  Scanners that use the network run it first.
• The private Docker daemons of steps, chats and release builds, and
  the builder inside them, trust the certificates for their own pulls.
• Every image AppTown builds (previews, releases, check images and the
  agent image, including a worker's at its first start) gets the
  certificates as the build secret apptown-trust. The twelve starter
  Dockerfiles mount it in each RUN that downloads. Building with the
  secret needs buildx (Docker 23 or later).
• Deployed apps and previews on Docker hosts, Portainer and App
  Platform get the variable APPTOWN_TRUST, and the starters' start
  commands run it. Attached hosts, Portainer and App Platform never get the
  local authority. A command: in .apptown/app.yaml replaces the image's
  CMD, so it must run eval "${APPTOWN_TRUST:-}" itself if the app calls
  out.
• An image with no shell cannot run the script and keeps only its own
  roots. The go-small starter's distroless runtime is one.
• The build/container-image guidance says how a Dockerfile uses the
  secret and the variable. Projects started before RC7 keep their
  Dockerfiles, so they add the lines themselves.
• Every apptown-worker flag can also be set by its APPTOWN_ variable,
  as apptownd's already could.

Setting up a server
and the app contract
describe it.

Backing up and restoring a whole AppTown

• apptownd backup [-store] <archive> asks the running AppTown for one
  archive. First it backs up each app on AppTown's own Docker host, one at
  a time, with that app's parts stopped and then started again. Then it
  holds new jobs and steps for a moment, dumps the built-in database and
  copies the data directory (without pgdata and cache). -store also
  copies the archive to the backup store that deployment backups use.
• The archive is always encrypted with a passphrase (age). It holds
  every secret AppTown has. The passphrase is asked on the terminal, or
  read from the file APPTOWN_BACKUP_PASSPHRASE_FILE names. Without it the
  archive cannot be opened. An external secret store such as Infisical
  keeps its own values, and the archive's manifest says so.
• apptownd restore <archive> runs on a host with no AppTown. It
  refuses a host that already has an AppTown's database or deployment
  containers, or a data directory that is not empty. It checks the files
  and the dump against the manifest, loads the dump, compares each table's
  rows with it, and opens the database as -verify-only does.
• Apps on AppTown's own Docker host are rebuilt from their last release
  at the first start after a restore, with their data put back before any
  part of the app runs. If a copy is missing or partial, nothing starts and
  the deployment's card says so.
• App Platform and Portainer deployments are checked against their
  providers every minute after a restore. If the provider runs the
  recorded release, AppTown carries on. If it runs a different one,
  AppTown records it as a release "observed after restore", which AppTown
  did not ship. The release AppTown last shipped there can still be
  deployed again. If the app is gone, a person decides. If the provider
  cannot be read, AppTown asks again. Until a deployment is checked,
  AppTown does not release to it, restore into it or take it down,
  including work queued before the backup.
• scripts/apptown-recovery-rehearsal.sh now uses the two commands.

AppTown's own backups
leads with them.

Fixes

• A landing's deploy runs to its end when its run is abandoned. Before,
  stopping the run could cut the deploy short. AppTown then recorded its
  outcome as uncertain, and main refused every release until a recovery
  check decided it, usually as failed. A start stopped part way could leave
  main between two versions. What comes before the deploy starts still
  stops.
• A cancelled database statement fails as cancelled. When a
  cancellation cut short a statement while it was being sent, the error
  was a network timeout (write tcp ...: i/o timeout), which no caller
  could tell from a real network fault. The error is now both the
  cancellation and the timeout, over plain and TLS connections.
• The repo/no-build-artifacts check says "could not assess" when it
  cannot list or read a project's files, instead of passing.
• RC6's fix for a step that finished just as its run ended (it was treated
  as lost and cancelled) is in production for the first time, because RC6
  never ran there.

Dependencies

• Go: klauspost/compress 1.18.7 and grpc 1.83.2.
• The web interface: vite 6.4.4, vitest 4.1.12, react-router-dom 7.18.2,
  mermaid 12.2.0 (with katex 0.18.2), dompurify 3.4.17, js-yaml 5.4.1,
  undici 8.10.2, brace-expansion 5.0.12 and source-map-js 1.2.2. Each is
  the smallest version that fixes its advisory.
• The frontend-only and video-game starters, which new projects of
  those kinds start from, take vite 8.3.3 and 6.4.4 respectively, and
  source-map-js 1.2.2. Existing projects keep their own lockfiles.
• A new check, make check-npm-audit, runs in CI. It fails on a high or
  critical advisory in what the web interface ships, or in any starter's
  lockfile, unless scripts/npm-audit-exceptions.txt lists it with a date
  and a reason. It fails too when npm cannot get the report.

Starters and guides

• The WordPress starter's theme is apptown-site, with an apptown/
  Composer package name and an apptown- S3 plugin name. Projects started
  earlier keep the theme and files they were given, and the guidance says
  so.
• The shipped guides' links work on GitHub and on the Docs page. A
  guide links another by its file (split-install.md), which GitHub
  follows and the Docs page turns into its own route. make check-docs
  checks every link in the guides and the release notes, and now runs in
  CI.

Releases and CI

• The release workflow makes the tour on apptown.dev from the tag's
  source, and publishes the site with it. The screenshots are no longer
  kept in the repository. A test tag (-test.N) makes the tour and leaves
  the site alone.
• A release's images and archives are built only when heavy.yml passed
  on the commit at its first attempt. A run that passed only when re-run
  does not count. heavy.yml now also runs on every pull request.
• The repository runs AppTown's own no-build-artifacts-tracked check over
  itself.
• The upgrade test now also upgrades an AppTown that RC6 recorded.

Removed

• Moving a deployment made before 1.0 to its new names. Every
  deployment is now named by its key. apptown move-names and its route
  are gone, and so is everything that still read the names and forge.*
  labels things had before 1.0: the start-up sweep of what an AppTown or a
  worker before 1.0 left on its Docker, the old label reads, and the
  forge- prefix in the readers of names on a host.
• A built-in database container without this installation's
  apptown.instance label is refused, as its volume already was. An
  install made before 1.0 whose container has only the old forge.instance
  label must make the container again first.

Upgrading from RC6

Every deployment must be named by its key before the upgrade. Migration
167 stops the upgrade, changing nothing, while a deployment still holds a
container, a Portainer stack or anything else on a host under the names it
was made with, and names each one. Under RC6, move one on a Docker host
with apptown move-names <project> <deployment>. Take one on Portainer
down and release it again. Its data is not carried over, so copy it first.
Upgrading
says more. Upgrading from a release before RC6 is not supported.

Otherwise the upgrade is as the upgrading guide describes: check nothing
is executing, stop AppTown, take the two copies, replace the binaries and
start.

Database migrations

RC7 has two, 166 and 167. 166: each release records whether AppTown
shipped it or saw it after a restore, each deployment records whether its
provider has been checked since a restore, and a new table records putting
a built-in deployment's data back after a restore. 167: the recorded host
prefix of each deployment and the move flag on release requests are
dropped, once no deployment is still on its old names.

HTTP API changes

Routes removed:

• POST /api/v1/projects/{slug}/deployments/{name}/move-names, added in
  RC6 and not promised (apptown move-names).

Fields added:

• Release.origin, always present: shipped, or observed-after-restore
  for a release AppTown recorded after a restore and did not ship.
• Deployment.restoreCheck and DeploymentView.restoreCheck: empty, or,
  after a restore, unconfirmed (the provider has not been read yet),
  gone (the app is not there) or filling (the data is being put back).
• DeploymentView.dataAfterRestore: null, or a RestoreFill with state
  (waiting, filled or failed), detail, the backup set and
  updatedAt.
• ServiceSpec.appPart: true for one of the app's own parts, as opposed to
  a need's service.

Deprecations

These are removals before 1.0, so no minor release comes first.

• apptown move-names and
  POST /api/v1/projects/{slug}/deployments/{name}/move-names are
  removed. They shipped in RC6 to move a deployment made before 1.0 to
  its new names. Nothing replaces them: every deployment is named by its
  key, and migration 167 refuses an upgrade while one is not.
• The names and labels from before 1.0 are no longer read: the
  forge- prefix on a host, the forge.* Docker labels, and a built-in
  database container labelled only forge.instance.