How to upgrade HelloJohn safely, including zero-downtime upgrades, rollback procedures, and breaking change policies.

Upgrading HelloJohn

HelloJohn follows Semantic Versioning. Patch releases (1.2.x) are always safe to apply. Minor releases (1.x.0) are backward-compatible. Major releases (x.0.0) may contain breaking changes.

Before you upgrade

Read the changelog for your target version
Back up your database — always, before any upgrade
Test in a staging environment first for minor and major upgrades
Check for breaking changes — look for "BREAKING" labels in the release notes

# Back up PostgreSQL before upgrading
pg_dump -Fc -h localhost -U hellojohn hellojohn > \
  "hellojohn_backup_$(date +%Y%m%d_%H%M%S).dump"

Upgrading with Docker Compose

This is the most common upgrade path.

Patch / minor releases

# Pull the latest image
docker compose pull

# Restart with the new image (zero downtime if single container)
docker compose up -d --force-recreate hellojohn

# Check logs for errors
docker compose logs --tail=50 -f hellojohn

# Verify health
curl http://localhost:3000/health

Migrations run automatically when the new container starts.

Pinned version upgrades

# docker-compose.yml
services:
  hellojohn:
    image: ghcr.io/hellojohn/hellojohn:1.3.0   # ← update this

docker compose up -d

Upgrading the binary

# Download the new version
HELLOJOHN_VERSION=1.3.0
curl -fsSL \
  "https://github.com/hellojohn/hellojohn/releases/download/v${HELLOJOHN_VERSION}/hellojohn-linux-amd64.tar.gz" \
  | tar xz

# Replace the binary (after stopping the service)
systemctl stop hellojohn
mv hellojohn /usr/local/bin/hellojohn
systemctl start hellojohn
systemctl status hellojohn

systemd service file

/etc/systemd/system/hellojohn.service:

[Unit]
Description=HelloJohn Auth Server
After=network.target postgresql.service

[Service]
Type=simple
User=hellojohn
EnvironmentFile=/etc/hellojohn/hellojohn.env
ExecStart=/usr/local/bin/hellojohn serve
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/hellojohn

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable hellojohn
systemctl start hellojohn

Zero-downtime upgrades

For deployments with multiple instances behind a load balancer:

Deploy the new version to one instance and verify it passes health checks
Drain traffic from the old instance (load balancer removes it from rotation)
Upgrade remaining instances one by one
Verify each instance health before proceeding

# Example rolling update with Docker Compose (single node)
docker compose pull hellojohn
docker compose up -d --no-deps hellojohn
# Docker will pull the new image and replace the container
# There's a brief restart — use Kubernetes for true zero-downtime

For true zero-downtime, use Kubernetes with a rolling deployment strategy:

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    spec:
      containers:
      - name: hellojohn
        image: ghcr.io/hellojohn/hellojohn:1.3.0
        readinessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5

Running migrations separately

If you want to run migrations before starting the new server (e.g., to verify they succeed):

# Run migrations without starting the server
hellojohn migrate

# Or with Docker
docker run --rm \
  -e DATABASE_URL=postgres://... \
  ghcr.io/hellojohn/hellojohn:1.3.0 \
  hellojohn migrate

Rollback

If an upgrade fails, roll back to the previous version:

Docker

# Roll back to the previous image tag
docker compose stop hellojohn
docker compose rm -f hellojohn

# Edit docker-compose.yml to the previous version tag, then:
docker compose up -d hellojohn

# Check logs
docker compose logs --tail=100 -f hellojohn

Database rollback

If a migration fails or causes issues, restore from the pre-upgrade backup:

# Stop HelloJohn first
docker compose stop hellojohn

# Drop and restore the database
dropdb -h localhost -U hellojohn hellojohn
createdb -h localhost -U hellojohn hellojohn -O hellojohn
pg_restore -h localhost -U hellojohn -d hellojohn hellojohn_backup_20240101_120000.dump

# Start the old version
docker compose up -d hellojohn

Version compatibility matrix

HelloJohn version	PostgreSQL	Redis	Node SDK	Go SDK
1.3.x	14–16	6–7	≥1.2.0	≥1.2.0
1.2.x	14–16	6–7	≥1.1.0	≥1.1.0
1.1.x	13–15	6–7	≥1.0.0	≥1.0.0
1.0.x	13–15	6–7	≥1.0.0	≥1.0.0

Upgrade notifications

Stay informed about new releases:

Watch releases: github.com/hellojohn/hellojohn/releases — click "Watch" → "Custom" → "Releases"
Security advisories: Watch the GitHub security advisories for the repo
Newsletter: Subscribe at hellojohn.dev/newsletter for release announcements

Breaking change policy

HelloJohn follows these rules to minimize upgrade pain:

Patch (1.2.x → 1.2.y): No breaking changes. Apply immediately.
Minor (1.2.x → 1.3.0): No API breaking changes. Database migrations are additive. Old SDK versions continue to work.
Major (1.x.0 → 2.0.0): May include breaking API changes, migration that removes deprecated columns, or SDK major version bumps. A migration guide is published with every major release.

Deprecation notices are added at least one minor version before removal. For example, if a feature is deprecated in 1.3.0, it will not be removed until 1.4.0 at the earliest.

Upgrading

On this page