Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat: add optional walkthrough guides

Juan Denisb44f2439f9f1
diff --git a/frontend/src/components/WalkthroughHub.jsx b/frontend/src/components/WalkthroughHub.jsx
index 8cdf1ecf..86d21757 100644
--- a/frontend/src/components/WalkthroughHub.jsx
+++ b/frontend/src/components/WalkthroughHub.jsx
@@ -1,10 +1,15 @@
import {
+ Archive,
BookOpenCheck,
Boxes,
Check,
Clock3,
+ Globe2,
+ Radar,
+ Server,
ShieldCheck,
Square,
+ UserPlus,
} from 'lucide-react';
import { useEffect, useMemo, useState } from 'react';
import { useNavigate } from 'react-router-dom';
@@ -17,7 +22,15 @@ import { getWalkthroughProgress } from '../services/walkthroughState';
import Pill from './ds/Pill';
import ShellDockTabs from './ShellDockTabs';
-const ICONS = { service: Boxes, security: ShieldCheck };
+const ICONS = {
+ service: Boxes,
+ security: ShieldCheck,
+ domain: Globe2,
+ monitor: Radar,
+ backup: Archive,
+ server: Server,
+ team: UserPlus,
+};
// Recipes console — the prototype's guided-walkthrough surface: a library of
// recipe cards, and for the running recipe a split view with the step rail on
@@ -25,9 +38,17 @@ const ICONS = { service: Boxes, security: ShieldCheck };
// (auto-completion via routes/signals/checks, saved progress) is untouched;
// only the shell changed from a floating card stack to the docked console.
function RecipeLibrary({ walkthroughs, state, onStart, onStop, t }) {
+ const [showMore, setShowMore] = useState(false);
+ const primary = walkthroughs.filter((walkthrough) => !walkthrough.secondary);
+ const secondary = walkthroughs.filter((walkthrough) => walkthrough.secondary);
+ const visible = showMore ? [...primary, ...secondary] : [
+ ...primary,
+ ...secondary.filter((walkthrough) => state.progress?.[walkthrough.id]?.status === 'active'),
+ ];
+
return (
<div className="shell-recipes__grid">
- {walkthroughs.map((walkthrough) => {
+ {visible.map((walkthrough) => {
const Icon = ICONS[walkthrough.icon] || BookOpenCheck;
const progress = getWalkthroughProgress(state, walkthrough);
const status = progress.entry?.status;
@@ -65,6 +86,26 @@ function RecipeLibrary({ walkthroughs, state, onStart, onStop, t }) {
</div>
);
})}
+ {secondary.length > 0 && (
+ <button
+ type="button"
+ className="shell-recipes__more"
+ onClick={() => setShowMore((current) => !current)}
+ aria-expanded={showMore}
+ >
+ <BookOpenCheck size={15} aria-hidden="true" />
+ <span>
+ <strong>{showMore
+ ? t('app.walkthroughs.hideMoreGuides', 'Show fewer guides')
+ : t('app.walkthroughs.moreGuides', 'More walkthroughs')}
+ </strong>
+ <small>{showMore
+ ? t('app.walkthroughs.keepLibraryFocused', 'Keep the library focused on the essentials')
+ : t('app.walkthroughs.moreGuidesCount', '{{count}} optional guides', { count: secondary.length })}
+ </small>
+ </span>
+ </button>
+ )}
</div>
);
}
@@ -203,9 +244,11 @@ export default function WalkthroughHub() {
<h3 className="shell-recipes__step-heading">{viewStep.title}</h3>
<p className="shell-recipes__body">{viewStep.description}</p>
<footer className="shell-recipes__foot">
- <Button type="button" size="sm" onClick={runAction} disabled={checking}>
- {checking ? t('common.checking', 'Checking…') : viewStep.action}
- </Button>
+ {(viewStep.path || viewStep.check) && (
+ <Button type="button" size="sm" onClick={runAction} disabled={checking}>
+ {checking ? t('common.checking', 'Checking…') : viewStep.action}
+ </Button>
+ )}
{!viewStep.check && !isDone && (
<Button type="button" variant="outline" size="sm" onClick={markDoneNext}>
{isLast
diff --git a/frontend/src/components/service-detail/SettingsTab.jsx b/frontend/src/components/service-detail/SettingsTab.jsx
index 76958831..a23e894b 100644
--- a/frontend/src/components/service-detail/SettingsTab.jsx
+++ b/frontend/src/components/service-detail/SettingsTab.jsx
@@ -461,6 +461,12 @@ const DomainSslPanel = ({ app, domains, primaryDomain, onUpdate }) => {
// no copy — which is the case the Domains modal shares.
const [email, setEmail] = useState(() => localStorage.getItem('serverkit_ssl_email') || '');
+ useEffect(() => {
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'service-domain-settings-opened' },
+ }));
+ }, []);
+
useEffect(() => {
if (email) return undefined;
let cancelled = false;
@@ -532,6 +538,9 @@ const DomainSslPanel = ({ app, domains, primaryDomain, onUpdate }) => {
ssl_enabled: false,
});
toast.success(res.message || t('app.settingsTab.domainAttached', 'Domain attached'));
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'service-domain-attached' },
+ }));
setDomainInput('');
onUpdate();
} catch (err) {
@@ -608,6 +617,9 @@ const DomainSslPanel = ({ app, domains, primaryDomain, onUpdate }) => {
}
const updated = await api.getSSLHealth(primaryDomain);
setHealth(updated);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'service-ssl-enabled' },
+ }));
onUpdate();
} else {
toast.error(res.error || t('app.settingsTab.certificateRequestFailed', 'Certificate request failed'));
@@ -630,7 +642,7 @@ const DomainSslPanel = ({ app, domains, primaryDomain, onUpdate }) => {
);
return (
- <div className="card settings-section svc-domain-panel">
+ <div className="card settings-section svc-domain-panel" data-walkthrough="service-domain-panel">
<div className="app-info-grid">
<div className="app-info-item">
<span className="app-info-label">{t('app.settingsTab.primaryDomain', 'Primary Domain')}</span>
@@ -672,7 +684,7 @@ const DomainSslPanel = ({ app, domains, primaryDomain, onUpdate }) => {
{!primaryDomain ? (
<div className="ssl-guide">
<p className="hint">{t('app.settingsTab.noDomainIsAttachedToThis', 'No domain is attached to this service yet. Add one to expose it on a public URL and enable HTTPS.')}</p>
- <form className="ssl-inline-attach" onSubmit={handleAttachDomain}>
+ <form className="ssl-inline-attach" onSubmit={handleAttachDomain} data-walkthrough="service-domain-attach">
{contextLoading ? (
<p className="hint">{t('app.settingsTab.loadingAvailableDomains', 'Loading available domains…')}</p>
) : (
@@ -742,7 +754,11 @@ const DomainSslPanel = ({ app, domains, primaryDomain, onUpdate }) => {
</>
)}
<div className="app-detail-actions">
- <Button onClick={handleEnableSSL} disabled={issuing || (!issued && (!email.trim() || !email.includes('@')))}>
+ <Button
+ onClick={handleEnableSSL}
+ disabled={issuing || (!issued && (!email.trim() || !email.includes('@')))}
+ data-walkthrough="service-enable-ssl"
+ >
{issued ? <Shield size={14} /> : <Lock size={14} />}
{issuing ? 'Requesting...' : issued ? 'Re-issue Certificate' : 'Enable SSL'}
</Button>
diff --git a/frontend/src/components/settings/InvitationsTab.jsx b/frontend/src/components/settings/InvitationsTab.jsx
index 0a2c8f2c..cf01d96b 100644
--- a/frontend/src/components/settings/InvitationsTab.jsx
+++ b/frontend/src/components/settings/InvitationsTab.jsx
@@ -13,6 +13,7 @@ import { useColumnVisibility } from '@/hooks/useColumnVisibility';
import EmptyState from '../EmptyState';
import { copyToClipboard } from '@/utils/clipboard';
import { useTranslation } from 'react-i18next';
+import useFocusParam from '@/hooks/useFocusParam';
// A pending invite whose window has closed still carries status 'pending' in
// the database — the row only becomes 'expired' on screen. One accessor for
@@ -72,6 +73,10 @@ const InvitationsTab = () => {
const [showInviteModal, setShowInviteModal] = useState(false);
const [copied, setCopied] = useState(null);
+ useFocusParam('create', (target) => {
+ if (target === 'invitation') setShowInviteModal(true);
+ });
+
// Lifted out of <DataTable> so a saved view can capture them. The storage
// keys are the ones DataTable derived from storageKey="serverkit-table-
// settings-invitations", so a persisted sort or hidden column survives.
@@ -274,7 +279,7 @@ const InvitationsTab = () => {
});
return (
- <div className="invitations-section">
+ <div className="invitations-section" data-walkthrough="invitations-section">
{/* The view name replaces the old "Invitations" h4: it names the
section AND says which slice of it you are looking at. */}
<GridViewPicker
diff --git a/frontend/src/components/settings/InviteModal.jsx b/frontend/src/components/settings/InviteModal.jsx
index 0507f132..f82b330e 100644
--- a/frontend/src/components/settings/InviteModal.jsx
+++ b/frontend/src/components/settings/InviteModal.jsx
@@ -55,6 +55,9 @@ const InviteModal = ({ onClose, onCreated }) => {
const response = await api.createInvitation(data);
setResult(response);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'invitation-created' },
+ }));
if (onCreated) onCreated();
} catch (err) {
setError(err.message || 'Failed to create invitation');
@@ -66,6 +69,9 @@ const InviteModal = ({ onClose, onCreated }) => {
async function copyLink() {
if (result?.invite_url && await copyToClipboard(result.invite_url)) {
setCopied(true);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'invitation-link-copied' },
+ }));
setTimeout(() => setCopied(false), 2000);
}
}
@@ -75,7 +81,7 @@ const InviteModal = ({ onClose, onCreated }) => {
return (
<Modal open={true} onClose={onClose} title={t('app.inviteModal.invitationCreated', 'Invitation Created')} size="md">
<p>{t('app.inviteModal.shareThisInvitationLink', 'Share this invitation link:')}</p>
- <div className="invite-link-display">
+ <div className="invite-link-display" data-walkthrough="invite-result">
<code>{result.invite_url}</code>
<Button variant="ghost" size="sm" onClick={copyLink}>
{copied ? 'Copied!' : 'Copy'}
@@ -100,7 +106,7 @@ const InviteModal = ({ onClose, onCreated }) => {
return (
<Modal open={true} onClose={onClose} title={t('app.inviteModal.inviteUser', 'Invite User')} size="md">
- <form onSubmit={handleSubmit}>
+ <form onSubmit={handleSubmit} data-walkthrough="invite-form">
<div className="modal-body">
{error && <div className="error-message">{error}</div>}
@@ -186,7 +192,7 @@ const InviteModal = ({ onClose, onCreated }) => {
<div className="modal-footer">
<Button type="button" variant="ghost" onClick={onClose}>{t('common.actions.cancel', 'Cancel')}</Button>
- <Button type="submit" variant="default" disabled={loading}>
+ <Button type="submit" variant="default" disabled={loading} data-walkthrough="invite-submit">
{loading ? 'Creating...' : 'Create Invitation'}
</Button>
</div>
diff --git a/frontend/src/contexts/WalkthroughContext.jsx b/frontend/src/contexts/WalkthroughContext.jsx
index cf2394f9..0e84eef8 100644
--- a/frontend/src/contexts/WalkthroughContext.jsx
+++ b/frontend/src/contexts/WalkthroughContext.jsx
@@ -54,9 +54,12 @@ export function WalkthroughProvider({ children }) {
const [open, setOpen] = useState(false);
const localizedWalkthroughs = useMemo(() => localizeWalkthroughs(t), [t]);
- const availableWalkthroughs = useMemo(() => localizedWalkthroughs.filter((item) => (
- !item.permission || hasPermission(item.permission.feature, item.permission.level)
- )), [hasPermission, localizedWalkthroughs]);
+ const availableWalkthroughs = useMemo(() => localizedWalkthroughs.filter((item) => {
+ const required = item.permissions || (item.permission ? [item.permission] : []);
+ return required.every((permission) => (
+ hasPermission(permission.feature, permission.level)
+ ));
+ }), [hasPermission, localizedWalkthroughs]);
const activeWalkthrough = localizedWalkthroughs.find(
(walkthrough) => walkthrough.id === state.active_id,
@@ -129,10 +132,10 @@ export function WalkthroughProvider({ children }) {
));
return;
}
- if (!currentStep?.signal) return;
- if (event.detail?.type === currentStep.signal) {
- completeStep(activeWalkthrough.id, currentStep.id);
- }
+ const signaledStep = activeWalkthrough.steps.find(
+ (step) => step.signal === event.detail?.type,
+ );
+ if (signaledStep) completeStep(activeWalkthrough.id, signaledStep.id);
};
window.addEventListener('serverkit:walkthrough-signal', handleSignal);
return () => window.removeEventListener('serverkit:walkthrough-signal', handleSignal);
diff --git a/frontend/src/data/walkthroughs.js b/frontend/src/data/walkthroughs.js
index 0c99859c..16440347 100644
--- a/frontend/src/data/walkthroughs.js
+++ b/frontend/src/data/walkthroughs.js
@@ -114,6 +114,308 @@ export const WALKTHROUGHS = Object.freeze([
},
],
},
+ {
+ id: 'publish-service',
+ icon: 'domain',
+ tone: 'green',
+ secondary: true,
+ titleKey: 'app.walkthroughs.publishServiceTitle',
+ title: 'Publish a service securely',
+ descriptionKey: 'app.walkthroughs.publishServiceDescription',
+ description: 'Attach a public domain, confirm DNS, and enable HTTPS.',
+ durationKey: 'app.walkthroughs.sixMinutes',
+ duration: 'About 6 minutes',
+ permissions: [
+ { feature: 'applications', level: 'write' },
+ { feature: 'domains', level: 'write' },
+ ],
+ steps: [
+ {
+ id: 'open-domain-settings',
+ titleKey: 'app.walkthroughs.openDomainSettings',
+ title: 'Open a service’s domain settings',
+ descriptionKey: 'app.walkthroughs.openDomainSettingsDescription',
+ description: 'Choose the service you want to publish, then open Settings → Domain & SSL.',
+ path: '/services',
+ signal: 'service-domain-settings-opened',
+ target: '[data-walkthrough="service-domain-panel"]',
+ actionKey: 'app.walkthroughs.chooseService',
+ action: 'Choose a service',
+ },
+ {
+ id: 'attach-domain',
+ titleKey: 'app.walkthroughs.attachPublicDomain',
+ title: 'Attach a public domain',
+ descriptionKey: 'app.walkthroughs.attachPublicDomainDescription',
+ description: 'Enter a domain you control and attach it to the service.',
+ signal: 'service-domain-attached',
+ target: '[data-walkthrough="service-domain-attach"]',
+ actionKey: 'app.walkthroughs.attachDomain',
+ action: 'Attach domain',
+ },
+ {
+ id: 'confirm-dns',
+ titleKey: 'app.walkthroughs.confirmDns',
+ title: 'Confirm the DNS record',
+ descriptionKey: 'app.walkthroughs.confirmDnsDescription',
+ description: 'Point the domain at this server and wait until public DNS resolves to the correct address.',
+ target: '[data-walkthrough="service-domain-panel"]',
+ actionKey: 'app.walkthroughs.reviewDns',
+ action: 'Review DNS',
+ },
+ {
+ id: 'enable-https',
+ titleKey: 'app.walkthroughs.enableHttps',
+ title: 'Enable HTTPS',
+ descriptionKey: 'app.walkthroughs.enableHttpsDescription',
+ description: 'Request a Let’s Encrypt certificate. The guide completes after ServerKit verifies it.',
+ signal: 'service-ssl-enabled',
+ target: '[data-walkthrough="service-enable-ssl"]',
+ actionKey: 'app.walkthroughs.enableHttpsAction',
+ action: 'Enable HTTPS',
+ },
+ ],
+ },
+ {
+ id: 'monitor-service',
+ icon: 'monitor',
+ tone: 'cyan',
+ secondary: true,
+ titleKey: 'app.walkthroughs.monitorServiceTitle',
+ title: 'Monitor your first service',
+ descriptionKey: 'app.walkthroughs.monitorServiceDescription',
+ description: 'Create an uptime check and run its first probe.',
+ durationKey: 'app.walkthroughs.fourMinutes',
+ duration: 'About 4 minutes',
+ permission: { feature: 'monitoring', level: 'write' },
+ steps: [
+ {
+ id: 'open-monitor-form',
+ titleKey: 'app.walkthroughs.openMonitorForm',
+ title: 'Open the monitor form',
+ descriptionKey: 'app.walkthroughs.openMonitorFormDescription',
+ description: 'Start a new uptime monitor from the Monitoring area.',
+ path: '/monitoring/monitors?focus=create:monitor',
+ route: '/monitoring/monitors',
+ target: '[data-walkthrough="monitor-form"]',
+ actionKey: 'app.walkthroughs.addMonitor',
+ action: 'Add monitor',
+ },
+ {
+ id: 'configure-monitor',
+ titleKey: 'app.walkthroughs.configureMonitor',
+ title: 'Choose what success means',
+ descriptionKey: 'app.walkthroughs.configureMonitorDescription',
+ description: 'Set the URL, check type, interval, timeout, and expected response.',
+ target: '[data-walkthrough="monitor-form"]',
+ actionKey: 'app.walkthroughs.configureCheck',
+ action: 'Configure check',
+ },
+ {
+ id: 'create-monitor',
+ titleKey: 'app.walkthroughs.createMonitor',
+ title: 'Create the monitor',
+ descriptionKey: 'app.walkthroughs.createMonitorDescription',
+ description: 'Save the check. ServerKit will begin probing it on the selected interval.',
+ signal: 'monitor-created',
+ target: '[data-walkthrough="monitor-submit"]',
+ actionKey: 'app.walkthroughs.saveMonitor',
+ action: 'Save monitor',
+ },
+ {
+ id: 'run-first-check',
+ titleKey: 'app.walkthroughs.runFirstCheck',
+ title: 'Run the first check',
+ descriptionKey: 'app.walkthroughs.runFirstCheckDescription',
+ description: 'Use Check now on the new row and review the response status and timing.',
+ path: '/monitoring/monitors',
+ signal: 'monitor-check-completed',
+ target: '[data-walkthrough="monitor-check-now"]',
+ actionKey: 'app.walkthroughs.reviewMonitor',
+ action: 'Review monitor',
+ },
+ ],
+ },
+ {
+ id: 'protect-with-backups',
+ icon: 'backup',
+ tone: 'amber',
+ secondary: true,
+ titleKey: 'app.walkthroughs.backupTitle',
+ title: 'Protect data with backups',
+ descriptionKey: 'app.walkthroughs.backupDescription',
+ description: 'Schedule recurring protection and create the first snapshot.',
+ durationKey: 'app.walkthroughs.fiveMinutes',
+ duration: 'About 5 minutes',
+ permission: { feature: 'backups', level: 'write' },
+ steps: [
+ {
+ id: 'open-schedule-form',
+ titleKey: 'app.walkthroughs.openScheduleForm',
+ title: 'Open a backup schedule',
+ descriptionKey: 'app.walkthroughs.openScheduleFormDescription',
+ description: 'Start a recurring schedule so protection does not depend on memory.',
+ path: '/backups/schedules?focus=create:schedule',
+ route: '/backups/schedules',
+ target: '[data-walkthrough="backup-schedule-form"]',
+ actionKey: 'app.walkthroughs.newSchedule',
+ action: 'New schedule',
+ },
+ {
+ id: 'configure-schedule',
+ titleKey: 'app.walkthroughs.configureSchedule',
+ title: 'Choose the target and cadence',
+ descriptionKey: 'app.walkthroughs.configureScheduleDescription',
+ description: 'Select what to protect, when it runs, and whether a remote copy is required.',
+ target: '[data-walkthrough="backup-schedule-form"]',
+ actionKey: 'app.walkthroughs.configureScheduleAction',
+ action: 'Configure schedule',
+ },
+ {
+ id: 'save-schedule',
+ titleKey: 'app.walkthroughs.saveSchedule',
+ title: 'Save the schedule',
+ descriptionKey: 'app.walkthroughs.saveScheduleDescription',
+ description: 'Create the schedule and confirm its next run appears in the list.',
+ signal: 'backup-schedule-created',
+ target: '[data-walkthrough="backup-schedule-submit"]',
+ actionKey: 'app.walkthroughs.saveScheduleAction',
+ action: 'Save schedule',
+ },
+ {
+ id: 'create-first-backup',
+ titleKey: 'app.walkthroughs.createFirstBackup',
+ title: 'Create the first snapshot',
+ descriptionKey: 'app.walkthroughs.createFirstBackupDescription',
+ description: 'Run one backup now so you can verify the target before relying on the schedule.',
+ path: '/backups/snapshots?focus=create:backup',
+ signal: 'backup-created',
+ target: '[data-walkthrough="backup-create-form"]',
+ actionKey: 'app.walkthroughs.backUpNow',
+ action: 'Back up now',
+ },
+ ],
+ },
+ {
+ id: 'connect-server',
+ icon: 'server',
+ tone: 'cyan',
+ secondary: true,
+ titleKey: 'app.walkthroughs.connectServerTitle',
+ title: 'Connect another server',
+ descriptionKey: 'app.walkthroughs.connectServerDescription',
+ description: 'Generate a one-time connection, install the agent, and confirm it reports online.',
+ durationKey: 'app.walkthroughs.sixMinutes',
+ duration: 'About 6 minutes',
+ permission: { feature: 'servers', level: 'write' },
+ steps: [
+ {
+ id: 'open-server-drawer',
+ titleKey: 'app.walkthroughs.openServerDrawer',
+ title: 'Open the server connection flow',
+ descriptionKey: 'app.walkthroughs.openServerDrawerDescription',
+ description: 'Start from Servers and choose a connection method for the target machine.',
+ path: '/servers?focus=create:server',
+ route: '/servers',
+ target: '[data-walkthrough="server-setup"]',
+ actionKey: 'app.walkthroughs.addServer',
+ action: 'Add server',
+ },
+ {
+ id: 'generate-connection',
+ titleKey: 'app.walkthroughs.generateConnection',
+ title: 'Generate a one-time connection',
+ descriptionKey: 'app.walkthroughs.generateConnectionDescription',
+ description: 'Choose an optional group and a short token lifetime, then generate the connection string.',
+ signal: 'server-connection-string-generated',
+ target: '[data-walkthrough="server-generate-connection"]',
+ actionKey: 'app.walkthroughs.generateConnectionAction',
+ action: 'Generate connection',
+ },
+ {
+ id: 'install-agent',
+ titleKey: 'app.walkthroughs.installAgent',
+ title: 'Install and connect the agent',
+ descriptionKey: 'app.walkthroughs.installAgentDescription',
+ description: 'Copy the connection string or installer command to the target machine and run it there.',
+ signal: 'server-connection-string-copied',
+ target: '[data-walkthrough="server-connection-string"]',
+ actionKey: 'app.walkthroughs.connectAgent',
+ action: 'Connect agent',
+ },
+ {
+ id: 'confirm-server-online',
+ titleKey: 'app.walkthroughs.confirmServerOnline',
+ title: 'Confirm the server is online',
+ descriptionKey: 'app.walkthroughs.confirmServerOnlineDescription',
+ description: 'Return to the server list and confirm the new row changes from pending to online.',
+ path: '/servers',
+ signal: 'server-paired',
+ target: '[data-walkthrough="server-list"]',
+ actionKey: 'app.walkthroughs.reviewServers',
+ action: 'Review servers',
+ },
+ ],
+ },
+ {
+ id: 'invite-teammate',
+ icon: 'team',
+ tone: 'amber',
+ secondary: true,
+ titleKey: 'app.walkthroughs.inviteTeammateTitle',
+ title: 'Invite a teammate safely',
+ descriptionKey: 'app.walkthroughs.inviteTeammateDescription',
+ description: 'Choose a role, create a time-limited invitation, and share it.',
+ durationKey: 'app.walkthroughs.threeMinutes',
+ duration: 'About 3 minutes',
+ permission: { feature: 'users', level: 'write' },
+ steps: [
+ {
+ id: 'open-invite-form',
+ titleKey: 'app.walkthroughs.openInviteForm',
+ title: 'Open the invitation form',
+ descriptionKey: 'app.walkthroughs.openInviteFormDescription',
+ description: 'Go to Settings → Users and start a new invitation.',
+ path: '/settings/users?focus=create:invitation',
+ route: '/settings/users',
+ target: '[data-walkthrough="invite-form"]',
+ actionKey: 'app.walkthroughs.inviteUser',
+ action: 'Invite user',
+ },
+ {
+ id: 'choose-invite-access',
+ titleKey: 'app.walkthroughs.chooseInviteAccess',
+ title: 'Choose the least access needed',
+ descriptionKey: 'app.walkthroughs.chooseInviteAccessDescription',
+ description: 'Select a role and expiry. Customize permissions when a broad role grants too much.',
+ target: '[data-walkthrough="invite-form"]',
+ actionKey: 'app.walkthroughs.reviewAccess',
+ action: 'Review access',
+ },
+ {
+ id: 'create-invitation',
+ titleKey: 'app.walkthroughs.createInvitation',
+ title: 'Create the invitation',
+ descriptionKey: 'app.walkthroughs.createInvitationDescription',
+ description: 'Generate the invitation only after its role and expiry match the intended person.',
+ signal: 'invitation-created',
+ target: '[data-walkthrough="invite-submit"]',
+ actionKey: 'app.walkthroughs.createInvitationAction',
+ action: 'Create invitation',
+ },
+ {
+ id: 'share-invitation',
+ titleKey: 'app.walkthroughs.shareInvitation',
+ title: 'Share the invitation',
+ descriptionKey: 'app.walkthroughs.shareInvitationDescription',
+ description: 'Copy the private invitation link and send it through a trusted channel.',
+ signal: 'invitation-link-copied',
+ target: '[data-walkthrough="invite-result"]',
+ actionKey: 'app.walkthroughs.copyInviteLink',
+ action: 'Copy invite link',
+ },
+ ],
+ },
]);
export const WALKTHROUGH_BY_ID = Object.freeze(Object.fromEntries(
@@ -173,6 +475,61 @@ export function localizeWalkthroughs(t) {
},
],
},
+ 'publish-service': {
+ title: t('app.walkthroughs.publishServiceTitle', 'Publish a service securely'),
+ description: t('app.walkthroughs.publishServiceDescription', 'Attach a public domain, confirm DNS, and enable HTTPS.'),
+ duration: t('app.walkthroughs.sixMinutes', 'About 6 minutes'),
+ steps: [
+ { title: t('app.walkthroughs.openDomainSettings', 'Open a service’s domain settings'), description: t('app.walkthroughs.openDomainSettingsDescription', 'Choose the service you want to publish, then open Settings → Domain & SSL.'), action: t('app.walkthroughs.chooseService', 'Choose a service') },
+ { title: t('app.walkthroughs.attachPublicDomain', 'Attach a public domain'), description: t('app.walkthroughs.attachPublicDomainDescription', 'Enter a domain you control and attach it to the service.'), action: t('app.walkthroughs.attachDomain', 'Attach domain') },
+ { title: t('app.walkthroughs.confirmDns', 'Confirm the DNS record'), description: t('app.walkthroughs.confirmDnsDescription', 'Point the domain at this server and wait until public DNS resolves to the correct address.'), action: t('app.walkthroughs.reviewDns', 'Review DNS') },
+ { title: t('app.walkthroughs.enableHttps', 'Enable HTTPS'), description: t('app.walkthroughs.enableHttpsDescription', 'Request a Let’s Encrypt certificate. The guide completes after ServerKit verifies it.'), action: t('app.walkthroughs.enableHttpsAction', 'Enable HTTPS') },
+ ],
+ },
+ 'monitor-service': {
+ title: t('app.walkthroughs.monitorServiceTitle', 'Monitor your first service'),
+ description: t('app.walkthroughs.monitorServiceDescription', 'Create an uptime check and run its first probe.'),
+ duration: t('app.walkthroughs.fourMinutes', 'About 4 minutes'),
+ steps: [
+ { title: t('app.walkthroughs.openMonitorForm', 'Open the monitor form'), description: t('app.walkthroughs.openMonitorFormDescription', 'Start a new uptime monitor from the Monitoring area.'), action: t('app.walkthroughs.addMonitor', 'Add monitor') },
+ { title: t('app.walkthroughs.configureMonitor', 'Choose what success means'), description: t('app.walkthroughs.configureMonitorDescription', 'Set the URL, check type, interval, timeout, and expected response.'), action: t('app.walkthroughs.configureCheck', 'Configure check') },
+ { title: t('app.walkthroughs.createMonitor', 'Create the monitor'), description: t('app.walkthroughs.createMonitorDescription', 'Save the check. ServerKit will begin probing it on the selected interval.'), action: t('app.walkthroughs.saveMonitor', 'Save monitor') },
+ { title: t('app.walkthroughs.runFirstCheck', 'Run the first check'), description: t('app.walkthroughs.runFirstCheckDescription', 'Use Check now on the new row and review the response status and timing.'), action: t('app.walkthroughs.reviewMonitor', 'Review monitor') },
+ ],
+ },
+ 'protect-with-backups': {
+ title: t('app.walkthroughs.backupTitle', 'Protect data with backups'),
+ description: t('app.walkthroughs.backupDescription', 'Schedule recurring protection and create the first snapshot.'),
+ duration: t('app.walkthroughs.fiveMinutes', 'About 5 minutes'),
+ steps: [
+ { title: t('app.walkthroughs.openScheduleForm', 'Open a backup schedule'), description: t('app.walkthroughs.openScheduleFormDescription', 'Start a recurring schedule so protection does not depend on memory.'), action: t('app.walkthroughs.newSchedule', 'New schedule') },
+ { title: t('app.walkthroughs.configureSchedule', 'Choose the target and cadence'), description: t('app.walkthroughs.configureScheduleDescription', 'Select what to protect, when it runs, and whether a remote copy is required.'), action: t('app.walkthroughs.configureScheduleAction', 'Configure schedule') },
+ { title: t('app.walkthroughs.saveSchedule', 'Save the schedule'), description: t('app.walkthroughs.saveScheduleDescription', 'Create the schedule and confirm its next run appears in the list.'), action: t('app.walkthroughs.saveScheduleAction', 'Save schedule') },
+ { title: t('app.walkthroughs.createFirstBackup', 'Create the first snapshot'), description: t('app.walkthroughs.createFirstBackupDescription', 'Run one backup now so you can verify the target before relying on the schedule.'), action: t('app.walkthroughs.backUpNow', 'Back up now') },
+ ],
+ },
+ 'connect-server': {
+ title: t('app.walkthroughs.connectServerTitle', 'Connect another server'),
+ description: t('app.walkthroughs.connectServerDescription', 'Generate a one-time connection, install the agent, and confirm it reports online.'),
+ duration: t('app.walkthroughs.sixMinutes', 'About 6 minutes'),
+ steps: [
+ { title: t('app.walkthroughs.openServerDrawer', 'Open the server connection flow'), description: t('app.walkthroughs.openServerDrawerDescription', 'Start from Servers and choose a connection method for the target machine.'), action: t('app.walkthroughs.addServer', 'Add server') },
+ { title: t('app.walkthroughs.generateConnection', 'Generate a one-time connection'), description: t('app.walkthroughs.generateConnectionDescription', 'Choose an optional group and a short token lifetime, then generate the connection string.'), action: t('app.walkthroughs.generateConnectionAction', 'Generate connection') },
+ { title: t('app.walkthroughs.installAgent', 'Install and connect the agent'), description: t('app.walkthroughs.installAgentDescription', 'Copy the connection string or installer command to the target machine and run it there.'), action: t('app.walkthroughs.connectAgent', 'Connect agent') },
+ { title: t('app.walkthroughs.confirmServerOnline', 'Confirm the server is online'), description: t('app.walkthroughs.confirmServerOnlineDescription', 'Return to the server list and confirm the new row changes from pending to online.'), action: t('app.walkthroughs.reviewServers', 'Review servers') },
+ ],
+ },
+ 'invite-teammate': {
+ title: t('app.walkthroughs.inviteTeammateTitle', 'Invite a teammate safely'),
+ description: t('app.walkthroughs.inviteTeammateDescription', 'Choose a role, create a time-limited invitation, and share it.'),
+ duration: t('app.walkthroughs.threeMinutes', 'About 3 minutes'),
+ steps: [
+ { title: t('app.walkthroughs.openInviteForm', 'Open the invitation form'), description: t('app.walkthroughs.openInviteFormDescription', 'Go to Settings → Users and start a new invitation.'), action: t('app.walkthroughs.inviteUser', 'Invite user') },
+ { title: t('app.walkthroughs.chooseInviteAccess', 'Choose the least access needed'), description: t('app.walkthroughs.chooseInviteAccessDescription', 'Select a role and expiry. Customize permissions when a broad role grants too much.'), action: t('app.walkthroughs.reviewAccess', 'Review access') },
+ { title: t('app.walkthroughs.createInvitation', 'Create the invitation'), description: t('app.walkthroughs.createInvitationDescription', 'Generate the invitation only after its role and expiry match the intended person.'), action: t('app.walkthroughs.createInvitationAction', 'Create invitation') },
+ { title: t('app.walkthroughs.shareInvitation', 'Share the invitation'), description: t('app.walkthroughs.shareInvitationDescription', 'Copy the private invitation link and send it through a trusted channel.'), action: t('app.walkthroughs.copyInviteLink', 'Copy invite link') },
+ ],
+ },
};
return WALKTHROUGHS.map((walkthrough) => {
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index 4aad61b7..31cfc7db 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -6326,34 +6326,110 @@
"volumeRemovedSuccessfully": "Volume removed successfully"
},
"walkthroughs": {
+ "addMonitor": "Add monitor",
+ "addServer": "Add server",
"all": "All walkthroughs",
+ "attachDomain": "Attach domain",
+ "attachPublicDomain": "Attach a public domain",
+ "attachPublicDomainDescription": "Enter a domain you control and attach it to the service.",
+ "backUpNow": "Back up now",
+ "backupDescription": "Schedule recurring protection and create the first snapshot.",
+ "backupTitle": "Protect data with backups",
"checkStatus": "Check status",
+ "chooseInviteAccess": "Choose the least access needed",
+ "chooseInviteAccessDescription": "Select a role and expiry. Customize permissions when a broad role grants too much.",
+ "chooseService": "Choose a service",
"chooseServiceSource": "Choose where the code lives",
"chooseServiceSourceDescription": "Pick GitHub, another Git remote, a local path, or a ZIP upload.",
"chooseSource": "Choose a source",
"completed": "Completed",
+ "configureCheck": "Configure check",
+ "configureMonitor": "Choose what success means",
+ "configureMonitorDescription": "Set the URL, check type, interval, timeout, and expected response.",
+ "configureSchedule": "Choose the target and cadence",
+ "configureScheduleAction": "Configure schedule",
+ "configureScheduleDescription": "Select what to protect, when it runs, and whether a remote copy is required.",
+ "confirmDns": "Confirm the DNS record",
+ "confirmDnsDescription": "Point the domain at this server and wait until public DNS resolves to the correct address.",
+ "confirmServerOnline": "Confirm the server is online",
+ "confirmServerOnlineDescription": "Return to the server list and confirm the new row changes from pending to online.",
+ "connectAgent": "Connect agent",
+ "connectServerDescription": "Generate a one-time connection, install the agent, and confirm it reports online.",
+ "connectServerTitle": "Connect another server",
"continueSetup": "Continue setup",
+ "copyInviteLink": "Copy invite link",
+ "createFirstBackup": "Create the first snapshot",
+ "createFirstBackupDescription": "Run one backup now so you can verify the target before relying on the schedule.",
+ "createInvitation": "Create the invitation",
+ "createInvitationAction": "Create invitation",
+ "createInvitationDescription": "Generate the invitation only after its role and expiry match the intended person.",
+ "createMonitor": "Create the monitor",
+ "createMonitorDescription": "Save the check. ServerKit will begin probing it on the selected interval.",
"createServiceDescription": "Choose a source, review the detected runtime, and launch a service.",
"createServiceTitle": "Create your first service",
"doneCount": "{{count}} of {{total}} done",
"doneNextStep": "Done · next step",
+ "enableHttps": "Enable HTTPS",
+ "enableHttpsAction": "Enable HTTPS",
+ "enableHttpsDescription": "Request a Let’s Encrypt certificate. The guide completes after ServerKit verifies it.",
"enableTwoFactorDescription": "Pair an authenticator, verify a code, and store your recovery codes.",
"enableTwoFactorTitle": "Enable two-step authentication",
"finishService": "Finish in the wizard",
"fiveMinutes": "About 5 minutes",
+ "fourMinutes": "About 4 minutes",
+ "generateConnection": "Generate a one-time connection",
+ "generateConnectionAction": "Generate connection",
+ "generateConnectionDescription": "Choose an optional group and a short token lifetime, then generate the connection string.",
+ "hideMoreGuides": "Show fewer guides",
+ "installAgent": "Install and connect the agent",
+ "installAgentDescription": "Copy the connection string or installer command to the target machine and run it there.",
+ "inviteTeammateDescription": "Choose a role, create a time-limited invitation, and share it.",
+ "inviteTeammateTitle": "Invite a teammate safely",
+ "inviteUser": "Invite user",
+ "keepLibraryFocused": "Keep the library focused on the essentials",
"launchService": "Create and launch the service",
"launchServiceDescription": "Submit the reviewed configuration. The guide completes only after creation succeeds.",
"markDone": "Mark done",
+ "monitorServiceDescription": "Create an uptime check and run its first probe.",
+ "monitorServiceTitle": "Monitor your first service",
+ "moreGuides": "More walkthroughs",
+ "moreGuidesCount": "{{count}} optional guides",
+ "newSchedule": "New schedule",
+ "openDomainSettings": "Open a service’s domain settings",
+ "openDomainSettingsDescription": "Choose the service you want to publish, then open Settings → Domain & SSL.",
+ "openInviteForm": "Open the invitation form",
+ "openInviteFormDescription": "Go to Settings → Users and start a new invitation.",
+ "openMonitorForm": "Open the monitor form",
+ "openMonitorFormDescription": "Start a new uptime monitor from the Monitoring area.",
+ "openScheduleForm": "Open a backup schedule",
+ "openScheduleFormDescription": "Start a recurring schedule so protection does not depend on memory.",
"openSecurity": "Open security",
"openSecuritySettings": "Open account security",
"openSecuritySettingsDescription": "Go directly to your personal two-factor authentication card.",
+ "openServerDrawer": "Open the server connection flow",
+ "openServerDrawerDescription": "Start from Servers and choose a connection method for the target machine.",
"openServiceWizard": "Open the service wizard",
"openServiceWizardDescription": "Start from ServerKit’s dedicated three-step service flow.",
"openWizard": "Open wizard",
"pairAuthenticator": "Pair your authenticator",
"pairAuthenticatorDescription": "Scan the QR code, then enter the six-digit code from your app.",
+ "publishServiceDescription": "Attach a public domain, confirm DNS, and enable HTTPS.",
+ "publishServiceTitle": "Publish a service securely",
+ "reviewAccess": "Review access",
+ "reviewDns": "Review DNS",
+ "reviewMonitor": "Review monitor",
+ "reviewServers": "Review servers",
"reviewService": "Review the detected setup",
"reviewServiceDescription": "Confirm the name, runtime, build method, project, and environment.",
+ "runFirstCheck": "Run the first check",
+ "runFirstCheckDescription": "Use Check now on the new row and review the response status and timing.",
+ "saveMonitor": "Save monitor",
+ "saveSchedule": "Save the schedule",
+ "saveScheduleAction": "Save schedule",
+ "saveScheduleDescription": "Create the schedule and confirm its next run appears in the list.",
+ "shareInvitation": "Share the invitation",
+ "shareInvitationDescription": "Copy the private invitation link and send it through a trusted channel.",
+ "sixMinutes": "About 6 minutes",
"startEnrollment": "Start enrollment",
"stepCount": "Step {{current}} of {{total}}",
"stepsMeta": "{{count}} steps · {{duration}}",
diff --git a/frontend/src/pages/Backups.jsx b/frontend/src/pages/Backups.jsx
index cb6959c9..33d43d42 100644
--- a/frontend/src/pages/Backups.jsx
+++ b/frontend/src/pages/Backups.jsx
@@ -26,6 +26,7 @@ import { useTopbarActions, useTopbarChrome } from '@/hooks/useTopbarActions';
import { useTableSort } from '@/hooks/useTableSort';
import { useColumnVisibility } from '@/hooks/useColumnVisibility';
import { useTranslation } from 'react-i18next';
+import useFocusParam from '../hooks/useFocusParam';
// `backups` is kept as an alias so old /backups/backups links still resolve to
// the archive, which now answers to `snapshots`.
@@ -148,6 +149,11 @@ const Backups = () => {
const [uploadingBackup, setUploadingBackup] = useState(null);
const [testingConnection, setTestingConnection] = useState(false);
+ useFocusParam('create', (target) => {
+ if (target === 'schedule') setShowScheduleModal(true);
+ if (target === 'backup') setShowBackupModal(true);
+ });
+
// Backup form state
const [backupForm, setBackupForm] = useState({
type: 'application',
@@ -276,6 +282,9 @@ const Backups = () => {
await api.backupFiles(paths, backupForm.fileName || null);
toast.success(t('app.backups.fileBackupCreated', 'File backup created'));
}
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'backup-created' },
+ }));
setShowBackupModal(false);
resetBackupForm();
loadData();
@@ -344,6 +353,9 @@ const Backups = () => {
scheduleForm.uploadRemote
);
toast.success(t('app.backups.scheduleAdded', 'Schedule added'));
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'backup-schedule-created' },
+ }));
setShowScheduleModal(false);
resetScheduleForm();
loadData();
@@ -1157,7 +1169,7 @@ const Backups = () => {
{/* Create Backup Modal */}
<Modal open={showBackupModal} onClose={() => setShowBackupModal(false)} title={t('app.backups.createBackup', 'Create Backup')}>
- <form onSubmit={handleCreateBackup}>
+ <form onSubmit={handleCreateBackup} data-walkthrough="backup-create-form">
<div className="form-group">
<label>{t('app.backups.backupType', 'Backup Type')}</label>
<select
@@ -1281,14 +1293,14 @@ const Backups = () => {
<Button type="button" variant="outline" onClick={() => setShowBackupModal(false)}>
{t('common.actions.cancel', 'Cancel')}
</Button>
- <Button type="submit">{t('app.backups.createBackup', 'Create Backup')}</Button>
+ <Button type="submit" data-walkthrough="backup-create-submit">{t('app.backups.createBackup', 'Create Backup')}</Button>
</div>
</form>
</Modal>
{/* Add Schedule Modal */}
<Modal open={showScheduleModal} onClose={() => setShowScheduleModal(false)} title={t('app.backups.addBackupSchedule', 'Add Backup Schedule')}>
- <form onSubmit={handleAddSchedule}>
+ <form onSubmit={handleAddSchedule} data-walkthrough="backup-schedule-form">
<div className="form-group">
<label>{t('app.backups.scheduleName', 'Schedule Name')}</label>
<Input
@@ -1362,7 +1374,7 @@ const Backups = () => {
<Button type="button" variant="outline" onClick={() => setShowScheduleModal(false)}>
{t('common.actions.cancel', 'Cancel')}
</Button>
- <Button type="submit">{t('app.backups.addSchedule', 'Add Schedule')}</Button>
+ <Button type="submit" data-walkthrough="backup-schedule-submit">{t('app.backups.addSchedule', 'Add Schedule')}</Button>
</div>
</form>
</Modal>
diff --git a/frontend/src/pages/Monitors.jsx b/frontend/src/pages/Monitors.jsx
index 6c25869f..14dfb6d8 100644
--- a/frontend/src/pages/Monitors.jsx
+++ b/frontend/src/pages/Monitors.jsx
@@ -265,6 +265,9 @@ export default function Monitors() {
}
await api.createMonitor(payload);
toast.success(t('app.monitors.monitoring', 'Monitoring {{name}}', { name: form.name }));
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'monitor-created' },
+ }));
setFormOpen(false);
load();
} catch (err) {
@@ -290,6 +293,9 @@ export default function Monitors() {
const check = res?.check;
if (check?.status === 'up') toast.success(t('app.monitors.upIn', '{{name}}: up in {{duration}} ms', { name: monitor.name, duration: check.response_time ?? '—' }));
else toast.warning(`${monitor.name}: ${check?.status || 'failed'}${check?.error ? ` — ${check.error}` : ''}`);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'monitor-check-completed' },
+ }));
load();
} catch (err) {
toast.error(err.message || t('app.monitors.checkFailed', 'Check failed'));
@@ -404,7 +410,13 @@ export default function Monitors() {
hideable: false,
render: (m) => (
<div className="mon-actions" onClick={(e) => e.stopPropagation()}>
- <Button variant="ghost" size="sm" onClick={() => onCheckNow(m)} title={t('app.monitors.checkNow', 'Check now')}>
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => onCheckNow(m)}
+ title={t('app.monitors.checkNow', 'Check now')}
+ data-walkthrough="monitor-check-now"
+ >
<RefreshCw size={14} />
</Button>
<Button
@@ -526,7 +538,7 @@ export default function Monitors() {
subtitle={t('app.monitors.probeAUrlHostOrPort', 'Probe a URL, host or port on a schedule')}
icon={<Radar size={18} />}
>
- <form className="mon-form" onSubmit={onSave}>
+ <form className="mon-form" onSubmit={onSave} data-walkthrough="monitor-form">
<div className="form-group">
<Label htmlFor="mon-name">{t('common.labels.name', 'Name')}</Label>
<Input
@@ -645,7 +657,7 @@ export default function Monitors() {
<div className="mon-form__actions">
<Button type="button" variant="ghost" onClick={() => setFormOpen(false)}>{t('common.actions.cancel', 'Cancel')}</Button>
- <Button type="submit" disabled={saving}>
+ <Button type="submit" disabled={saving} data-walkthrough="monitor-submit">
{saving ? 'Adding…' : 'Add monitor'}
</Button>
</div>
diff --git a/frontend/src/pages/Servers.jsx b/frontend/src/pages/Servers.jsx
index b96ecc8d..c9733c32 100644
--- a/frontend/src/pages/Servers.jsx
+++ b/frontend/src/pages/Servers.jsx
@@ -377,7 +377,7 @@ const Servers = () => {
}
return (
- <div className="sk-tabgroup__inner servers-page">
+ <div className="sk-tabgroup__inner servers-page" data-walkthrough="server-list">
{topbarChrome}
<GridViewPicker
views={chrome.views}
@@ -588,6 +588,9 @@ const PairAgentForm = ({ groups, onClose, onClaimed }) => {
trust_fingerprint: true
});
toast.success(t('app.servers.agentPairedSuccessfully', 'Agent paired successfully'));
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'server-paired' },
+ }));
onClaimed();
} catch (err) {
const status = err.status || err.response?.status;
@@ -748,6 +751,9 @@ const AddServerModal = ({ groups, onClose, onCreated }) => {
});
setRegistrationData(result);
setStep(2);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'server-connection-string-generated' },
+ }));
} catch (err) {
setError(err.message || 'Failed to create server');
} finally {
@@ -798,7 +804,7 @@ Install-ServerKitAgent -Server "${window.location.origin}" -Token "${registratio
className="server-setup-drawer"
>
{step === 1 && (
- <div className="mode-switcher">
+ <div className="mode-switcher" data-walkthrough="server-setup">
<button
type="button"
className={`mode-switcher__tab${mode === 'install' ? ' is-active' : ''}`}
@@ -832,7 +838,7 @@ Install-ServerKitAgent -Server "${window.location.origin}" -Token "${registratio
onClaimed={onCreated}
/>
) : step === 1 ? (
- <form className="server-setup-form" onSubmit={handleCreateServer}>
+ <form className="server-setup-form" onSubmit={handleCreateServer} data-walkthrough="server-generate-connection">
<div className="server-setup-form__body">
{error && <div className="error-message">{error}</div>}
@@ -887,7 +893,12 @@ Install-ServerKitAgent -Server "${window.location.origin}" -Token "${registratio
<ConnectionStringField
value={connectionString}
- onCopy={() => copy(connectionString)}
+ onCopy={() => {
+ copy(connectionString);
+ window.dispatchEvent(new CustomEvent('serverkit:walkthrough-signal', {
+ detail: { type: 'server-connection-string-copied' },
+ }));
+ }}
/>
<details className="install-fallback">
@@ -937,7 +948,7 @@ Install-ServerKitAgent -Server "${window.location.origin}" -Token "${registratio
const ConnectionStringField = ({ value, onCopy }) => {
const { t } = useTranslation();
return (
- <div className="connection-string-field">
+ <div className="connection-string-field" data-walkthrough="server-connection-string">
<div className="connection-string-field__header">
<KeyIcon />
<span>{t('app.servers.connectionString', 'Connection string')}</span>
diff --git a/frontend/src/services/__tests__/walkthroughRegistry.test.mjs b/frontend/src/services/__tests__/walkthroughRegistry.test.mjs
new file mode 100644
index 00000000..da217a26
--- /dev/null
+++ b/frontend/src/services/__tests__/walkthroughRegistry.test.mjs
@@ -0,0 +1,61 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+ WALKTHROUGHS,
+ WALKTHROUGH_BY_ID,
+ localizeWalkthroughs,
+} from '../../data/walkthroughs.js';
+
+
+const OPTIONAL_IDS = [
+ 'publish-service',
+ 'monitor-service',
+ 'protect-with-backups',
+ 'connect-server',
+ 'invite-teammate',
+];
+
+test('keeps the two essentials prominent and the five added guides optional', () => {
+ assert.deepEqual(
+ WALKTHROUGHS.filter((guide) => !guide.secondary).map((guide) => guide.id),
+ ['create-service', 'enable-two-factor'],
+ );
+ assert.deepEqual(
+ WALKTHROUGHS.filter((guide) => guide.secondary).map((guide) => guide.id),
+ OPTIONAL_IDS,
+ );
+});
+
+test('walkthrough ids and step ids are stable and unique', () => {
+ assert.equal(new Set(WALKTHROUGHS.map((guide) => guide.id)).size, WALKTHROUGHS.length);
+ for (const guide of WALKTHROUGHS) {
+ assert.equal(new Set(guide.steps.map((step) => step.id)).size, guide.steps.length);
+ assert.ok(guide.steps.every((step) => step.title && step.description && step.action));
+ assert.equal(WALKTHROUGH_BY_ID[guide.id], guide);
+ }
+});
+
+test('optional guides finish on real product outcome signals', () => {
+ const finalSignals = Object.fromEntries(OPTIONAL_IDS.map((id) => {
+ const guide = WALKTHROUGH_BY_ID[id];
+ return [id, guide.steps.at(-1).signal];
+ }));
+
+ assert.deepEqual(finalSignals, {
+ 'publish-service': 'service-ssl-enabled',
+ 'monitor-service': 'monitor-check-completed',
+ 'protect-with-backups': 'backup-created',
+ 'connect-server': 'server-paired',
+ 'invite-teammate': 'invitation-link-copied',
+ });
+});
+
+test('every guide and step retains localized display copy', () => {
+ const localized = localizeWalkthroughs((_key, fallback) => fallback);
+ assert.equal(localized.length, WALKTHROUGHS.length);
+ for (const guide of localized) {
+ assert.ok(guide.title && guide.description && guide.duration);
+ assert.ok(guide.steps.every((step) => step.title && step.description && step.action));
+ }
+});
diff --git a/frontend/src/styles/components/_walkthroughs.scss b/frontend/src/styles/components/_walkthroughs.scss
index 2c5277e0..8cf65959 100644
--- a/frontend/src/styles/components/_walkthroughs.scss
+++ b/frontend/src/styles/components/_walkthroughs.scss
@@ -52,6 +52,7 @@
&.is-cyan { color: var(--cyan); background: color-mix(in srgb, var(--cyan) 13%, transparent); }
&.is-amber { color: var(--amber); background: color-mix(in srgb, var(--amber) 13%, transparent); }
+ &.is-green { color: var(--green); background: color-mix(in srgb, var(--green) 13%, transparent); }
}
&__card-name {
@@ -94,6 +95,41 @@
&:hover { color: var(--red); background: var(--red-bg); }
}
+ &__more {
+ display: flex;
+ min-height: 78px;
+ align-items: center;
+ gap: 11px;
+ padding: 13px;
+ border: 1px dashed var(--border-soft);
+ border-radius: 11px;
+ background: transparent;
+ color: var(--text-dim);
+ font: inherit;
+ text-align: start;
+ cursor: pointer;
+ transition: border-color 130ms ease, background 130ms ease, color 130ms ease;
+ @include focus-ring();
+
+ &:hover {
+ border-color: var(--accent-dim);
+ background: var(--surface-2);
+ color: var(--text);
+ }
+
+ > svg { flex: 0 0 auto; color: var(--accent); }
+
+ > span {
+ display: flex;
+ min-width: 0;
+ flex-direction: column;
+ gap: 3px;
+ }
+
+ strong { font-size: 12.5px; font-weight: 550; }
+ small { color: var(--text-faint); font-size: 10.5px; }
+ }
+
// Running recipe — step rail left, story right (prototype cp-split).
&__split {
display: flex;