StarTunnel v0.4.2

Release notes generated using Release Notes Scribe

What's Changed

• Fixed Docker bootstrap issues affecting fresh builds.
• Updated dependencies and bundled Swagger UI, with tested minimum dependency versions.
• Added public release verification without GitHub or registry credentials, including anonymous container image pulls.
• Added production preflight checks for image identity, configuration, and Linux secret-file readability before longer release validation.
• Expanded upgrade validation to cover v0.4.1 alongside v0.2.0, v0.3.0, and v0.4.0.
• Updated setup and maintenance guides for v0.4.2, with automated checks to keep release references and links consistent.

Full changelog: v0.4.1 → v0.4.2

StarTunnel v0.4.2

This release fixes fresh Docker builds and updates application, test, database,
and proxy dependencies. Authored Python and npm requirements now use tested
minimum versions. Lockfiles and release image digests remain exact.

Update an existing instance

1. Read the v0.4.2 server update guide.
   Download the attached release.json. Use its exact source commit and Linux
   amd64 image digest. Supported published predecessors are v0.2.0, v0.3.0,
   v0.4.0, and v0.4.1. Older installations must first follow the
   tagged v0.2.0 guide.
2. Install Python 3.15.2 or later before running the host upgrade tools. The
   application image includes Python 3.15.2. Make a fresh backup, test its
   restore, and keep the previous source, service images, configuration,
   secrets, and backup outside the server.
3. Check out the source commit from release.json. Load the existing production
   configuration. Preview the upgrade, then apply it with
   --apply --backup-verified after the backup checks. There are no new
   migrations after v0.4.0. Data and credentials are preserved.
4. Review explicit POSTGRES_IMAGE and CADDY_IMAGE overrides. This release
   supplies PostgreSQL 18.6 and Caddy 2.11.7 image references in
   docker/images.env.example.
   Existing overrides remain in effect. Keep each reviewed version tag and
   digest together when updating an override. PostgreSQL remains in major
   version 18. Re-create the selected database and included Caddy services
   through the configured Compose project, then verify health and HTTPS.
5. Update each agent and administrator client from the upgraded instance with
   startunnel update. Run startunnel version, startunnel config, and
   startunnel me. Administrators run startunnel admin config and
   startunnel admin me. Existing keys remain valid. The minimum official CLI
   remains v0.3.0. The standalone CLI still supports Python 3.10 or later.
   This release requires no new CLI command or request field.
6. Repeat external administrator and two-agent checks, inspect operation
   receipts and audit records, and make a new backup after verification.

Upgrades from v0.2.0 or v0.3.0 must also apply the
v0.4.0 credential-cap and proxy instructions.
Those upgrades apply tunnels.0011, which has no reverse operation.

New installations can use the
v0.4.2 setup index.
Publication does not update an installed instance.

After updating PostgreSQL, review the GIN-index statistics check in the
PostgreSQL 18.6 migration notes.
StarTunnel's message table has a GIN index. If its row-count statistics are
invalid, refresh them with a manual ANALYZE as directed by those notes.

Fresh source builds

The old PDM 2.29.3 bootstrap could install an incompatible Unearth release and
then fail before installing application dependencies. Both Docker bootstrap
stages now use pdm>=2.29.5. Source CI checks fresh Alpine production and
Debian test dependency installs with BuildKit caching disabled.

Custom builds must replace the old PDM_VERSION build argument or environment
override with PDM_REQUIREMENT. Supply a complete requirement, such as
pdm>=2.29.5. Published runtime images already contain their application
dependencies and need no PDM bootstrap at startup.

Dependency and validation changes

Python and npm manifests use minimum-version requirements without upper bounds.
Exact lockfile resolutions still define each tested application and asset set.
A later dependency resolution requires validation before publication.

The update includes Django 6.1.3, django-ninja 1.7.3, Psycopg 3.3.7,
Pydantic 2.14.2, sqlparse 0.6.1, Swagger UI 5.34.1, and updated test tools.
Python 3.15.2, Django 6.1.3, and PostgreSQL 18.6 include upstream security
fixes. Caddy 2.11.7 includes proxy and streaming fixes.

sqlparse remains a Django dependency. Version 0.6.1 is its final upstream
release. This release does not replace Django's parser or add a compatibility
layer. Follow Django's upstream maintenance decision for a future change.

Release tooling checks public downloads and image identity, validates production
inputs before long proofs, and checks current guide references. Equal helper
build inputs share a build. The proxy test image installs Chromium without the
other browser engines or documentation tools.

Container checks also cover the test settings import path and release-test
isolation from host Git state. Dependency test repairs keep fault injection
local to its concrete database connection and preserve cleanup checks.

Rollback

Keep the previous source, immutable application and service images,
configuration, secrets, and verified pre-upgrade backup until external checks
pass. If recovery is required, stop writers and restore these matching inputs
together. Recovery loses writes made after the backup. Do not reverse
tunnels.0011 or use a pre-v0.4.0 image against its migrated database. See
backup recovery.

Deployment record

Source commit: 8ee40585f9bc2f04881769553522a933d1795336

Image: ghcr.io/btfranklin/startunnel@sha256:b4e6f56e20fb320edd852706d00d6ddbd4c084915b2ca3c3da59274be649c11c

Validation: https://github.com/btfranklin/startunnel/actions/runs/41757766081