mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 20:00:08 +00:00
Anso
7c84969b31
* fix(stacks): validate input, bound YAML parses, and reorder delete steps
Backend hardening covering three editor-served routes:
- `/:stackName/containers` GET adds an explicit `isValidStackName` guard so
bad input is rejected at the call site even if the router-level param
validator changes in future.
- `MAX_COMPOSE_PARSE_BYTES` (1 MiB) bounds the two `YAML.parse` callsites
(`resolveAllEnvFilePaths`, `/services`) so a malformed or oversize compose
cannot exhaust heap during routine env/service lookups.
- `DELETE /:stackName` is reordered to abort before any database cleanup
if `FileSystemService.deleteStack` throws, keeping DB and FS in sync.
Partial-failure responses now describe the resulting state in human
terms instead of returning a generic 500.
Adds debug-mode entry-point traces (`[Stacks:debug] ...`) on save / down /
restart / delete handlers, all sanitised through `sanitizeForLog`. New
vitest covers the containers validator, the YAML size guard, and the
small-compose happy path.
* fix(editor): gate save-and-deploy on save success, abort stale loads
`saveFile` now returns a boolean: true on a successful PUT, false on any
failure. `handleSaveAndDeploy` short-circuits when save fails so a backend
500 on the compose write no longer slips through to a deploy with the
unsaved in-memory content. The diff-preview confirm path in ShellOverlays
applies the same guard.
`loadFile` now drives a per-hook `AbortController`. A stack switch, a
node switch (via `resetEditorState`), or hook unmount aborts the in-flight
GET chain so a late compose / env / containers / backup response from the
previous selection never overwrites freshly-loaded state.
`hasUnsavedChanges` is exported so EditorLayout can check it during the
node-switch lifecycle. New unit tests cover the boolean save contract and
the save-fail-blocks-deploy invariant.
* fix(editor): prompt on node switch when the editor has unsaved changes
Switching the active node previously called `resetEditorState()` without
checking the editor's dirty state, silently dropping in-progress edits.
The post-auth shell now intercepts the node-change effect: if the editor
is dirty, the attempted node is stashed via the existing
`pendingUnsavedNode` field, `pendingUnsavedLoad` is set to a sentinel
that routes `discardAndLoadPending` to `setActiveNode`, and `activeNode`
is reverted to the previous node so the dialog can be resolved without
losing content.
A re-entrant switch (clicking a third node while the dialog is still
open) is now ignored — the second switch reverts silently so the
dialog's anchor stays on the first attempt. When the previous node is no
longer in the registry and cannot be reverted to, the operator gets a
warning toast before the wipe so the loss is at least visible.
* fix(editor): split delete and deploy permission gates in the action bar
The action bar previously wrapped every affordance — including the Delete
menu item — in a single `can('stack:deploy')` check, even though the
backend route requires `stack:delete`. A user with `stack:deploy` only
saw a Delete button that 403'd, and a user with `stack:delete` only saw
no menu at all.
Each affordance now renders against its own permission: deploy / stop /
restart / update on `stack:deploy`, delete on `stack:delete`, rollback on
`canDeploy + isPaid + backupInfo.exists`, scan on `isAdmin +
trivy.available`. The overflow menu appears if any of {rollback, scan,
delete} is granted, so a delete-only operator still has a way to remove
the stack.
Adds a Monaco model dispose on EditorView unmount via the existing
editor ref, and a compact `Stats unavailable` chip in the CONTAINERS
header that lights up when the live-stats WebSocket reports a persistent
failure.
* fix(editor): make container-stats hook reactive to the active node
`useContainerStats` previously read the active node id from
`localStorage` on each WebSocket open, with a deps array of `[containers]`
only. After a node switch the stats stream stayed pointed at the
previous node's `/ws` endpoint until the containers array refreshed.
The hook now accepts `activeNodeId` as a second argument, depends on
`[containers, activeNodeId]`, and drops the localStorage read. The
return shape is `{ stats, error }`: the error field carries a string
when the stream fails, surfaced by EditorView as a small chip in the
CONTAINERS header. A per-WS `warnedOnce` set ensures a flaky daemon
emits at most one console.warn per stream lifetime, never at message
rate. Close codes 1000 / 1001 stay silent (normal teardown, navigation).
The error reset (`setError(null)`) is split into its own effect keyed on
`activeNodeId` so the banner does not flap on every containers-array
refresh tick against a persistently-flaky daemon. Tests cover the new
shape, the node-id reactivity, and the abnormal-close warn behaviour.
* docs(editor): describe new gate split and add troubleshooting entries
Updates the editor cockpit page to reflect that the action bar now
gates each affordance on its own permission (deploy / delete), and that
the bar appears for delete-only users so a stack can still be removed.
Adds three troubleshooting accordions covering the new behaviours: a
failed save that blocks the subsequent deploy, the unsaved-changes
prompt on node switch, and the live-stats chip when the daemon is
unreachable.
Adds an E2E spec verifying that a forced PUT 500 on the compose write
surfaces the failure toast and prevents the deploy POST from firing.
* fix(stacks): use printf-style format for compose-down warn
`console.warn` treats arg-1 as a printf format string when subsequent
args follow. The template literal here interpolated a sanitized but
not %-escaped stackName into arg-1 alongside an error argument, so a
stackName containing a `%s` placeholder could theoretically swallow
the error in the substitution. Switch to the file's established
`'... %s ...', value, err` pattern.
* test(editor): fix save-deploy spec; click both edit buttons, drop Monaco fill
The editor has two edit affordances: a lowercase 'edit' in the Anatomy
panel header that swaps the right column to the editor tabs, and a
capital 'Edit' in the editor toolbar that flips Monaco from read-only
into edit mode. The spec previously matched both with a case-insensitive
regex and only fired one click, so Monaco never entered edit mode.
It also tried to fill .monaco-editor textarea — that element is Monaco's
IME accessibility helper, hard-coded readonly; the real editable surface
is a contenteditable div.
`saveFile()` does not gate on a dirty buffer, so the spec does not need
to modify Monaco at all. Click both edit buttons with case-anchored
regexes and drop the fill step.
* test(editor): disambiguate Save & Deploy locator from sidebar row
The TEST_STACK fixture is named 'e2e-save-deploy-stack'. The sidebar
renders each stack into a div with role=button whose accessible name
includes the stack slug, so the regex /save.*deploy/i matches both the
sidebar row ('e2e-save-deploy-stack') and the editor toolbar's actual
Save & Deploy button — strict-mode bails. Anchor the locator to the
literal button text with exact:true.
210 lines
14 KiB
Plaintext
210 lines
14 KiB
Plaintext
---
|
||
title: Editor
|
||
description: The per-stack cockpit. Run, restart, update, and update compose files; stream logs; exec into a container.
|
||
---
|
||
|
||
Selecting a stack in the sidebar opens the editor cockpit, a two-column workspace for everything you do to a single stack. The left column is the **Command Center** with the stack's identity, action bar, container list, and log stream. The right column starts on the **Anatomy panel**, a read-only summary of the compose file; clicking **edit** swaps it for the Monaco editor with `compose.yaml`, `.env`, and **Files** tabs.
|
||
|
||
<Frame>
|
||
<img src="/images/editor/editor-overview.png" alt="Editor cockpit showing the Command Center and live logs on the left and the Anatomy panel on the right" />
|
||
</Frame>
|
||
|
||
## Command Center
|
||
|
||
The top card on the left holds the stack's identity and primary controls.
|
||
|
||
<Frame>
|
||
<img src="/images/editor/command-center.png" alt="Command Center card with breadcrumb, stack title, running status pill, image and digest, action bar, and the plex container row with live stats" />
|
||
</Frame>
|
||
|
||
| Element | What it shows |
|
||
|---------|--------------|
|
||
| **Breadcrumb** | `<node> › stacks › <stack>` rendered in caps. Confirms which node the stack lives on. |
|
||
| **Stack title** | The stack name in display italic. |
|
||
| **Status pill** | Aggregate state: `running · healthy`, `running · starting`, `running · unhealthy`, plain `running` (no healthcheck defined), or `exited` (any non-running state, including stopped, created, and paused). The dot pulses while the stack is running. |
|
||
| **Image and digest** | First container's image and the leading 12 characters of its image digest, with a copy button for the full SHA. |
|
||
|
||
### Stack action bar
|
||
|
||
The action bar runs every state transition for the whole stack. The primary buttons (**Start**, **Restart**, **Stop**, **Update**) require the `stack:deploy` permission; the **Delete** entry in the kebab dropdown requires the `stack:delete` permission. The bar still appears when only **Delete** is authorised so the operator has a way to remove the stack.
|
||
|
||
| Button | Behavior |
|
||
|--------|----------|
|
||
| **Start** / **Restart** | A single button that becomes **Restart** when at least one container is running and **Start** otherwise. |
|
||
| **Stop** | Stops every container in the stack. Hidden when nothing is running. |
|
||
| **Update** | Pulls fresh images and reapplies the compose file. |
|
||
| **More actions** (`⋮`) | Opens a dropdown with secondary actions. |
|
||
|
||
The kebab dropdown carries:
|
||
|
||
- **Rollback `<timestamp>`** restores the previous deployment using the stored snapshot. Visible only when a backup exists. Skipper or Admiral.
|
||
- **Scan config** runs Trivy against the compose configuration and surfaces misconfigurations inline. Visible only when Trivy is reachable. Admin role required. Skipper or Admiral.
|
||
- **Delete** stops the stack and removes its compose directory. Requires the `stack:delete` permission.
|
||
|
||
## Containers list
|
||
|
||
Below the action bar, the **CONTAINERS** section lists every container the stack defines. Each row carries a status badge, identity, port mapping, action buttons, and live stats.
|
||
|
||
<Frame>
|
||
<img src="/images/editor/containers-list.png" alt="Container row showing the green check status badge, container name, uptime, port mapping with an inline open link, action buttons, and CPU MEM and NET I/O stats with sparklines" />
|
||
</Frame>
|
||
|
||
| Element | Detail |
|
||
|---------|--------|
|
||
| **Status badge** | `✓` (green, healthy or running), `✗` (red, exited or unhealthy), `…` (yellow, starting). |
|
||
| **Name** | The Docker container name; falls back to the first 12 characters of the container ID. |
|
||
| **Uptime / state** | `up 2h 15m` for running containers, the raw state for everything else. |
|
||
| **Healthcheck label** | `healthcheck passing`, `healthcheck failing`, or `healthcheck starting`, only when a healthcheck is defined. |
|
||
| **Port mapping** | The first detected web-UI port, formatted `host → container/proto`, with an inline **open** link that launches `http://<node-host>:<host-port>` in a new tab. |
|
||
| **Action buttons** | **View logs**, **Open bash shell** (admin only), **Service actions**. |
|
||
| **Live stats** | CPU, memory, and net I/O with rolling sparklines. Only rendered while the container is running. Stats refresh on the same 1500 ms cadence as the dashboard. |
|
||
|
||
### Service actions
|
||
|
||
When the container has a compose service name attached, an extra `⋮` button appears at the right of the row. It opens **Restart service**, **Stop service**, or **Start service** depending on the current state. Service actions affect a single service; for full-stack operations use the action bar above.
|
||
|
||
## Anatomy panel
|
||
|
||
The right column shows the **Anatomy panel** by default: a read-only summary of the compose file with a tab for the stack's activity timeline.
|
||
|
||
The header strip carries two tabs (**Anatomy** and **Activity**) plus shortcuts to open the **files** tab and enter **edit** mode. The shortcuts belong to the strip itself and remain available regardless of which tab is active.
|
||
|
||
The Anatomy tab lists:
|
||
|
||
- **services** as chips
|
||
- **ports** in `host → container/proto` rows, grouped by service when the stack defines more than one
|
||
- **volumes** in `host → container` rows
|
||
- **restart** policy
|
||
- **env_file** paths and a count of variables defined in each
|
||
- **network** and its driver
|
||
- **source** with `git · <host>/<repo>#<branch>` when the stack is linked to a Git repository, or `local` when it is not. Clicking the row opens the Git source dialog. A pulsing brand-color dot means an upstream change is queued.
|
||
|
||
When an image update is available, an inline banner appears at the top of the panel. Its tone follows the version-bump severity: `safe to apply` (patch), `review recommended` (minor), `breaking changes possible` (major), or `review required` when the bump cannot be classified. The banner has an inline **apply** button that runs the same operation as the action bar's **Update**; it is hidden for roles that lack the `stack:edit` permission and when the bump is flagged as blocked.
|
||
|
||
The **Activity** tab streams every operational event scoped to this stack. See [Stack Activity](/features/stack-activity) for the full event catalog and attribution rules.
|
||
|
||
## Editor mode
|
||
|
||
Clicking **edit** in the Anatomy strip swaps the right column for the Monaco editor card.
|
||
|
||
<Frame>
|
||
<img src="/images/editor/editor-edit-mode.png" alt="Editor in edit mode with the compose.yaml tab selected, the Git Source button, the Save and Deploy split button, and the close button visible" />
|
||
</Frame>
|
||
|
||
The editor card has three tabs:
|
||
|
||
| Tab | Purpose |
|
||
|-----|---------|
|
||
| `compose.yaml` | YAML editor with syntax highlighting. Always available. |
|
||
| `.env` | Plaintext editor for the discovered env file. Disabled when the stack has no env file. |
|
||
| **Files** | Browseable directory tree for the stack folder. See the dedicated [Stack File Explorer](/features/stack-file-explorer) page for permissions, upload caps, and protected-file behavior. |
|
||
|
||
Above the editor area, the toolbar carries:
|
||
|
||
- **Git Source** opens the Git source dialog. A pulsing brand-color dot appears next to it when an upstream change is waiting to be applied.
|
||
- **Edit** (when read-only) flips the editor into write mode. Replaced by the save split-button while editing.
|
||
- **Close editor** (`X`) returns the right column to the Anatomy panel.
|
||
|
||
When you switch to the `.env` tab and the stack defines more than one env file, a dropdown appears next to the tab strip so you can pick which file to edit. Sencho discovers env files from the `env_file:` entries in `compose.yaml`; if none are declared, it falls back to a `.env` in the stack directory.
|
||
|
||
The `.env` editor renders a teal banner above the textarea reminding you that variables defined there are available for substitution in `compose.yaml` (`${VAR}`), and that passing them into containers requires an `env_file:` entry on the service.
|
||
|
||
### Save options
|
||
|
||
In edit mode the toolbar shows a split button. The primary action is **Save & Deploy**; the dropdown chevron reveals two more.
|
||
|
||
| Action | Effect |
|
||
|--------|--------|
|
||
| **Save & Deploy** | Writes the file to disk, then runs `docker compose up -d` to apply changes. |
|
||
| **Save Only** | Writes the file to disk without restarting any containers. Changes take effect on the next deploy. |
|
||
| **Discard Changes** | Reverts the editor to the last saved version. Unsaved edits are lost. |
|
||
|
||
The same controls apply to the `compose.yaml` and `.env` editors.
|
||
|
||
## Diff preview before save
|
||
|
||
When **Diff preview before save** is enabled in **Settings → Appearance**, clicking **Save & Deploy** or **Save Only** opens a side-by-side diff modal before anything is written to disk. The left pane is the on-disk content; the right pane is your unsaved edits with additions highlighted in green. The footer reads `ON DISK → UNSAVED` so the panes are unambiguous.
|
||
|
||
<Frame>
|
||
<img src="/images/compose-diff-preview/diff-modal.png" alt="Diff preview modal showing side-by-side YAML diff with the unsaved version on the right and an ON DISK to UNSAVED legend in the footer" />
|
||
</Frame>
|
||
|
||
Review the diff, then:
|
||
|
||
- Click the primary button (**Save & deploy** when triggered from **Save & Deploy**, or **Save** when triggered from **Save Only**) to confirm and write the changes.
|
||
- Click **Cancel** to return to the editor without saving.
|
||
|
||
If there are no unsaved changes the modal is skipped and the save proceeds directly. The toggle is off by default and stored per browser, so each device remembers its own setting.
|
||
|
||
## Logs
|
||
|
||
Below the Command Center the left column reserves the rest of its height for the **Logs** stream. Two modes are available, toggled by the buttons at the top right of the section.
|
||
|
||
| Mode | What it shows |
|
||
|------|--------------|
|
||
| **Structured** | Parses each line for an ISO 8601 timestamp and severity (info, warn, err) and renders rows with filter chips (`all`, `info`, `warn`, `err`) and a counter on the active level. Strips ANSI control codes and auto-follows new lines while you stay at the bottom; scrolling up reveals a **resume follow** button. The buffer is capped at 10,000 lines and the **Download logs** button writes the current buffer to a `.txt` file. |
|
||
| **Raw terminal** | A full xterm.js terminal that streams the combined container output verbatim with ANSI color preserved. Press `Ctrl+F` to open the inline find bar. The scrollback is 10,000 lines and a download button is available in the toolbar. |
|
||
|
||
Both modes connect to the same WebSocket and switch instantly without losing the stream.
|
||
|
||
## Log viewer
|
||
|
||
The **View logs** button on a container row opens a dedicated modal that streams output from a single container in real time using Server-Sent Events. Logs auto-scroll to the bottom as new lines arrive. Close the modal to stop the stream.
|
||
|
||
## Container exec (bash session)
|
||
|
||
The **Open bash shell** icon button opens an interactive shell inside a single running container, equivalent to `docker exec -it <id> bash`. The modal uses xterm.js with color, tab completion, and resize handling.
|
||
|
||
<Frame>
|
||
<img src="/images/editor/container-exec-modal.png" alt="Bash session modal connected to the plex container running cat slash etc slash os release with a Connected status pill" />
|
||
</Frame>
|
||
|
||
### Access requirements
|
||
|
||
- **Admin role required.** The button is rendered only for admin users.
|
||
- **Container must be running.** The button is disabled for stopped containers, and the backend rejects exec attempts against non-running containers.
|
||
- **API token scope.** API tokens with the `read-only` or `deploy-only` scope cannot open exec sessions. Only `full-admin` tokens are accepted.
|
||
|
||
### Shell selection
|
||
|
||
Sencho tries `/bin/bash` first and transparently falls back to `/bin/sh` if bash is missing. No user action is needed.
|
||
|
||
<Warning>
|
||
Minimal base images that ship no shell at all (for example `scratch` or fully `distroless`) will not work with container exec.
|
||
</Warning>
|
||
|
||
## Troubleshooting
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="The compose editor is read-only and I can't type">
|
||
You have not entered edit mode yet. Click **edit** in the Anatomy panel header (or the **Edit** button at the top of the editor card) to enable typing. If the **Edit** button is missing entirely, your role lacks the `stack:edit` permission; ask an admin to grant it.
|
||
</Accordion>
|
||
<Accordion title="Save & Deploy is disabled">
|
||
A deploy is already running for this stack. Watch the action bar for the spinning state to clear, then save again.
|
||
</Accordion>
|
||
<Accordion title="The .env tab is greyed out">
|
||
The stack has no env file to edit. Add an `env_file:` entry to a service in `compose.yaml` and save, or create a `.env` file in the stack directory through the **Files** tab.
|
||
</Accordion>
|
||
<Accordion title='"Container is not running" error when opening a bash session'>
|
||
The container stopped between clicking the button and the exec starting. Start the container from the action bar (or the row's **Start service** option) and try again.
|
||
</Accordion>
|
||
<Accordion title='"Failed to start shell" error when opening a bash session'>
|
||
The container image has no shell binary at `/bin/bash` or `/bin/sh`. Use an image that includes a shell, or install one in your Dockerfile.
|
||
</Accordion>
|
||
<Accordion title='Bash session connects but immediately shows "Session ended"'>
|
||
The shell process inside the container exited as soon as it started. Check the container logs (the **View logs** button on the same row) for errors; the container's entrypoint may be overriding the shell, or the container itself may be in a crash loop.
|
||
</Accordion>
|
||
<Accordion title="Bash session is unresponsive">
|
||
The WebSocket dropped silently. Close the modal and reopen it to start a fresh session; the bash modal does not reconnect automatically.
|
||
</Accordion>
|
||
<Accordion title='"Failed to save file" toast appears when I click Save & Deploy'>
|
||
The PUT to write the compose file failed (most often a permission or disk-space issue on the node). Save & Deploy stops at the save step in this case, so no deploy is attempted and your editor still holds the unsaved version. Resolve the underlying error on the node, then retry.
|
||
</Accordion>
|
||
<Accordion title="Switching nodes prompts me to discard unsaved changes">
|
||
The editor blocks a silent loss of in-progress edits. Click **Cancel** to return to the original node with your edits intact; click **Discard** to abandon them and proceed to the other node.
|
||
</Accordion>
|
||
<Accordion title='"Stats unavailable" chip on the container list'>
|
||
The stats WebSocket failed to open, or closed unexpectedly. This usually means the Docker daemon on the node is unreachable. Container status, action buttons, and logs continue to work; only live CPU / memory / network rates pause.
|
||
</Accordion>
|
||
</AccordionGroup>
|