Versioning and Releases

Version scheme

FreeSDN uses Calendar Versioning (CalVer) in the format YY.MM.PATCH:

Component	Meaning	Example
YY	Two-digit year	26 = 2026
MM	Two-digit month (zero-padded)	06 = June
PATCH	Patch increment within the month, starting at 1	1, 2, 3

Current release: 26.09.0

Examples of what version numbers communicate:

• 26.06.1 - first release of June 2026.
• 26.06.2 - patch release in the same month (bug fix or security patch).
• 26.07.1 - first release of July 2026.

There is no separate “major” or “minor” bump - the date carries that information. Breaking changes are called out explicitly in the release notes.

---

Release cadence

FreeSDN targets a monthly release cadence aligned to the CalVer month component. Security patches are released as PATCH increments as soon as they are ready - they do not wait for the monthly cycle.

Dependency update policy:

• Python and Node packages are not adopted on release day. The 3-day rule applies: new versions are evaluated after they have been on PyPI/npm for at least 72 hours, which catches withdrawn releases and compromised-maintainer incidents.
• CVE patches override the 3-day rule and are applied as soon as the upstream patch is signed.

---

Where to get releases

Container images

There is no published image registry yet

FreeSDN does not currently publish pre-built application images to any public container registry. The CI workflow that ships with the public repository builds and tests the code, but it has no image-publishing job, so there is nothing to pull. Every first-party image is built from source on your own host. docker compose pull will fail on the FreeSDN services.

All first-party services carry a build: stanza in docker-compose.yml and default to locally-built tags:

Service	Default image tag	Built from
api, worker, worker-io, scheduler, collector, flower, vpn	freesdn-backend:local (BACKEND_IMAGE)	backend/
edge	freesdn-edge:local (EDGE_IMAGE)	frontend/
edge-nginx	freesdn-edge-nginx:local (EDGE_NGINX_IMAGE)	frontend/
logdb	freesdn-logdb:local (LOGDB_IMAGE)	docker/Dockerfile.logdb (PostgreSQL 18 + TimescaleDB)

Third-party dependencies that run as their own services (Postgres, Valkey, pgbouncer, Prometheus and so on) are ordinary public images and are pulled normally. Caddy is not one of them: it arrives as the base image of the first-party edge build stage, so it is fetched during the build rather than pulled as a service image.

The standard deploy workflow is therefore a build, not a pull:

# Build the FreeSDN images from source (--pull refreshes the upstream base images)
docker compose --env-file .env.pro build --pull

# Restart with a rolling update (single-host)
docker compose --env-file .env.pro up -d

Always run migrations after deploying a new release:

docker compose --env-file .env.pro exec api python scripts/migrate.py

The image variables above exist so that you can publish to a registry of your own. If you build and push to a private registry, point the corresponding variable at your tag in .env.pro, and docker compose pull will then work for those services.

Source releases

Tagged releases are available on the FreeSDN GitHub repository. The public release is a flattened snapshot (no development history):

https://github.com/freesdn/freesdn

Agent releases

The freesdn-agent desktop + headless daemon is distributed separately (MIT-licensed, Python ≥ 3.11, Windows / Linux / macOS):

https://github.com/freesdn/freesdn-agent

Current agent version: v1.0.0 (alpha). The agent uses ECDSA-P256 signed auto-updates (fail-closed - an agent with a bad signature stays on the previous version rather than installing a corrupt update).

---

Licenses

Platform - AGPL-3.0-only

The FreeSDN core platform is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).

Key points of AGPL-3.0:

• You may use, study, modify, and distribute the software freely.
• If you run a modified version as a network service (SaaS), you must make the modified source available to users of that service under the same licence.
• Distribution of binaries requires providing the corresponding source.
• The licence applies to the entire platform codebase under SPDX-License-Identifier: AGPL-3.0-only.

Not MIT

Earlier documentation and the old marketing site incorrectly stated “MIT”. The current licence is AGPL-3.0-only. If you are evaluating FreeSDN for commercial embedding, consult the licence text and your legal counsel.

Full licence text: LICENSE in the repository root, and https://www.gnu.org/licenses/agpl-3.0.html.

Agent - MIT

The freesdn-agent package is separately licensed under the MIT License. You may embed or redistribute it without the AGPL network-service clause.

Full licence text: LICENSE in the freesdn-agent repository.

---

Upgrade path

1. Read the release notes for any breaking changes or required migration steps. They are published alongside each tagged release.

2. Take a database snapshot before upgrading:

   docker compose --env-file .env.pro exec pg-backup bash -c '
     STAMP=$(date +%Y%m%d_%H%M%S)
     pg_dump -h postgres -U "$PGUSER" -d "${POSTGRES_DB:-freesdn}" \
       | gzip > /backups/preupgrade_$STAMP.sql.gz
     pg_dump -h logdb -U "$LOGDB_USER" -d "$LOGDB_DB" \
       | gzip > /backups/preupgrade_logdb_$STAMP.sql.gz
   '

3. Rebuild the images from source (there is no registry to pull from):

   docker compose --env-file .env.pro build --pull

4. Apply migrations (idempotent - safe to run even when already at head):

   docker compose --env-file .env.pro up -d api
   docker compose --env-file .env.pro exec api python scripts/migrate.py

5. Start the rest of the stack:

   docker compose --env-file .env.pro up -d

6. Verify health:

   curl -fsS http://localhost:8080/api/v1/health/ready

   Port 8080 is the default Caddy edge port (override via EDGE_HTTP_PORT). In a production stack, the API container port 8000 is not published on the host - only the edge is. To check health from inside the container instead: docker compose --env-file .env.pro exec api python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/v1/health/ready', timeout=5); print('ready')"

For full disaster-recovery procedures see docs/DR_PROCEDURE.md in the repository.

---

Supported vendors and adapter maturity

The honesty matrix of all 12 supported adapters (maturity tier, write capability, known limitations) is maintained at docs/SUPPORTED_VENDORS.md in the repository. It is updated with each release. Do not rely on marketing summaries - check that file for your specific vendor before deploying.