W WPMMCC ATS / Docs
简体中文

WPTSALL Client Complete Guide

WPTSALL Client is the local-first companion daemon and desktop application for the WPMMCC ATS WordPress plugin. This guide details installation, updates, uninstallation, configuration parameters, and the complete end-to-end automated translation workflow.

Local-First Guarantee: WPTSALL Client runs on your hardware — not in a vendor cloud. Your site credentials, translation memory, and AI provider API keys stay in your local SQLite database (wptsall.db, under your OS data directory) and are never routed through intermediary SaaS servers.

1. Overview & Product Architecture

WPTSALL Client ships in two form factors sharing the exact same compiled Rust core engine (tokio async runtime, reqwest with rustls, bundled SQLite, and cryptographic signature validation):

  • WebUI (Daemon / Background Service): Runs as a headless daemon on 127.0.0.1:8977. Ideal for servers, VPS, local workstations, or NAS devices. Accessible via any standard web browser.
  • Desktop Application (Tauri 2): Native window for the same engine. It listens on 127.0.0.1:8978 by default and stays on this computer, so it can run beside the WebUI on port 8977. It does not open its interface onto the network.

2. Cross-Platform Installation

Official release kits and installer scripts are published on the wptsall-client-releases repository. Every kit is cryptographically signed with minisign and includes SHA-256 checksums.

Linux Installation (WebUI Daemon)

Download the official installer, review it, then run it — never pipe remote scripts straight into a shell:

curl -fsSL -o install.sh https://raw.githubusercontent.com/wpmmcc/wptsall-client-releases/main/install.sh
less install.sh    # review the script before running it
sh install.sh

What this does automatically:

  1. Detects system architecture (x86_64 or aarch64) and verifies the minisign cryptographic signature and SHA-256 hash.
  2. Installs binaries to ~/.local/opt/wptsall-client/.
  3. Creates command-line symlinks in ~/.local/bin/wptsall-client and ~/.local/bin/wptsall-webui.
  4. Registers and activates a systemd user service (~/.config/systemd/user/wptsall-client.service) configured to restart automatically on failure.
  5. Launches the WebUI at http://127.0.0.1:8977.

macOS Installation (WebUI Daemon or Desktop)

For the background WebUI service, run:

curl -fsSL -o install.sh https://raw.githubusercontent.com/wpmmcc/wptsall-client-releases/main/install.sh
less install.sh    # review the script before running it
sh install.sh

This configures a native LaunchAgent at ~/Library/LaunchAgents/cc.wpmm.wptsall-client.plist that starts the WebUI automatically upon login. Alternatively, download the .dmg package from GitHub Releases for the graphical Desktop application — it is minisign-verified (artifact integrity) but not Apple Developer-ID signed, so Gatekeeper will ask for authorization on first launch (see below).

Windows Installation (PowerShell)

Open Windows PowerShell, download and review the script, then run it:

irm https://raw.githubusercontent.com/wpmmcc/wptsall-client-releases/main/install.ps1 -OutFile install.ps1
Get-Content install.ps1    # review the script before running it
powershell -ExecutionPolicy Bypass -File .\install.ps1

What this does automatically:

  1. Downloads and verifies the signed kit.
  2. Extracts to $env:LOCALAPPDATA\wptsall-client.
  3. Adds the installation directory to your user PATH.
  4. Creates a startup shortcut in your user Startup folder so the WebUI is ready upon login.
  5. Starts the process and opens http://127.0.0.1:8977.

First-Launch Authorization (Unsigned OS Builds)

Release artifacts are protected by minisign signatures and SHA-256 checksums — this guarantees what you download is exactly what we published. However, the Desktop application currently carries no operating-system code-signing certificate (no Apple Developer ID, no Microsoft Authenticode). On first launch the OS itself will therefore show a warning. This is expected behavior for an unsigned build, not evidence of tampering:

  • macOS (Gatekeeper): "WPTSALL Client" cannot be opened because it is from an unidentified developer. — Open System Settings → Privacy & Security, scroll to the Security section, and click Open Anyway. On macOS 14 and earlier you can instead right-click the app → Open → Open. Terminal users may clear the quarantine flag after verifying checksums: xattr -dr com.apple.quarantine "/Applications/WPTSALL Client.app"
  • Windows (SmartScreen): Windows protected your PC. — Click More info, then Run anyway. Or, after verifying checksums: Unblock-File .\wptsall-client.exe

Recommended order: verify first (minisign + SHA-256, commands in the release README-AUTHORIZATION.md), then authorize. Full step-by-step instructions ship inside every release as FIRST-LAUNCH-AUTHORIZATION.md and as README-AUTHORIZATION.md next to the downloads.

Building from Source

If you prefer compiling directly with Rust toolchains:

# Build WebUI binary
cd client-wpplugin/source
cargo build --release
# Output binary: target/release/wptsall-client

# Build Desktop App (requires Node.js + Tauri CLI)
cd client-desktop
npm install
npm run tauri build

3. Updating & OTA Security

WPTSALL Client provides automatic, in-place Over-The-Air (OTA) updates with strict verification safeguards:

  • In-App Update Check: In the WebUI, navigate to Settings → About and click Check for Updates. When a release source is configured (see WPTSALL_SERVER_BASE below) and a new version is available, it downloads and installs in place.
  • Cryptographic Verification: Every update kit is checked against the official minisign public key (RWR7lrdabZEEywfWEfrRJXIyP5h+LHEabOA8JFiNJ3vGLpNtppyabHfP) and verified with SHA-256. Tampered or partially downloaded kits are rejected immediately.
  • Anti-Rollback Protection: Version numbers are checked sequentially to prevent downgrade attacks.
  • Zero-Downtime Safe Swapping: On Windows, where active executable files are locked by the OS, the updater renames and replaces the binary safely, with automatic rollback if replacement fails. On Linux and macOS, the system service restarts cleanly.
  • Manual Update: You can also run the installer script again at any time; it will safely upgrade the binary in place without touching your configuration or task database.

