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

> Upgrade S-UI to the latest version seamlessly. Run install.sh to download the newest release update systemd binaries and migrate your SQLite schema without data loss.

- Repository: [Alireza Ahmadi/s-ui](https://github.com/alireza0/s-ui)
- Tags: how-to-guide
- Published: 2026-05-22

---

**To upgrade S-UI to the latest version, execute the official [`install.sh`](https://github.com/alireza0/s-ui/blob/main/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`](https://github.com/alireza0/s-ui/blob/main/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`](https://github.com/alireza0/s-ui/blob/main/install.sh)).

```bash
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).

```bash

# 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`](https://github.com/alireza0/s-ui/blob/main/cmd/migration/main.go), which iterates through sequential version files (e.g., [`1_1.go`](https://github.com/alireza0/s-ui/blob/main/1_1.go), [`1_2.go`](https://github.com/alireza0/s-ui/blob/main/1_2.go), [`1_3.go`](https://github.com/alireza0/s-ui/blob/main/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`](https://github.com/alireza0/s-ui/blob/main/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.

```bash
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`](https://github.com/alireza0/s-ui/blob/main/install.sh)** (lines 37-76): Main orchestration script containing the version detection, download, extraction, and service management logic.
- **[`cmd/migration/main.go`](https://github.com/alireza0/s-ui/blob/main/cmd/migration/main.go)**: Migration driver that executes schema transformations against the SQLite database.
- **[`cmd/migration/1_1.go`](https://github.com/alireza0/s-ui/blob/main/cmd/migration/1_1.go), [`1_2.go`](https://github.com/alireza0/s-ui/blob/main/1_2.go), [`1_3.go`](https://github.com/alireza0/s-ui/blob/main/1_3.go)**: Sequential schema transformation files representing incremental database changes.
- **[`config/config.go`](https://github.com/alireza0/s-ui/blob/main/config/config.go)**: Defines system paths for the binary location (`/usr/local/s-ui/`) and database files.
- **[`service/server.go`](https://github.com/alireza0/s-ui/blob/main/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`](https://github.com/alireza0/s-ui/blob/main/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`](https://github.com/alireza0/s-ui/blob/main/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`](https://github.com/alireza0/s-ui/blob/main/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`](https://github.com/alireza0/s-ui/blob/main/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`](https://github.com/alireza0/s-ui/blob/main/cmd/migration/main.go) executes sequentially through version-specific files (e.g., [`1_1.go`](https://github.com/alireza0/s-ui/blob/main/1_1.go), [`1_2.go`](https://github.com/alireza0/s-ui/blob/main/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.