Lutra/docs/deployment.md
danny 872b5cb258
Some checks are pending
ci / ci (macos-15) (push) Waiting to run
ci / ci (ubuntu-24.04) (push) Waiting to run
ci / ci (windows-2025) (push) Waiting to run
D1: deployment UI, docs and G17
Servers dialog (write-only keychain secret, test connection, unknown and
changed host key), status-bar progress with Cancel, Deployment log tool
window, Upload/Download in the project tree menu and Tools › Deployment.
docs/deployment.md, architecture section, G17 row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 19:14:58 +01:00

4.5 KiB
Raw Blame History

Deployment

Status: Deployment v1 (C9 D1, owner decision D27): servers per project, upload, download, upload on save, test connection, host keys, Deployment log. Remote browser, compare and sync follow in D2 · 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.
  • Uploads send what is on disk; save first. 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.

For agents and scripts

The deploy.* engine commands (deploy.servers, deploy.saveServer, deploy.setSecret, deploy.testConnection, deploy.trustHostKey, deploy.upload, deploy.download, 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.

Not yet (D2)

A remote file browser, opening and editing remote files, compare with the server, and sync with a preview.