Remote Host tool window (server select, tree, read-only viewer with Edit and Upload, rename, new folder, delete after its question), server tabs in the diff viewer, sync preview (uploads preselected, deletions never, extra confirmation before deleting on the server), Compare with Server in the tree menu and Tools › Deployment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
69 lines
6.6 KiB
Markdown
69 lines
6.6 KiB
Markdown
# Deployment
|
||
|
||
> **Status:** Deployment v1 (C9 D1, owner decision D27): servers per project, upload, download, upload on save, test connection, host keys, Deployment log. v2 (C9 D2): Remote Host browser, compare with the server, sync with a preview, save before upload · **Last updated:** 2026-11-06
|
||
|
||
Lutra uploads a PHP project to a server and downloads files back, the way people deploy shared hosting and small servers every day.
|
||
|
||
## Servers
|
||
|
||
Open **Tools › Deployment › Servers…**. Each project has its own list; one is the default server (the only one is the default automatically).
|
||
|
||
| Field | Meaning |
|
||
|---|---|
|
||
| Name | Shown in the log, the status bar and toasts. |
|
||
| Type | **SFTP** (SSH), **FTPS** (FTP with explicit TLS, certificates checked against the system's trusted roots), **FTP** (unencrypted: everything, including the password, crosses the network in clear text; prefer SFTP or FTPS), or a **local or mounted folder**. |
|
||
| Host, Port, User | Port defaults to 22 (SFTP) or 21 (FTP, FTPS). |
|
||
| Sign in with | SFTP: password, private key file (with an optional passphrase), or the SSH agent (Pageant or the OpenSSH Authentication Agent on Windows, `SSH_AUTH_SOCK` on macOS). FTP and FTPS: password. |
|
||
| Root folder | The server folder everything is relative to; empty for the login folder. For a folder server: the absolute local folder. |
|
||
| Path mappings | Local folder (project-relative, empty for the root) → remote folder (relative to the root, or absolute with a leading `/`). The longest matching local folder wins. Without mappings the project root goes to the root. Files outside every mapping are skipped. |
|
||
| Excluded paths | One per line. A path excludes itself and everything below it (`var/cache`); a pattern with `*` or `?` matches file and folder names (`*.log`). `.git`, `.svn` and `.hg` are never deployed. |
|
||
| Upload on save | Off by default. When on, every saved file that maps to the server is uploaded in the background. |
|
||
|
||
The configuration lives in Lutra's config directory (`deployment/<project-id>.json`), not in the project, and never contains a password.
|
||
|
||
## Passwords and passphrases
|
||
|
||
- They are stored **only in the operating system's keychain**: the Windows Credential Manager or the macOS Keychain, under the service "Lutra Deployment".
|
||
- Lutra never writes them to a file, a log, the recovery journal, an event, MCP or control-channel output, or an error message. The password field in the dialog is write-only: after Save it empties again and says "Stored in the system keychain".
|
||
- Removing a server removes its keychain entries.
|
||
- Linux has no keychain store yet; there, use the SSH agent or a key without a passphrase.
|
||
|
||
## Host keys (SFTP)
|
||
|
||
On the first connection, **Test Connection** shows the server's key fingerprint (`ssh-ed25519 SHA256:…`). Compare it with the one from the server's administrator, then choose **Trust and Connect**. Trusted keys are kept in Lutra's own known-hosts file (`deployment/known_hosts` in the config directory); `~/.ssh/known_hosts` is neither read nor changed.
|
||
|
||
If the key later differs, Lutra **refuses to connect** and says so: someone may be intercepting the connection. Only if you know the server was reinstalled, test the connection and choose **Replace the Trusted Key**.
|
||
|
||
Uploads and downloads never ask about a key; they fail with a message pointing to Test Connection.
|
||
|
||
## Upload and download
|
||
|
||
- **Project tree:** right-click a file or folder › **Upload to Server** / **Download from Server** (default server).
|
||
- **Tools › Deployment:** Upload Current File, Download Current File, Upload Project, Test Connection, Deployment Log.
|
||
- The same actions are in the command palette. Lutra assigns no default shortcuts; bind them in the keymap.
|
||
- An upload first saves the open, unsaved files it covers, so the server gets what the editor shows. Downloads replace the local files.
|
||
- While a job runs, the status bar shows it with a Cancel button. One job runs at a time; uploads on save wait for the running one.
|
||
- Every file, skip and error goes to the **Deployment** log in the bottom panel (newest 1,000 lines). A failing file is logged and the job goes on; a lost connection or a refused sign-in stops it. Each error says what to do.
|
||
|
||
## Remote Host
|
||
|
||
**Tools › Deployment › Remote Host** opens the server's folders in the bottom panel (the default server; choose another in the toolbar). Paths are relative to the server's root folder; the browser never leaves it.
|
||
|
||
- Click a folder to expand it, a file to open it. Files open **read-only**; **Edit** makes the text editable and **Upload** writes it back. Files that are not text, or larger than 4 MiB, are not shown.
|
||
- **Rename** and **Delete on Server** are on each row; **New Folder** goes into the selected folder. Delete always asks first, names what goes (a folder with everything inside it), and only the red button deletes. The root folder cannot be deleted.
|
||
|
||
## Compare and sync
|
||
|
||
- **Compare with Server** on a file (project tree, or Tools › Deployment › Compare Current File with Server) opens the diff viewer: the server's copy on the left (read-only), your working copy on the right (editable as usual).
|
||
- On a folder, or **Sync Project with Server…**, Lutra lists every file that differs: only in the project, only on the server, or changed (sizes first, then contents up to 8 MiB per file; larger files of equal size count as equal). Excluded and unmapped files are left out.
|
||
- The preview selects the uploads (new and changed files). Files only on the server would be **deleted on the server**; they are never selected for you, and once you select one, Sync stays disabled until you tick "I understand that … files will be deleted on the server". Sync goes from the project to the server only; to take a server change into the project, use Download.
|
||
|
||
## For agents and scripts
|
||
|
||
The `deploy.*` engine commands (`deploy.servers`, `deploy.saveServer`, `deploy.setSecret`, `deploy.testConnection`, `deploy.trustHostKey`, `deploy.upload`, `deploy.download`, `deploy.browse`, `deploy.readRemote`, `deploy.writeRemote`, `deploy.renameRemote`, `deploy.mkdirRemote`, `deploy.deleteRemote`, `deploy.compare`, `deploy.sync`, `deploy.cancel`, `deploy.log`, …) work over the control channel and MCP like every command; see `docs/architecture.md` › Deployment. Their results never contain a secret. `deploy.deleteRemote` refuses without `confirm: true`, and `deploy.sync` refuses deletions without `confirmDelete: true`: an agent must have asked the user.
|
||
|
||
## Not yet
|
||
|
||
- Remote files open in the Remote Host viewer, not as editor tabs with highlighting.
|
||
- FTPS accepts only certificates the system trusts; servers with a self-signed certificate cannot be pinned yet.
|
||
- Linux has no keychain store yet.
|