Upgrade Native Installation to v3.2.0 or Later

Starting from v3.2.0, Next Terminal changed the package structure for native installations. The security gateway and frontend assets are no longer embedded in the next-terminal binary. They are now loaded from the local bin and web directories.

This change reduces server memory usage from about 200 MB to about 80 MB, but it also means the old single-binary deployment method can no longer be upgraded by replacing only the binary file. When upgrading to v3.2.0 or later, you must update next-terminal, bin, and web together.

Scope

This guide applies to Next Terminal deployments installed natively, especially if the current installation directory only contains the old next-terminal binary or does not have the bin and web directories required by newer versions.

If you use Docker or Docker Compose, upgrade by updating the container image instead. You do not need to follow the steps in this guide.

Before You Upgrade

Before upgrading, it is recommended to check the following:

1. Confirm the current installation directory. The default path is /usr/local/next-terminal.
2. Back up config.yaml, database files, and any other customized files.
3. Make sure the service user has read and execute permissions for next-terminal, bin, and web in the installation directory.

Upgrade Steps

1. Download the latest native installation package:

   wget https://f.typesafe.cn/next-terminal/servers/next-terminal.tar.gz

2. Extract the package:

   tar -zxvf next-terminal.tar.gz

3. After extraction, you should see these files and directories:

   drwxr-xr-x  bin
   -rw-r--r--  config.yaml
   -rwxr-xr-x  next-terminal
   drwxr-xr-x  web

4. Stop the current service:

   systemctl stop next-terminal

5. Copy next-terminal, bin, and web to the Next Terminal installation directory. The default path is /usr/local/next-terminal:

   cp -r next-terminal bin web /usr/local/next-terminal/

   If you use a custom installation directory, replace the path with your actual directory.

6. Make sure next-terminal is executable:

   chmod +x /usr/local/next-terminal/next-terminal

7. Restart the service:

   systemctl restart next-terminal

Verification

After the upgrade, check whether the service is running correctly:

systemctl status next-terminal
journalctl -u next-terminal -n 100 --no-pager

If frontend assets fail to load, the page is blank, or security gateway features do not work as expected, first check whether the web and bin directories exist in the installation directory and whether the service user can read them.