Skip to main content

Upgrades, Backups, and Migration

Change configuration or rotate credentials​

Configuration is read at process startup. Apply changes in this order:

  1. Stop the persistent instance, retaining the application and its existing certificates.
  2. Update the settings or credentials in the configuration file.
  3. Run check as the actual runtime account, and doctor --network if needed.
  4. Run sync --once when a file, IIS, or DSM target requires a real deployment check.
  5. Confirm the results, then start the persistent instance.

Stopping a Docker container in exec mode also stops its application. Schedule changes during an appropriate maintenance window and verify them by restarting or recreating the container.

Changes to file target configuration or export passwords can trigger redeployment even when the certificate version is unchanged. Editing a file during a platform reconciliation interval does not mean all settings will be reloaded automatically. Restart the process to apply configuration changes.

Upgrade the program​

  1. Obtain the new package, check its OS, architecture, and SHA256 checksum, and review the provider's upgrade notes.
  2. Stop CertOne.
  3. Back up the current executable, configuration including credentials, complete state directory, and necessary application configuration.
  4. Replace the executable at the same path, retaining the state directory.
  5. Run version, check, and any required connection checks.
  6. Start the agent and verify deployment and application status.

For Docker, rebuild the image and recreate the container, mounting the existing .certone data volume and any custom output directories. Do not delete volumes as part of an upgrade.

If the executable path changes, the system service may still refer to the old location. Update its registration. Check state-format compatibility before downgrading; do not assume every older binary can read newer state.

Back up and migrate​

The state directory contains instance identity, cached certificate private keys, and recovery information. It is not disposable cache.

  • Stop the instance before backing it up to obtain a consistent set of files.
  • Configuration contains Tokens and passwords; protect it and the state directory as sensitive data.
  • Application certificate output files are outside the state directory. Back them up separately as needed.
  • To move an existing instance, stop it on the original machine before restoring configuration and state on the new machine. Check paths, architecture, and permissions.
  • To add a replica, use a new, empty state directory so it receives its own identity. Do not copy a running instance's state directory.
  • Do not copy or manually edit only state.json to change identity or clear failures.

Use a separate state directory when switching to another platform node ID. Do not reuse state containing a different node identity.

Permissions and file management​

On Unix, newly created private keys, certificate outputs, and state files generally use 0600 permissions; automatically created directories generally use 0700. Files are owned by the account running CertOne.

Consequently:

  • The application process reading certificates must have read access.
  • Run CertOne and the application under suitable accounts, or use a reviewed local deployment script to set the required permissions.
  • Do not assume a one-time manual permission change will persist. A later replacement may recreate the file.
  • Do not use chmod 777 to work around certificate or credential access problems.
  • Generic owner, group, and mode configuration fields are not supported. Unknown fields are rejected.
  • Avoid having other certificate tools write to the same output paths; they may overwrite one another and repeatedly trigger repairs.

Restrict configuration-file modification permissions too, because the file can specify commands to execute locally.

Uninstall​

Stop the local service before removing its registration. These commands use sudo because they control a system service and remove its registration:

sudo "$(command -v certone)" service stop --config "$HOME/.certone/config.yaml"
sudo "$(command -v certone)" service uninstall --config "$HOME/.certone/config.yaml"

On Windows, use the corresponding commands in an administrator PowerShell session. Uninstalling the service does not delete certificates, configuration, or state, and does not undo completed IIS or DSM deployments.

Delete the program and data only after confirming that the application no longer depends on them. Treat container removal and volume deletion as separate operations as well.