Sherpa AI Server Updates#
Before updating, review the release notes for every version from the installed version to the target version and prepare a data backup. The notes may contain mandatory upgrade steps. Notes for the latest published release: version 2.5.1. Services will stop temporarily during the update.
When updating from 2.5.0 to 2.5.1, first prepare the indexes of the populated database. Run the update only after the index check succeeds. Otherwise, the migration may fail.
Update with the script#
From the root of the existing Sherpa AI Server installation, run:
sudo ./sh_scripts/update.sh
The script determines the target version from the client-files archive and selects only archives of that version. Before stopping services, it checks available SHA-256 checksums and Docker archive manifests, free space, and required images. It then backs up the configuration and data, updates files and images, runs migrations, and checks startup. It is necessary to review the displayed version and action list before confirming.
When a component is not published for the target version, the script keeps its current :latest image and checks, before stopping services, that this image exists and matches the running container. This is an expected partial release. The target-version client-files archive is always required. If a published archive cannot be downloaded, or the required .SHA256SUM file is missing for an available online artifact, the update stops.
For an offline update, copy docker_aiserver_client_files_<version>.tgz and the archives of actually published components of the same version to the installation root. Include their .SHA256SUM files when supplied. It is necessary to check the bundle against the published component list before running the script: offline, it cannot distinguish an intentionally omitted component from an archive forgotten during transfer. Obtain any expected missing archive before updating. An offline archive without a .SHA256SUM file still receives structural checks, but its SHA-256 cannot be verified. Any supplied checksum must match. Do not mix versions or choose images from independent /latest endpoints.
Switch to external LLM and Embedding services during an update#
On a server with local LLM and Embedding services, the script offers to switch to external services. Press Enter to keep the current mode, or enter y to switch. Before containers stop, provide both service URLs in the http(s)://host:port format, the LLM model name, and an Embedding token if required. Enter 0 to cancel input; the active installation settings remain unchanged.
When switching, the script saves the addresses and settings in .env, stops the former local containers, and does not request their images or model archives. Optional Whisper and BGE Reranker profiles are preserved. After the update, check that COMPOSE_PROFILES in .env contains external and inspect containers with docker compose --profile external ps.
In the Models section, open the LLM instance in use. Set its “Host,” “Port,” “Scheme,” and “Model path” fields to the external service values, then save it. Chat uses the saved instance settings, so changing .env alone is insufficient. Check a response in Chat and index a test document. If the connection fails, check access to the external addresses from the main server and inspect the aiserver logs.
Backup retention#
By default, the script keeps all backups. To retain the two most recent complete sets after a successful update, an administrator must run:
sudo env SHERPA_UPDATE_BACKUPS_KEEP=2 ./sh_scripts/update.sh
A complete set includes copies of .env, docker-compose.yml, client files, a PostgreSQL dump, and Docker volume archives. If the current dump or volume archives are missing, older sets are not deleted. The value must be a positive integer. Rotation also covers model backup directories. Sets created before the completeness marker was introduced are left in place. Setting it to 0 or leaving it unset disables rotation.
Verify the result#
After the update, an administrator can run the full diagnostic from the installation directory:
sudo ./sh_scripts/diagnostics.sh
Exit code 0 and the message Диагностика завершена без замечаний mean that the container, PostgreSQL, disk space, and API response checks passed. If the exit code is 1, read the affected component in the message and inspect the indicated logs. To get a diagnostics prompt immediately after a successful update, start the wizard with SHERPA_DIAGNOSTICS_OFFER=true. The prompt is disabled by default.
When the script finishes, confirm that it reports successful migrations and service checks. Also inspect the containers and application log:
docker compose ps
docker compose logs --tail 100 aiserver
If the update fails, save its output and use the recovery instructions and backups shown by the script. Do not replace archives or rerun migrations blindly. After manually changing .env, apply the settings with docker compose up -d --force-recreate; docker compose restart does not reload environment variables.