How to Upgrade S-UI to the Latest Version: Complete Technical Guide

To upgrade S-UI to the latest version, execute the official install.sh script, which downloads the newest GitHub release, replaces the systemd service binaries, and automatically runs the database migration tool to sync your SQLite schema without data loss.

Upgrading the S-UI panel—maintained in the alireza0/s-ui repository—requires atomic replacement of backend binaries while preserving your existing configuration database. The entire workflow is encapsulated in a single shell script that handles version detection, tarball extraction, service management, and schema updates orchestrated through the Go migration package.

Automated Upgrade Process

The upgrade follows a deterministic sequence defined in install.sh. When executed, the script queries the GitHub API to determine the current semantic version tag, then orchestrates file replacement, database migration, and service restart.

Step 1: Download and Execute the Install Script

Fetch the script directly from the master branch and pipe it to bash. This command detects your system architecture and queries https://api.github.com/repos/alireza0/s-ui/releases/latest to retrieve the current tag_name (lines 37-44 of install.sh).

bash <(curl -Ls https://raw.githubusercontent.com/alireza0/s-ui/master/install.sh)

Step 2: Binary Replacement and Service Management

The script gracefully stops the existing service using systemctl stop s-ui (lines 60-63), then downloads the architecture-specific tarball to /tmp/. It extracts the archive and copies new binaries to /usr/local/s-ui/ while updating systemd unit files in /etc/systemd/system/ (lines 64-71).

# Commands executed internally by the script

wget -N --no-check-certificate -O /tmp/s-ui-linux-$(arch).tar.gz \
  https://github.com/alireza0/s-ui/releases/download/${last_version}/s-ui-linux-$(arch).tar.gz

tar zxvf /tmp/s-ui-linux-$(arch).tar.gz
cp -rf s-ui /usr/local/
cp -f s-ui/*.service /etc/systemd/system/

Step 3: Database Migration

After file replacement, the script invokes /usr/local/s-ui/sui migrate through the config_after_install function. This executes the Go migration package defined in cmd/migration/main.go, which iterates through sequential version files (e.g., 1_1.go, 1_2.go, 1_3.go) to upgrade your SQLite database schema without affecting stored data.

Step 4: Post-Installation Configuration

The script interactively prompts you to preserve or modify panel settings, including the HTTP port, application path, subscription parameters, and administrator credentials. By default, it retains your existing configuration database located according to paths defined in config/config.go.

Finally, it runs systemctl enable s-ui --now (line 76) to register the updated service and start the panel immediately.

Pinning a Specific Version

To upgrade S-UI to a specific version rather than the latest, pass the VERSION environment variable to the install script. This overrides the GitHub API query and fetches the corresponding release tarball directly.

VERSION=v2.3.1 bash <(curl -Ls https://raw.githubusercontent.com/alireza0/s-ui/master/install.sh) $VERSION

Key Source Files in the Upgrade Workflow

Understanding the migration architecture helps troubleshoot failed upgrades or customize deployment pipelines:

• install.sh (lines 37-76): Main orchestration script containing the version detection, download, extraction, and service management logic.
• cmd/migration/main.go: Migration driver that executes schema transformations against the SQLite database.
• cmd/migration/1_1.go, 1_2.go, 1_3.go: Sequential schema transformation files representing incremental database changes.
• config/config.go: Defines system paths for the binary location (/usr/local/s-ui/) and database files.
• service/server.go: HTTP panel implementation; remains unaffected by the binary swap but provides context for service startup behavior.

Verification Steps

After the script completes, run sui version to confirm the binary reports the expected tag (e.g., v2.4.0). Access the web panel at your configured URL (default http://localhost:2095/app) to verify functionality. If you modified credentials during the script prompts, authenticate with the new username and password. You may optionally remove the temporary tarball from /tmp/ to reclaim disk space.

Summary

• Run bash <(curl -Ls https://raw.githubusercontent.com/alireza0/s-ui/master/install.sh) to initiate the upgrade process.
• The script automatically queries the GitHub API, downloads the correct architecture-specific tarball, and stops the existing systemd service before file replacement.
• Binary replacement occurs in /usr/local/s-ui/ and /etc/systemd/system/ with files extracted from the release archive.
• Database migration runs automatically via /usr/local/s-ui/sui migrate using the logic in cmd/migration/main.go to update your SQLite schema to the current version.
• The interactive post-install phase preserves existing settings by default while allowing optional credential and port changes.

Frequently Asked Questions

Will upgrading S-UI delete my existing configuration?

No. The upgrade process preserves your SQLite database and configuration files. The install.sh script explicitly prompts you during the post-install phase to keep existing panel settings, ports, and admin credentials, migrating only the database schema structure via cmd/migration/main.go.

Can I upgrade S-UI without stopping the service?

No. The script runs systemctl stop s-ui (lines 60-63 of install.sh) before replacing binaries to prevent file locks and data corruption. The service is automatically restarted with systemctl enable s-ui --now (line 76) after migration completes.

What happens if the database migration fails?

The migration tool in cmd/migration/main.go executes sequentially through version-specific files (e.g., 1_1.go, 1_2.go). If a migration step fails, the process halts and the service does not start, preventing data inconsistency. Check the output of /usr/local/s-ui/sui migrate for specific schema errors and version mismatches.

How do I verify the upgrade succeeded?

Run sui version to confirm the binary reports the expected tag (e.g., v2.4.0), and access the web panel at your configured URL (default http://localhost:2095/app). The systemd service status should show active (running) after the script completes, confirming that S-UI is running the latest version.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}