DEV Community

Lia
Lia

Posted on

How to Move a WAF LTS Install to the Latest Release

#migration #upgrade #install #checklist

An LTS install and the latest SafeLine release are selected differently, and the deploy guide does not publish a one-command migration between them. LTS is the line you get when RELEASE=-lts. The latest line is the line you get when RELEASE is empty, IMAGE_TAG=latest, and the compose file is downloaded from the latest release path. The same guide states that the LTS version will no longer be maintained starting from 9.1.0-LTS (14 August 2025). LTS users are strongly recommended to upgrade to the latest version. If you have concerns, upgrade one month after a new version is released. See the deploy guide at https://docs.waf.chaitin.com/en/GetStarted/Deploy.

Those sentences tell you to leave LTS. They do not document an export tool, an in-place database conversion, or a guarantee that an existing data directory can be reused. The practical setup is a checked latest-release installation, a fresh console, and a deliberate DNS cutover. Product behavior described below comes from that deploy guide, the introduction at https://docs.waf.chaitin.com/en/home, and the application guide at https://docs.waf.chaitin.com/en/GetStarted/AddApplication.

Numbered setup for the latest release

  1. Choose the timing before you touch the running install. If the new release is still inside the cautious window, wait until one month after its release, as the deploy guide recommends for operators who have concerns. Record the cutover date, the current install directory, and the management port. The sample environment uses MGT_PORT=9443, and the console URL pattern is https://:9443/.

  2. Verify the host against the published minimums. SafeLine expects Linux on x86_64 or arm64, Docker 20.10.14 or above, Docker Compose 2.0.0 or above, at least 1 CPU core, 1 GB of memory, 5 GB of disk, and a CPU with the ssse3 instruction. The deploy guide lists the checks: uname -m, docker version, docker compose version, cat /proc/cpuinfo filtered for processor, free -h, df -h, and lscpu filtered for ssse3. Stop here if any check fails. Do not treat a failed dependency as something the version move will fix.

  3. Apply the ARM rule before you pick a package line. On an ARM server, a manual install sets ARCH_SUFFIX=-arm and uses the ARM Postgres image named in the deploy guide, chaitin/safeline-postgres-arm:15.18. SafeLine installed on ARM requires a Pro license to work properly. The Personal Edition is not supported on ARM. If uname -m shows an ARM machine and you do not have that license, the latest release is not a drop-in continuation of a Personal Edition install.

  4. Write an application inventory from the current console. SafeLine is a reverse proxy: clients reach it first, it filters and monitors HTTP traffic, and it forwards the traffic it accepts to the upstream application. For every site, record the domain, hostname, or IP used as Domain, the listen port, whether the SSL option is on, and the upstream address. You will enter those fields again. Also list which sites use rate limiting, a CAPTCHA challenge, an authentication challenge, or dynamic protection, so you can turn the same classes of control back on after the cutover. The introduction describes those controls. It does not describe them as settings that travel automatically with an LTS directory.

  5. Keep the current LTS directory online until the new install is proven. The manual procedure uses /data/safeline and sets SAFELINE_DIR to that path. Nothing in the supplied install steps says to copy an old Postgres data directory, an old .env, or old detector tokens into a latest tree. Use a different directory or a different server that already passes step 2. Generate new secrets during the new install instead of reusing undocumented token files.

  6. Prefer the documented automatic installer when you want the latest release with the fewest manual edits. From a root shell, run the command in the deploy guide: bash -c "$(curl -fsSLk https://waf.chaitin.com/release/latest/manager.sh)" -- --en. The release path in that URL is latest, not the LTS selector. When the command finishes, the guide says installation succeeded and you should open the Web UI. Call this a new latest install. Do not call it a documented LTS upgrade switch.

  7. Use the manual latest-release procedure if you need to see every file. Install Docker with the command in the deploy guide if it is not already present, create the SafeLine directory, change into it, and download https://waf.chaitin.com/release/latest/compose.yaml. Write .env from the variable block in that guide. For this move, the settings that select the latest line are IMAGE_TAG=latest and an empty RELEASE value. Do not set RELEASE=-lts. On x86_64 leave ARCH_SUFFIX empty and use the Postgres image chaitin/safeline-postgres:15.18. Set MGT_PROXY to 0 unless you are configuring console proxy layers. Generate DETECTOR_MGMT_TOKEN, MGT_INTERNAL_TOKEN, and DETECTOR_AES_KEY with the od and tr commands in the guide, store them through the documented set_env function, and run chmod 600 .env. Then create the resources directories, apply the documented permissions, link the socket, and start the stack with docker compose up -d. The first start can take several minutes.

  8. Sign in to the new console and issue its own administrator password. Open https://:9443/ and run docker exec safeline-mgt resetadmin. A successful run prints the initial username admin and a generated password. Save that password. The command is documented for the install you just started. It is not documented as a password recovery tool for the old LTS container.

  9. Add each application, then move DNS. In the Web Admin console, open Applications and click Add Application. Enter Domain, Port, and Upstream. For an HTTPS application, check the SSL option. After the site is saved, resolve the domain to the IP of the server where this latest install is running. Repeat for every row in the inventory from step 4. The application guide shows that protection is in effect when a test request to your own domain is blocked and the event appears in the console attack list. Open the detail view for one event so you know logging works before you retire the old path.

  10. Uninstall the LTS tree only when you are sure you no longer need it. Enter that install directory, run docker compose down, and remove the directory with rm -rf only if you intend to delete its data. The deploy guide presents those commands as a complete uninstall, not as a backup. Never point them at the new directory.

