Phonemos is updated by running the update-phonemos.sh script, which pulls the latest code from git, downloads new Docker images, and restarts all services in the correct order. The update process involves a downtime of approximately 5 minutes.

Running an Update

cd /opt/phonemos-linux
sudo ./update-phonemos.sh

The script must be run as the user who owns the git repository (typically root or the user who cloned the repo). It will:

Check for available updates.
Show the current and new version numbers.
Ask for confirmation before proceeding.

What the Update Script Does

1. Check for Updates

The script runs git fetch and compares the local branch with the remote. If no new commits are found, it exits without making changes.

2. Pull Latest Code

Updates all files in /opt/phonemos-linux/, including docker-compose files, scripts, nginx configuration, and templates.

3. Ensure New Configuration Keys and Migrate Application Overlay

If the new version introduces new configuration keys, the script adds them to the existing config files with generated values.

The script also updates /etc/phonemos/app/overlay.yaml when needed: removing service stanzas that no longer exist in docker-compose.yaml and adding stub stanzas for new services.

For Keycloak 26, the script updates /etc/phonemos/keycloak/config when needed: it removes deprecated KC_HOSTNAME_STRICT, KC_PROXY_ADDRESS_FORWARDING, and KC_PROXY lines, and adds KC_HOSTNAME, KC_HTTP_ENABLED, and KC_PROXY_HEADERS.

4. Pull New Docker Images

Calls scripts/pull-images.sh (as the phonemos user) to download the new container images from the registry.

5. Restart Services

Services are restarted in dependency order:

phonemos-postgres
phonemos-keycloak
phonemos-minio
phonemos-ingress
phonemos (main application)

6. Remove Obsolete Application Containers

After the main application restarts, the script runs docker compose up -d --remove-orphans for the Phonemos app stack. This deletes containers for services that were removed from docker-compose.yaml so they do not linger beside the new stack.

7. Verify

All services are checked to confirm they are running correctly.

8. Commit Configuration Changes

If any files in /etc/phonemos/ have changed (e.g. new config keys were added), the changes are committed to the local git repository in /etc/phonemos/.

9. Log the Update

The update is recorded in /etc/phonemos/updates.txt with a timestamp, old version, new version, and commit ID.

What Is Preserved

The update process preserves:

Data volumes — PostgreSQL data, Keycloak data, MinIO files in /data/volumes/
Configuration values — existing values in /etc/phonemos/ are not overwritten
Secrets — passwords, keys, and tokens remain unchanged
TLS certificates — certificate files in /etc/phonemos/ingress/certs/
Custom overlays — any customizations in overlay YAML files

Version-Specific Steps

Some upgrades require manual steps that cannot be automated. These are documented in MANUAL-STEPS.md at the repository root. Check it before upgrading.

Rollback

Code Rollback

The repository at /opt/phonemos-linux/ is a standard git repository:

cd /opt/phonemos-linux
git log --oneline          # Find the commit to roll back to
git checkout <commit-hash>

After checking out an older commit, pull the corresponding Docker images and restart services manually.

Configuration Rollback

The /etc/phonemos/ directory is also a git repository:

cd /etc/phonemos
sudo git log --oneline     # View configuration history
sudo git diff <commit>     # See what changed

Database Migrations

Important: Phonemos may apply database migrations during startup. Rolling back the application version does not roll back database schema changes. Ensure you have a database backup before upgrading.

Phonemos User Guide

Upgrading