mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 20:00:08 +00:00
Anso
0be479100c
* docs(introduction): rewrite intro page and refresh screenshots
Rewrite the Getting Started introduction to reflect the current product:
adds the Mesh, Blueprints, Pilot, Fleet, Resources concepts up front;
restructures capability sections around Stacks, Fleet (now including
Fleet Actions), Mesh, Blueprints, Monitoring, Resources, Security,
Automation, and Pilot/Remote ops; cross-links every claim to the
matching feature page.
Replaces the dashboard hero shot with a fresh capture against the
redesigned cockpit chrome and adds three inline shots (running stack
with anatomy and logs, fleet command deck, resources hub with
reclaim header). All screenshots taken at 1920x900, dark theme,
with node names, usernames, IPs, and home paths neutralized.
Drops outdated claims: stale "190+ templates" count, the
"viewer accounts" RBAC summary, and the "atomic" deployment label
that did not match the actual rollback mechanism.
* docs(introduction): add Federation and Fleet Secrets
Federation has shipped (Admiral) with cordon and pin policy as
operator overrides on the blueprint reconciler. Fleet Secrets is
landing as a Skipper+ tab for versioned env-var bundles encrypted
at rest, with diff preview and target push.
Mirror those in the Run-one-machine-or-many bullet list and in the
Tiers paragraph so the introduction matches the current product.
* docs(introduction): re-shoot screenshots against v0.72.0 production
Re-capture all four introduction screenshots from the upgraded
production node so the fleet view shows the current full tab strip
(Overview / Snapshots / Status / Deployments / Traffic / Federation
/ Fleet Actions / Secrets) instead of the older Overview / Snapshots
/ Status only. Same 1920x900 dark-theme capture and the same PII
scrub applied (node names, usernames, IPs, home paths neutralized).
* docs(quickstart): rewrite around v0.72.0 cockpit and add screenshots
Replaces the bare install snippet with a five-minute walkthrough that
matches the redesigned UI. Leads with a docker-compose.yml block (the
bare docker run command is collapsed in an Accordion), keeps the 1:1
path rule, and adds two new sections that show the user what happens
on first boot.
Adds two screenshots at 1920x900 dark theme:
- setup-cold-start.png: the Cold start card with Username, Password,
Confirm password fields, and the Initialize console button.
- dashboard.png: the post-sign-in dashboard captured against v0.72.0
with the full top nav (Home, Fleet, Resources, App Store, Logs,
Auto-Update, Console, Audit, Schedules) and the populated Stack
health table sorted by load.
Where-to-next now uses CardGroup cols=2 to match the introduction
page's pattern.
* docs(configuration): align env var reference with current backend
Bring docs/getting-started/configuration.mdx up to date with the
v0.72.0 backend:
- Remove PORT from the optional env vars table. The listen port is
hardcoded to 1852 in backend/src/helpers/constants.ts and is never
read from the environment. Replace it with a Listen port section
that explains the fixed port and host-port remapping.
- Document API_RATE_LIMIT (default 200) and API_POLLING_RATE_LIMIT
(default 300), both applied in production only.
- Note the /app/compose fallback default for COMPOSE_DIR while still
pointing readers at the 1:1 path rule.
- Point the SSO env var section at the new SSO Quickstart page and
keep the SSO feature reference as the deeper dive.
- Tighten First boot and cross-link to Quickstart so the screenshot
is not duplicated.
- Add a Where to next CardGroup matching the refreshed Introduction
and Quickstart pages.
Drop stale PORT=1852 and JWT_SECRET=your-secure-jwt-secret-here
lines from .env.example so the example no longer contradicts the
docs (PORT is hardcoded, JWT_SECRET is auto-generated and persisted
to the database during initial setup).
* docs(configuration): replace em-dash-substitute hyphens in prose
Three sentences used ` - ` (space-hyphen-space) as an em-dash
substitute. Replaced with the punctuation that fits each case:
- "How Sencho organizes your compose directory": semicolon between
the two related clauses.
- Data directory Warning: parentheses around the parenthetical
insertion.
- 1:1 path rule explanation: comma before the contrastive clause.
Heading slugs and YAML code-block comments are unchanged.
* docs(sso): refresh setup guide and drop misleading "one-click" wording
Brings the SSO Setup Guide in line with how SSO actually works in the
current build, and corrects misleading copy across both SSO docs pages.
- Setup Guide: explains the env-var-seeds-once / DB-is-authoritative
config model up front, replacing per-section "Restart Sencho"
wording that implied a restart was always required.
- Setup Guide: promotes the per-provider Test Connection button out
of the LDAP-only paragraph into a generic intro callout, and adds
a self-signed LDAPS tip.
- Setup Guide: notes that all OIDC providers accept a *_DISPLAY_NAME
override for the login button label, and adds a commented LDAP TLS
toggle to the full compose example.
- Setup Guide: adds two screenshots of the redesigned Settings > SSO
panel (overview + LDAP card expanded with form).
- Both pages: replaces "one-click presets" / "one-click configuration"
with "preset providers". The Skipper-tier presets still require an
OAuth app provisioned in the provider's console; what they actually
buy is provider-aware defaults and a branded login button. The old
wording overpromised.
* docs(features-overview): regroup catalog and add 17 missing features
Restructure the Features Overview into the same six groups the docs
sidebar uses (Stacks & Deployments, Observability, Fleet & Multi-Node,
Security & Identity, Automation, Platform) plus a short Reference tail.
Add catalog entries for 17 shipped features that the previous overview
never mentioned: Stack Activity, Stack File Explorer, Deploy Progress,
Deploy Enforcement, Blueprints, Git Sources, Global Search, Pilot Agent,
Sencho Mesh, Fleet Federation, Fleet Actions, Fleet Sync, Fleet Secrets,
Two-Factor Authentication, CVE Suppressions, Auto-Heal Policies, Stack
Sidebar.
Fix two factual inaccuracies:
- Fleet View blurb wrongly gated search, sort, filter, and stack
drill-down behind Skipper. The deep-dive is explicit that those are
available on every tier; only the bulk Update All action inside the
Node Updates modal is paid.
- Auto-update entry was titled and described as a scheduling system.
The deep-dive page is the Auto-Update Readiness board (risk tags,
changelog previews, rollback targets); the scheduler lives under
Scheduled Operations.
Add three hero screenshots captured from production at 1920x900,
illustrating the redesigned cockpit visual language: Home dashboard,
stack anatomy, and fleet topology.
* docs(stack-management): refresh page around v0.72.0 cockpit and add screenshots
Updates the Stack Management page to match the current UI: sidebar with
filter chips and label groups, bulk mode, restructured kebab menu,
two-tab anatomy panel, and three-source New stack dialog (Empty, From
Git, From Docker Run).
Adds sections for Filter chips, Pinned and label groups, and Bulk mode.
Restructures the Stack context menu around the inspect, organize,
lifecycle, and destructive groups with their keyboard shortcuts.
Documents the From Git tab and cross-links Git Sources for the full
sync flow.
Replaces every existing screenshot with fresh captures from the current
UI and adds eight new captures for the new sections. Cross-links Stack
Activity, Stack Labels, Stack File Explorer, Compose Editor, Atomic
Deployments, Scheduled Operations, Auto-Heal Policies, Auto-Update
Policies, and Alerts and Notifications for features documented on
their own pages.
* docs(stack-activity): refresh page around v1 cockpit and recapture screenshots
Realign the page with the current Anatomy panel tab strip and the
StackActivityTimeline component:
- Frame the Activity tab as a sibling of Anatomy under the right-hand
panel, with files/edit actions belonging to the strip.
- Expand the category guidance: list the five iconized categories and
call out that other stack-scoped notifications (deploy failure,
available image updates, auto-heal triggers, monitor alerts, scan
findings) flow into the timeline with a generic icon.
- Tighten the actor-attribution rule to match the component: omitted
for events without an actor and for system-driven events.
- Add the day-format example to the relative-time row.
- Recapture both screenshots from a populated stack (Today + Yesterday
+ Earlier with three distinct icons) and an empty stack.
- Convert troubleshooting blurbs to H3 for anchor links and consistency
with the v1-refresh sibling pages.
* docs(stack-activity): wrap troubleshooting entries in Accordion blocks
Match the foldable troubleshooting pattern established by
docs/features/deploy-progress.mdx so the page stays compact and
readers can scan to their issue. This is the canonical formatting
for the /features section's troubleshooting blurbs going forward.
* docs(editor): refresh page around v1 cockpit and recapture screenshots
Rewrites the page around the dual-mode right panel (Anatomy by default,
Monaco when the user clicks edit), the redesigned Command Center action
bar, the new container row layout with status badges and live stats, the
Structured / Raw terminal logs toggle, the Git Source toolbar button, and
the opt-in diff preview. Drops the obsolete persistent embedded terminal
section. Preserves the #diff-preview-before-save and #log-viewer anchors
referenced from settings.mdx and global-observability.mdx. Replaces
editor-overview.png and container-exec-modal.png with fresh captures
against v0.72.0 production at 1920x900 dark theme; renames container
-actions.png to containers-list.png; adds command-center.png and
editor-edit-mode.png. PII scrubbed (host paths normalized) and the
compose-diff-preview/diff-modal.png shared asset is left untouched after
visual diff against the live UI showed no chrome change.
* docs(features): wrap troubleshooting accordions in AccordionGroup
Wraps the loose <Accordion> blocks in editor.mdx and stack-activity.mdx
in a single <AccordionGroup> to match the troubleshooting design used
by fleet-federation.mdx. Structural only; no content changes.
* docs(stack-file-explorer): refresh page around v1 explorer and add screenshots
Full rewrite to match the live two-pane Files tab. Replaces the false
'Edit' toolbar flow with the read-only chip + always-on Save model,
fixes the protected-files list (5 names) and dedicated-tab redirect
list (3 names), drops the fabricated 100 MB download cap, and corrects
the upload claim to single file at a time.
Adds sections for New File, Rename, Permissions, the type-to-confirm
protected-file delete flow, the non-empty folder delete confirmation,
the 500-entry tree display cap, and the symlink rendering. Restructures
troubleshooting around <AccordionGroup> + <Accordion> to match
fleet-federation.mdx, and adds two new entries (display cap, 403 on
Community admin write).
Ships nine screenshots captured against v0.72.0 production at 1920x900
in dark theme: overview, two-pane layout, protected-tree-marker,
viewer-edit-mode, new-file-dialog, context-menu-folder, context-menu-file,
permissions-dialog, delete-protected-confirm.
* docs(deploy-progress): rewrite around current modal + capture v1 screenshots
Aligns the page with the v0.72.0 implementation and standardizes the
troubleshooting layout with the rest of the docs refresh.
Setting and gating
- Renames the Settings field to "Deploy progress modal" and quotes the
current helper text verbatim. Documents that the toggle is off by
default, lives under Settings > Appearance > Display, is stored in
localStorage, and syncs across tabs in the same browser.
Modal anatomy
- Names every visible UI string: header verbs, status indicator (with
the "closes in <n>s" countdown that was previously undocumented),
empty-body strings, footer toggle that flips between "Raw output" and
"Hide raw", and the destructive border on ERR rows vs the softer warn
tint on WARN rows.
- Replaces the vague "after a few seconds" with the actual 4-second
auto-close timer; documents hover-to-pause and the
leave-hover-restarts-the-countdown behavior.
- Documents the truncated error message in the failed-state header and
the manual close-only requirement.
- Notes that the pill is portal-mounted and survives navigation.
Stage badges
- Keeps the 9-badge table but adds an honest note that most lines render
as LOG because the badges are gated on Compose's "[+]" progress
prefix, which Compose only emits in TTY mode and Sencho spawns it
without one.
Entry points
- Splits the supported actions into the four that produce a populated
structured-log body (Deploy, Update, Install, Git Apply) and the two
that bypass compose and finish with 0 lines (Restart, Stop). Drops the
"Down" claim from the user-facing list since no UI control currently
triggers it; mentions the down route as an automation surface only.
Troubleshooting
- Wraps the existing accordions in an <AccordionGroup> matching the
pattern used by the editor and stack-activity refreshes. Adds two new
entries: one explaining the Restart/Stop "0 lines" outcome, one
explaining the LOG-everywhere case for non-TTY compose output.
Screenshots (six PNGs in docs/images/deploy-progress/, 1920x900, dark
theme, captured against the upgraded production node)
- setting-toggle.png: the Display section with the toggle enabled.
- modal-streaming.png: a real update in flight at 19s, 554 lines.
- modal-succeeded.png: succeeded state with the live closes-in
countdown visible.
- modal-raw-output.png: structured rows with the Raw output panel
expanded beneath.
- pill.png: minimized pill anchored bottom-center on a stack editor
view.
- modal-failed.png: failed state with the truncated error in the
header and ERR rows highlighted.
* docs(resources): refresh Resources Hub page for v1 redesign and feature additions
Rewrite the page to match the shipping UI and replace stale screenshots
with fresh captures of the redesigned chrome.
- Document the admin-only Reclaim hero and clarify the per-tile Sencho-only
vs. All Docker (includes external) split in Quick Clean.
- Add coverage of the Scan history toolbar button and the per-row severity
badge plus shield-icon scan dropdown in the Images tab; cross-link to the
vulnerability scanning page.
- Correct the Volumes column list (no Size column; size lives on the Largest
5 landing card) and call out admin gates on browse and delete.
- Spell out the List/Topology view-mode toggle and that Create Network is
admin-only and List-mode only.
- Rewrite the Unmanaged tab section around the project-grouped layout, the
Select all + Purge Selected (N) admin-only multi-select, and the empty
state copy.
- Replace screenshots: resources-reclaim, networks-list, create-network,
network-inspect, network-topology, network-topology-toggle. Add fresh
resources-volumes-tab and resources-unmanaged-tab captures.
* docs(app-store): refresh page around v1 deploy sheet, scan integration, and registry settings
Rewrites the App Store reference to match the current cockpit:
- Documents the weekly-rotated featured banner picked from the top-5 by GitHub stars and the star-descending grid sort.
- Adds the deploy-sheet structure (breadcrumb, meta line, About panel with Read more) and splits the Advanced tab into Ports, Volumes, Environment variables, Custom variables, and Security subsections.
- Documents the Trivy-gated Security checkbox, atomic vs non-atomic deploys by tier, and the rollback semantics driven by error class.
- Adds a Watching the deploy section linking to the deploy-progress modal.
- Rewrites the Custom registry section against the new two-panel settings layout (Default + Custom) with the URL validation rule and the using default / using custom hint.
- Adds a four-entry Accordion troubleshooting block in the house style.
- Replaces three screenshots and adds two (Advanced tab, Settings registry panel) captured against the production node.
Permissions wording aligns with current backend (admin only); the broader stack:create gate will land in a follow-up fix branch.
* docs(app-store): describe inline port-conflict messaging on deploy sheet
Update the deploy-sheet section to match the visible port-conflict
behavior: the Essentials tab surfaces a Port-conflict warning that
replaces the defaults hint when any default port is already bound, and
the Advanced tab shows an inline "in use by {stack}" message next to
the container port instead of a hover-only tooltip. Refresh the
screenshot alt-text and the troubleshooting Accordion to match.
* docs(app-store): align permissions note with stack:create gate
Pairs with the backend gate swap in fix/templates-deploy-rbac (#986)
which moves POST /api/templates/deploy from requireAdmin to
requirePermission('stack:create'). Updates the Note block under
'Watching the deploy' so the docs match the new behavior: admin and
node-admin can deploy templates from the App Store; viewer, deployer,
and auditor cannot.
201 lines
13 KiB
Plaintext
201 lines
13 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. It is hidden for roles without the `stack:deploy` permission.
|
||
|
||
| 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. Always available to the deploy role.
|
||
|
||
## 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>
|
||
</AccordionGroup>
|