Releases and distribution

Coequal ships as a single static binary, a multi-arch Docker image, and .deb/.rpm packages. This page covers what we publish, how to obtain it, and the cadence at which we cycle artifacts. Customers are responsible for keeping their installations current — older artifacts are retained for a limited window and then garbage-collected.

Versioning

We follow semantic versioning. Tags look like vMAJOR.MINOR.PATCH (for example, v1.4.2).

• Major — breaking change to configuration, schema migrations that require manual intervention, or removed endpoints. Always read the release notes before upgrading.
• Minor — new features, additive schema migrations, new configuration variables (always with safe defaults).
• Patch — bug fixes and security updates only.

latest follows the most recent stable release. We strongly recommend pinning to a specific version in production and bumping deliberately.

What we publish

Artifact	Where	Architectures
Linux/macOS/Windows binaries	GitHub Releases	amd64, arm64
Docker images	Amazon ECR (private)	amd64, arm64 (manifest list)
.deb packages	Amazon S3 (private)	amd64, arm64
.rpm packages	Amazon S3 (private)	amd64, arm64

Each release also publishes SHA-256 checksums alongside the artifacts.

Retention policy

WARNING

Only the last 10 versions are retained for each artifact type. When a new release is published, anything beyond the most recent 10 is permanently deleted from ECR and S3 — there is no archival tier and we cannot recover deleted images on request. If you are pinned to an old version and we cycle past it, your docker pull or package update will fail.

What this means in practice:

• Upgrade through the release stream regularly — at minimum every few months. Customers running on a release older than the latest 10 must skip directly to a supported version.
• For air-gapped environments, mirror the artifact you depend on into your own registry or APT/YUM repository on the day of the upgrade. We cannot reissue a deleted version.
• Security patches always land on the latest minor. We do not back-port to versions that have already cycled out of the retention window.

Credentials

To pull images or packages, request a customer access pair from your Coequal contact. You will receive:

• An AWS IAM access key ID and secret access key scoped to read-only access for both the ECR repository and the S3 distribution bucket.
• The S3 bucket name and region (the ECR registry URL is in Running with Docker).

These credentials are tied to your customer account. Treat them as secrets — check them into a secret manager, not into source control. Coequal can rotate or revoke them on request; we audit usage through CloudTrail and may rotate proactively if abuse is detected.

Pulling Docker images

See Running with Docker for the full flow. In summary:

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="us-east-2"

aws ecr get-login-password --region us-east-2 \
  | docker login --username AWS --password-stdin 845238243589.dkr.ecr.us-east-2.amazonaws.com

docker pull 845238243589.dkr.ecr.us-east-2.amazonaws.com/coequal:1.4.2

Pulling .deb and .rpm packages

The packages live in a private S3 bucket that you can pull from using the same access pair. You can either:

1. Download a single .deb or .rpm directly with the AWS CLI, or
2. Configure your package manager to treat the S3 bucket as an APT or YUM repository (recommended for fleets).

Direct download

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="us-east-2"

# Replace with the bucket name your account was issued.
BUCKET="s3://coequal-customer-packages"

# Debian / Ubuntu
aws s3 cp "$BUCKET/deb/pool/main/c/coequal/coequal_1.4.2_amd64.deb" .
sudo apt install ./coequal_1.4.2_amd64.deb

# RHEL / Rocky / Amazon Linux
aws s3 cp "$BUCKET/rpm/x86_64/coequal-1.4.2-1.x86_64.rpm" .
sudo dnf install ./coequal-1.4.2-1.x86_64.rpm

APT repository (Debian/Ubuntu)

The bucket is laid out as a flat APT repository with Packages.gz and Release files. Mount it with apt-transport-s3 or the simpler approach below using aws s3 sync into a local directory.

sudo install -d -m 0755 /etc/apt/keyrings
aws s3 cp s3://coequal-customer-packages/deb/coequal.gpg /etc/apt/keyrings/coequal.gpg

# Configure APT to fetch the index from a synced local mirror updated by cron:
echo "deb [signed-by=/etc/apt/keyrings/coequal.gpg] file:/var/lib/coequal-apt stable main" \
  | sudo tee /etc/apt/sources.list.d/coequal.list

# Cron job (run as root, daily):
aws s3 sync s3://coequal-customer-packages/deb /var/lib/coequal-apt --delete

sudo apt update
sudo apt install coequal

YUM/DNF repository (RHEL/Fedora/Rocky)

sudo tee /etc/yum.repos.d/coequal.repo <<'EOF'
[coequal]
name=Coequal
baseurl=file:///var/lib/coequal-yum
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-coequal
EOF

aws s3 cp s3://coequal-customer-packages/rpm/coequal.gpg /etc/pki/rpm-gpg/RPM-GPG-KEY-coequal

# Cron job (run as root, daily):
aws s3 sync s3://coequal-customer-packages/rpm /var/lib/coequal-yum --delete

sudo dnf install coequal

Verifying artifacts

Every release publishes a SHA256SUMS file alongside the artifacts and a detached signature SHA256SUMS.sig produced with our release signing key. Verify before installing:

aws s3 cp "$BUCKET/SHA256SUMS" .
aws s3 cp "$BUCKET/SHA256SUMS.sig" .
gpg --verify SHA256SUMS.sig SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

The public key is published at s3://coequal-customer-packages/coequal.gpg and on our website — fingerprint matches the one in the security policy.

Upgrade procedure

Coequal runs database migrations automatically on startup. The recommended upgrade procedure is:

1. Read the release notes. Major releases call out any operator action required.
2. Take a database backup. Migrations are forward-only; rolling back the binary on a migrated database is not supported.
3. Drain in-flight grading jobs, or accept that any pending jobs will resume on the new version. The jobs table is durable, so jobs survive a restart cleanly.
4. Roll the deployment — replace the binary or docker compose pull && docker compose up -d. Migrations run on first startup of the new version.
5. Verify that /metrics is reachable and the version reported in the startup log matches the version you deployed.

If you operate multiple replicas, each replica runs migrations idempotently — they coordinate via a Postgres advisory lock, so it is safe to start them in parallel.

Security updates

Critical CVEs are released as patch versions on the latest minor and announced via the GitHub security advisories feed. Subscribe to the repository to receive these. Customers running unsupported (older than 10 releases) versions need to upgrade to a current release to receive the fix.

Air-gapped deployments

If your environment cannot reach AWS, mirror the artifact at install time and host it internally. We do not provide a separate offline distribution channel — the same retention policy applies. For sustained air-gapped operation, set up a recurring sync (e.g. weekly) on a host that does have outbound access and ship artifacts inside.

Support

The latest 10 releases are supported. For a list of currently supported versions, see GitHub Releases. If you are running an unsupported version we will help you plan an upgrade path, but we will not back-port fixes.