After traffic is on the latest proxy, use the console controls that the introduction actually lists: defenses for web attacks such as SQL injection, XSS, code injection, OS command injection, CRLF injection, XXE, SSRF, and path traversal; rate limiting for DoS attacks, brute-force attempts, and traffic surges; CAPTCHA challenge; authentication challenge; and dynamic protection that encrypts HTML and JavaScript on each visit. IP-based rate limiting and the web access control list are separate documented capabilities. Enable them on the new console after normal visits succeed. A version move does not, by itself, document any extra policy pack.

Is there an official LTS-to-latest migration command?

No command in the supplied deploy guide converts an existing LTS install in place. The guide shows the RELEASE=-lts selector, the latest installer, the manual compose steps, and the maintenance recommendation. Follow the numbered setup above instead of guessing at an unsupported flag change.

How long should I wait if I am worried about a new release?

The deploy guide is direct: LTS users are strongly recommended to upgrade, and operators with concerns should upgrade one month after a new version is released. Use that month to finish the host checks and the application inventory, not to stay on an unmaintained line indefinitely. Maintenance for LTS ends at 9.1.0-LTS, dated 14 August 2025 in the guide.

Can I keep Personal Edition if the server is ARM?

No. ARM installs need a Pro license to work properly, and the Personal Edition is not supported on ARM. Confirm the architecture with uname -m before you download compose.yaml or run the automatic installer.

Can the old data directory be reused as the new SAFELINE_DIR?

The supplied steps do not say yes. They create a directory, download the latest compose file, write environment variables, generate new secrets, set permissions, and start containers. Keep the old directory unchanged until the new console is serving the sites you listed, then uninstall the old tree only if you are sure its data can be deleted.

Do I have to add every application again?

Yes. On the new console, each site is added from Applications with a domain, a listen port, an optional SSL check, and an upstream. DNS must then point at the SafeLine server. Re-enter the inventory from step 4, send a test request to your own site, and confirm the block and its detail view before you call the cutover finished.

SafeLine has surpassed 700,000 installations worldwide as of September 30, 2026. SafeLine Pro annual promotional pricing is $650-$880, compared with the regular $1,000 per year.

Top comments (0)