4. Uninstallation & Data Retention

Dedicated uninstaller scripts for all products and operating systems are provided in the releases repository:

Linux / macOS Uninstallation

# Standard uninstall (keeps your SQLite database, settings, and logs)
sh uninstall-webui.sh

# Complete uninstall including database and logs
sh uninstall-webui.sh --purge-data --yes

# If you also have Desktop installed and want to remove shared binaries
sh uninstall-webui.sh --purge-shared --purge-data --yes

Windows Uninstallation

# Standard uninstall via PowerShell
.\uninstall-webui.ps1

# Complete purge including SQLite database and logs (-PurgeData requires -Yes)
.\uninstall-webui.ps1 -PurgeData -Yes
Safe by Default: Like the WordPress plugin, WPTSALL Client protects your data. By default, uninstallation removes background service units, command-line symlinks, and executables, but leaves your SQLite database (wptsall.db) and translation logs intact. A future reinstallation will pick up exactly where you left off.

5. Parameter Configuration & Environment Variables

WPTSALL Client can be configured via environment variables, configuration files, or interactively within the WebUI Settings tab.

Variable / Parameter Default Value Description
WPTSALL_WEB_UI false Enables the local web UI HTTP daemon. The service installers set this to 1 automatically; a bare terminal run starts the worker without the UI.
WPTSALL_WEB_UI_BIND 127.0.0.1:8977 Network interface and port to bind the WebUI listener to.
WPTSALL_WEB_UI_PORT 8977 Listening port for the WebUI HTTP service.
WPTSALL_DATA_DIR ~/.local/share/wptsall-client (Linux & macOS, set by the service installer)
%LOCALAPPDATA%\wptsall-client (Windows)		 Base directory for persistent state: the SQLite database (wptsall.db) lives under <data dir>/runtime/, logs under <data dir>/logs/, configuration under <data dir>/config/. The Desktop app keeps its own data under the OS application-data directory (wptsall-desktop). Without this variable, a terminal run uses ./runtime, ./logs, ./config relative to the working directory.
WPTSALL_LOG_FILE <data dir>/logs/wptsall-client.log Target file path for client process execution logs.
WPTSALL_LOG_ENABLED false Debug logging flag. Can also be dynamically toggled at runtime in WebUI Settings.
WPTSALL_ONESHOT false When set to true, the worker claims one pending batch, writes back results, and exits cleanly (ideal for crontab).
WPTSALL_POLL_SECONDS 20 Interval in seconds between translation task polling checks in continuous daemon mode (minimum 1 second).
WPTSALL_SERVER_BASE unset Base URL for the release-update manifest. There is deliberately no built-in default (local-first): the in-app update check only works when this is configured explicitly (legacy alias: WPTSALL_SERVER_URL). Without it, update by re-running the installer script.

Port 8977 and Conflict Handling

The WebUI listens on 127.0.0.1:8977 by default — loopback only, so the interface is never exposed to your network. Port 8977 is not registered with IANA and sits away from the common service and development ranges (3306, 5432, 6379, 8080, 9000, 9200, and friends), so conflicts are rare in practice. If another local program has already taken the port, the client fails to start with bind web ui failed: 127.0.0.1:8977; set WPTSALL_WEB_UI_PORT (or WPTSALL_WEB_UI_BIND for a full address) to a free port and restart the service. For the systemd user unit, systemctl --user edit wptsall-client is the cleanest way to add the override; the Desktop app exposes the same variables as environment variables for the embedded WebUI.

6. End-to-End Integration Workflow

Understanding how WPMMCC ATS (WordPress) and WPTSALL Client coordinate during automated translation:

  1. Content Model Scan (WordPress): In wp-admin, navigate to WPMMCC ATS → Content Models. The plugin scans posts, taxonomies, menus, and third-party plugins (WooCommerce, ACF, Elementor), generating a unified translation rule set.
  2. Site Relations (WordPress): Under Site Relations, define your target language virtual site (e.g. Source: English, Target: Spanish with URL prefix /es/).
  3. Authorize Client (WordPress): Under Task Management → Authorization, click Generate Connection Pack. The pack carries your site URL, route secret and a one-time pairing code, and stays claimable for the validity window you choose (default 5 minutes). WP-CLI alternative: wp wptsall security issue-pairing-pack --device-id=<client-device-id>.
  4. Connect Site (Client): Open the client WebUI (http://127.0.0.1:8977) or Desktop app. On the Sites page, paste the connection pack JSON together with the pairing code and import it — the client claims a device-scoped token automatically and tests the connection.
  5. Configure AI Provider (Client): Under My Components, install a provider component from the catalog (DeepSeek, OpenAI, Claude, DeepL compatible, or a local OpenAI-compatible endpoint such as Ollama on http://127.0.0.1:11434) and store its API key under API Keys.
  6. Execute Translation Worker: Under the Worker tab, click Run Once (or start continuous background polling). The client claims pending batches from WordPress, translates them using your provider endpoint, and executes idempotent write-backs.
  7. Target Sites Live: Translated articles, terms, and custom fields appear immediately under their respective virtual site URLs.