Upgrade Guide

SPORK CA is designed for safe, zero-downtime upgrades. Every upgrade method creates an automatic backup before making changes, so you can always roll back.

1. Pre-Upgrade Checklist

Before upgrading, verify the following:

  1. Check your current version: 
    $ spork-acme --version
spork-acme 0.5.1
  2. Create a manual backup (in addition to the automatic one): 
    $ sudo tar czf /root/spork-backup-$(date +%Y%m%d).tar.gz /opt/spork-acme/
  3. Note any custom configuration: Record changes to /etc/spork/config.toml, systemd overrides, or environment files. Upgrades preserve configuration but it is good practice to have a record.
  4. Review the changelog for the target version (see Version History below) for any breaking changes or migration steps.

2. Upgrade via Installer

The self-extracting installer automatically detects an existing SPORK CA installation and offers an upgrade path:

$ sudo ./spork-acme-installer-0.5.2-x86_64-linux

Verifying installer integrity... SHA3-256 OK
Extracting...

Existing SPORK CA installation detected (v0.5.1).
  Data directory: /opt/spork-acme/
  Binary: /opt/spork-acme/bin/spork-acme

Select an option:
  1. Upgrade to v0.5.2
  2. Fresh install (will back up existing data)
  3. Cancel
Selection: 1

Creating backup... /opt/spork-acme/backups/pre-upgrade-20260310-120000.tar.gz
Upgrading binary... done.
Restarting service... done.

Upgrade complete: v0.5.1 -> v0.5.2
Backup saved to: /opt/spork-acme/backups/pre-upgrade-20260310-120000.tar.gz
Info: The installer verifies its own integrity via embedded SHA3-256 checksums before extracting. If verification fails, the upgrade is aborted.

3. Upgrade via Auto-Detect Menu

If you already have spork-acme installed, simply run it with no arguments. The auto-detect logic finds the existing installation and presents the management menu:

$ sudo spork-acme

Existing SPORK CA installation detected (v0.5.1).

  1. Configure
  2. Backup
  3. Security
  4. Upgrade
  5. Status
  6. Uninstall
Selection: 4

Checking for updates...
New version available: v0.5.2

Upgrade will:
  - Create a full backup of /opt/spork-acme/
  - Replace /opt/spork-acme/bin/spork-acme with v0.5.2
  - Restart the spork-acme service

Proceed? [y/N]: y

Creating backup... /opt/spork-acme/backups/pre-upgrade-20260310-130000.tar.gz
Replacing binary... done.
Restarting spork-acme.service... done.

Upgrade complete: v0.5.1 -> v0.5.2
Note: This method requires the new version binary to be available. If upgrading from a downloaded binary, place it at a known path and run the auto-detect from that binary, or use the manual upgrade method below.

4. Manual Upgrade

For full control over the upgrade process, follow these steps:

Step 1: Stop the service

$ sudo systemctl stop spork-acme

Step 2: Back up the data directory

$ sudo cp -a /opt/spork-acme/ /opt/spork-acme.bak/

Step 3: Back up the current binary

$ sudo cp /usr/local/bin/spork-acme /usr/local/bin/spork-acme.bak

Step 4: Install the new binary

$ sudo cp ./spork-acme /usr/local/bin/spork-acme
$ sudo chmod 755 /usr/local/bin/spork-acme

Step 5: Verify the new version

$ spork-acme --version
spork-acme 0.5.2

Step 6: Start the service

$ sudo systemctl start spork-acme
$ sudo systemctl status spork-acme
Warning: Ensure the new binary is a static (musl) build if your system differs from the build environment. SPORK CA distributes static binaries that work on any Linux distribution.

5. Rollback

If the upgrade causes issues, roll back to the previous version:

Rollback from automatic backup

# Stop the service
$ sudo systemctl stop spork-acme

# Restore the previous binary
$ sudo cp /usr/local/bin/spork-acme.bak /usr/local/bin/spork-acme

# If data migration occurred, restore the data backup
$ sudo tar xzf /opt/spork-acme/backups/pre-upgrade-20260209-120000.tar.gz -C /

# Start the service
$ sudo systemctl start spork-acme

# Verify
$ spork-acme --version

Rollback from manual backup

# Stop the service
$ sudo systemctl stop spork-acme

# Restore binary
$ sudo cp /usr/local/bin/spork-acme.bak /usr/local/bin/spork-acme

# Restore data directory
$ sudo rm -rf /opt/spork-acme/
$ sudo cp -a /opt/spork-acme.bak/ /opt/spork-acme/

# Start the service
$ sudo systemctl start spork-acme
Info: SPORK CA uses SQLite with WAL mode. Database schema migrations are forward-compatible within the same minor version series (0.2.x). Rolling back across minor versions may require restoring the database from backup.

6. Version History

Critical: ProtectSystem=strict issue (#106) — If your systemd service file uses ProtectSystem=strict, editing and reloading the service file can wipe your state directory. Change to ProtectSystem=full immediately. This is fixed in v0.5.2+ generated service files.

v0.5.2 (2026-03-10)

v0.5.1 (2026-03-10)

v0.5.0 (2026-03-10)

v0.4.x (2026-03-05 to 2026-03-09)

v0.3.x (beta)

v0.2.6 (2026-02-11)

v0.2.5 (2026-02-10)

v0.2.4 (2026-02-10)

Setup Wizard

Installer Improvements

Documentation & CI

v0.2.1 (2026-01-22)

v0.1.0 (2025-12-22)