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(services): New Service wizard clarity — guides, shared templates, docs links

Juan Denis6accbf9655ec
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 39c2fb4b..d04bcd70 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,13 @@ awaiting a stable release:
### Added
+- **New Service wizard clarity** — each source card now shows a short explainer
+ strip when selected (what it does, what to have ready, the next steps), and a
+ "Docs" link to the matching serverkit.ai guide (hidden under White Label). The
+ demo deploy template moved out of the wizard into a shared module: the
+ Templates tab gains a **Deploy templates** section with a "Use template"
+ action that deep-links into the wizard with the template preselected
+ (`/services/new?template=<id>`), so there is one list with two entry points.
- **Install extensions straight from GitHub, with a preview + consent step** —
the manual-install URL flow is now two-step: paste a repo (`owner/repo`,
`owner/repo@tag`, a release URL, or a direct `.zip`), **Preview** resolves and
diff --git a/frontend/src/components/DocsLink.jsx b/frontend/src/components/DocsLink.jsx
new file mode 100644
index 00000000..796bd5e5
--- /dev/null
+++ b/frontend/src/components/DocsLink.jsx
@@ -0,0 +1,24 @@
+import { BookOpen } from 'lucide-react';
+import { useTheme } from '../contexts/ThemeContext';
+import { docsUrl } from '../utils/docsLinks';
+
+// Small "Docs" link (book icon) that opens a serverkit.ai docs page in a new
+// tab. Hidden when White Label branding is active — an operator who rebranded
+// the panel does not want it pointing users at serverkit.ai. This is the ONE
+// place that rule lives, so wiring more docs links never re-implements it.
+export default function DocsLink({ to, label = 'Docs', className = '' }) {
+ const { whiteLabel } = useTheme();
+ if (whiteLabel?.enabled) return null;
+
+ return (
+ <a
+ href={docsUrl(to)}
+ target="_blank"
+ rel="noopener noreferrer"
+ className={`sk-docs-link ${className}`.trim()}
+ >
+ <BookOpen size={14} aria-hidden="true" />
+ {label}
+ </a>
+ );
+}
diff --git a/frontend/src/components/marketplace/ManualInstallModal.jsx b/frontend/src/components/marketplace/ManualInstallModal.jsx
index 28b6b186..50a9c8b3 100644
--- a/frontend/src/components/marketplace/ManualInstallModal.jsx
+++ b/frontend/src/components/marketplace/ManualInstallModal.jsx
@@ -14,6 +14,7 @@ import Modal from '@/components/Modal';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Badge } from '@/components/ui/badge';
+import DocsLink from '@/components/DocsLink';
const INSTALL_SOURCES = [
{ id: 'url', label: 'URL', icon: Globe2 },
@@ -206,6 +207,7 @@ const ManualInstallModal = ({ defaultSource = 'url', onClose, onInstalled }) =>
<h3>Extension source</h3>
<p className="text-muted">Load extension packages from a repository, host folder, or zip archive.</p>
</div>
+ <DocsLink to="extensionsInstalling" className="plugin-install-form__docs" />
</div>
<div className="plugin-install-tabs" role="tablist" aria-label="Extension install source">
diff --git a/frontend/src/data/deployTemplates.js b/frontend/src/data/deployTemplates.js
new file mode 100644
index 00000000..c47eff18
--- /dev/null
+++ b/frontend/src/data/deployTemplates.js
@@ -0,0 +1,53 @@
+// Shared deploy-template catalog. One source of truth consumed by both the
+// New Service wizard ("Deploy Template" source) and the Templates tab
+// ("Deploy templates" section), so there is one list with two entry points.
+//
+// `example: true` marks a demonstration entry (badged "Example" in the UI).
+// Real curated templates can be appended here as they are added.
+
+export const DEPLOY_TEMPLATES = [
+ {
+ id: 'agentsite',
+ name: 'AgentSite',
+ serviceName: 'agentsite',
+ description: 'AI-powered website builder with multi-agent orchestration.',
+ repoUrl: 'https://github.com/jhd3197/AgentSite.git',
+ branch: 'main',
+ appType: 'docker',
+ buildMethod: 'dockerfile',
+ port: 6391,
+ example: true,
+ badges: ['Render', 'Railway', 'Compose', 'Dockerfile'],
+ manifest: {
+ strategy: 'docker_compose',
+ recommended: {
+ app_type: 'docker',
+ build_method: 'dockerfile',
+ port: 6391,
+ dockerfile_path: 'Dockerfile',
+ healthcheck_path: '/api/health',
+ },
+ manifests: [
+ { type: 'docker_compose', file: 'docker-compose.yml', label: 'Docker Compose', summary: 'agentsite service on port 6391' },
+ { type: 'render', file: 'render.yaml', label: 'Render blueprint', summary: 'agentsite web service using docker' },
+ { type: 'railway', file: 'railway.json', label: 'Railway config', summary: 'Dockerfile build with health check' },
+ { type: 'app_json', file: 'app.json', label: 'App manifest', summary: 'AI-powered website builder using multi-agent orchestration' },
+ ],
+ env: [
+ { key: 'OPENAI_API_KEY', required: true, secret: true, source: 'render.yaml' },
+ { key: 'CLAUDE_API_KEY', required: true, secret: true, source: 'render.yaml' },
+ { key: 'GOOGLE_API_KEY', required: true, secret: true, source: 'render.yaml' },
+ { key: 'GROQ_API_KEY', required: true, secret: true, source: 'render.yaml' },
+ { key: 'GROK_API_KEY', required: true, secret: true, source: 'render.yaml' },
+ { key: 'OPENROUTER_API_KEY', required: true, secret: true, source: 'render.yaml' },
+ ],
+ ports: [6391],
+ },
+ },
+];
+
+export function getDeployTemplate(id) {
+ return DEPLOY_TEMPLATES.find((t) => t.id === id) || null;
+}
+
+export default DEPLOY_TEMPLATES;
diff --git a/frontend/src/pages/NewService.jsx b/frontend/src/pages/NewService.jsx
index 6014cc41..3b32dad0 100644
--- a/frontend/src/pages/NewService.jsx
+++ b/frontend/src/pages/NewService.jsx
@@ -1,5 +1,5 @@
import { useCallback, useEffect, useMemo, useState } from 'react';
-import { Link, useNavigate } from 'react-router-dom';
+import { Link, useNavigate, useSearchParams } from 'react-router-dom';
import {
ArrowRight,
CheckCircle2,
@@ -30,6 +30,8 @@ import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Switch } from '@/components/ui/switch';
import BuildpackPreview from '@/components/buildpack/BuildpackPreview';
+import DocsLink from '@/components/DocsLink';
+import { DEPLOY_TEMPLATES as SERVICE_TEMPLATES, getDeployTemplate } from '@/data/deployTemplates';
const APP_TYPE_OPTIONS = [
{ value: 'auto', label: 'Auto-detect' },
@@ -50,45 +52,35 @@ const BUILD_METHOD_OPTIONS = [
const APP_TYPE_LABELS = Object.fromEntries(APP_TYPE_OPTIONS.map(option => [option.value, option.label]));
const BUILD_METHOD_LABELS = Object.fromEntries(BUILD_METHOD_OPTIONS.map(option => [option.value, option.label]));
-const SERVICE_TEMPLATES = [
- {
- id: 'agentsite',
- name: 'AgentSite',
- serviceName: 'agentsite',
- description: 'AI-powered website builder with multi-agent orchestration.',
- repoUrl: 'https://github.com/jhd3197/AgentSite.git',
- branch: 'main',
- appType: 'docker',
- buildMethod: 'dockerfile',
- port: 6391,
- badges: ['Render', 'Railway', 'Compose', 'Dockerfile'],
- manifest: {
- strategy: 'docker_compose',
- recommended: {
- app_type: 'docker',
- build_method: 'dockerfile',
- port: 6391,
- dockerfile_path: 'Dockerfile',
- healthcheck_path: '/api/health',
- },
- manifests: [
- { type: 'docker_compose', file: 'docker-compose.yml', label: 'Docker Compose', summary: 'agentsite service on port 6391' },
- { type: 'render', file: 'render.yaml', label: 'Render blueprint', summary: 'agentsite web service using docker' },
- { type: 'railway', file: 'railway.json', label: 'Railway config', summary: 'Dockerfile build with health check' },
- { type: 'app_json', file: 'app.json', label: 'App manifest', summary: 'AI-powered website builder using multi-agent orchestration' },
- ],
- env: [
- { key: 'OPENAI_API_KEY', required: true, secret: true, source: 'render.yaml' },
- { key: 'CLAUDE_API_KEY', required: true, secret: true, source: 'render.yaml' },
- { key: 'GOOGLE_API_KEY', required: true, secret: true, source: 'render.yaml' },
- { key: 'GROQ_API_KEY', required: true, secret: true, source: 'render.yaml' },
- { key: 'GROK_API_KEY', required: true, secret: true, source: 'render.yaml' },
- { key: 'OPENROUTER_API_KEY', required: true, secret: true, source: 'render.yaml' },
- ],
- ports: [6391],
- },
+// Per-source guidance shown as an explainer strip above the selected source's
+// form: what this path does, what to have ready, and the steps that follow.
+const SOURCE_GUIDES = {
+ github: {
+ what: 'Deploy from a GitHub repository you own or can access.',
+ need: 'A GitHub account connected via OAuth (Settings → Connections).',
+ steps: ['Connect with OAuth', 'Pick a repository and branch', 'ServerKit detects the runtime and build'],
},
-];
+ manual: {
+ what: 'Deploy from any other Git remote (GitLab, Bitbucket, Gitea, or an SSH URL).',
+ need: 'The repository URL, and a deploy key or credentials if it is private.',
+ steps: ['Paste the remote URL', 'Choose a branch', 'ServerKit clones and detects the build'],
+ },
+ local: {
+ what: 'Register an application that already lives on this server — no clone, no build.',
+ need: 'The path on the server, and its compose file or systemd unit if any.',
+ steps: ['Point at the directory or unit', 'Tell ServerKit how it is managed', 'It starts tracking the service'],
+ },
+ upload: {
+ what: 'Deploy or update from a project zip archive uploaded from your machine.',
+ need: 'A .zip of the project (with a Dockerfile/compose or a detectable runtime).',
+ steps: ['Upload the archive', 'ServerKit extracts and detects the runtime', 'It builds and deploys'],
+ },
+ template: {
+ what: 'Fast import from a manifest-ready repository — the form is prefilled for you.',
+ need: 'A repo with a serverkit.yaml, Docker Compose, or another supported manifest.',
+ steps: ['Pick a template', 'ServerKit reads its manifests and prefills everything', 'Review and deploy'],
+ },
+};
function slugify(value) {
return value.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
@@ -120,6 +112,7 @@ function formatBuildMethod(value) {
const NewService = () => {
const navigate = useNavigate();
const toast = useToast();
+ const [searchParams] = useSearchParams();
const [sourceMode, setSourceMode] = useState('github');
const [githubStatus, setGithubStatus] = useState(null);
const [repos, setRepos] = useState([]);
@@ -432,6 +425,19 @@ const NewService = () => {
}
}
+ // Deep-link from the Templates tab: /services/new?template=<id> lands here
+ // with the Deploy Template source preselected. Runs once on mount.
+ useEffect(() => {
+ const templateId = searchParams.get('template');
+ if (!templateId) return;
+ const template = getDeployTemplate(templateId);
+ if (template) {
+ setSourceMode('template');
+ handleSelectTemplate(template);
+ }
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
async function handleSubmit(e) {
e.preventDefault();
if (!canSubmit) {
@@ -610,8 +616,26 @@ const NewService = () => {
? 'Upload Archive'
: 'Connect Source'}
</h2>
+ <DocsLink
+ to={sourceMode === 'template' ? 'manifest' : 'deploySources'}
+ className="new-service-page__section-docs"
+ />
</div>
+ {SOURCE_GUIDES[sourceMode] && (
+ <div className="new-service-page__source-guide">
+ <p className="new-service-page__source-guide-what">{SOURCE_GUIDES[sourceMode].what}</p>
+ <p className="new-service-page__source-guide-need">
+ <strong>Have ready:</strong> {SOURCE_GUIDES[sourceMode].need}
+ </p>
+ <ol className="new-service-page__source-guide-steps">
+ {SOURCE_GUIDES[sourceMode].steps.map((step, i) => (
+ <li key={i}>{step}</li>
+ ))}
+ </ol>
+ </div>
+ )}
+
{sourceMode === 'github' ? (
<div className="new-service-page__connect-box">
{githubConnection ? (
@@ -710,7 +734,12 @@ const NewService = () => {
onClick={() => handleSelectTemplate(template)}
>
<span className="new-service-page__template-main">
- <strong>{template.name}</strong>
+ <strong>
+ {template.name}
+ {template.example && (
+ <span className="new-service-page__template-example">Example</span>
+ )}
+ </strong>
<small>{template.description}</small>
<em>{template.repoUrl}</em>
</span>
@@ -726,7 +755,7 @@ const NewService = () => {
<div className="new-service-page__connect-actions new-service-page__connect-actions--left">
<Button type="button" variant="outline" asChild>
- <Link to="/templates">
+ <Link to="/templates#deploy-templates">
<Package size={16} />
Template Library
</Link>
diff --git a/frontend/src/pages/Templates.jsx b/frontend/src/pages/Templates.jsx
index 13262047..cb62d74a 100644
--- a/frontend/src/pages/Templates.jsx
+++ b/frontend/src/pages/Templates.jsx
@@ -14,6 +14,7 @@ import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { useTopbarActions } from '@/hooks/useTopbarActions';
import EmptyState from '../components/EmptyState';
+import { DEPLOY_TEMPLATES } from '@/data/deployTemplates';
// Featured templates (curated list)
const FEATURED_TEMPLATES = [
@@ -440,6 +441,44 @@ const Templates = () => {
return (
<div className="sk-tabgroup__inner templates-page">
+ {/* Deploy templates — manifest-ready repos, shared with the New
+ Service wizard's "Deploy Template" source. */}
+ <section id="deploy-templates" className="deploy-templates-section">
+ <div className="deploy-templates-section__head">
+ <div>
+ <h3>Deploy templates</h3>
+ <p>Manifest-ready repositories that prefill the New Service wizard.</p>
+ </div>
+ </div>
+ <div className="deploy-templates-list">
+ {DEPLOY_TEMPLATES.map(template => (
+ <div key={template.id} className="deploy-template-row">
+ <div className="deploy-template-row__main">
+ <div className="deploy-template-row__title">
+ <strong>{template.name}</strong>
+ {template.example && (
+ <span className="deploy-template-row__example">Example</span>
+ )}
+ </div>
+ <p>{template.description}</p>
+ <code>{template.repoUrl}</code>
+ <div className="deploy-template-row__badges">
+ {(template.badges || []).map(badge => (
+ <span key={badge}>{badge}</span>
+ ))}
+ </div>
+ </div>
+ <Button
+ size="sm"
+ onClick={() => navigate(`/services/new?template=${encodeURIComponent(template.id)}`)}
+ >
+ <Rocket size={14} /> Use template
+ </Button>
+ </div>
+ ))}
+ </div>
+ </section>
+
{/* Results and Filters */}
<div className="templates-results-header">
<span className="results-count">
diff --git a/frontend/src/styles/components/_docs-link.scss b/frontend/src/styles/components/_docs-link.scss
new file mode 100644
index 00000000..800b4cbc
--- /dev/null
+++ b/frontend/src/styles/components/_docs-link.scss
@@ -0,0 +1,19 @@
+// Small "Docs" link (book icon) rendered by <DocsLink>. Hidden under White
+// Label by the component itself; this only styles it.
+.sk-docs-link {
+ display: inline-flex;
+ align-items: center;
+ gap: $space-1;
+ color: $accent-primary;
+ font-size: $font-size-sm;
+ text-decoration: none;
+ white-space: nowrap;
+
+ svg {
+ flex-shrink: 0;
+ }
+
+ &:hover {
+ text-decoration: underline;
+ }
+}
diff --git a/frontend/src/styles/main.scss b/frontend/src/styles/main.scss
index f9e365b5..3db1aede 100644
--- a/frontend/src/styles/main.scss
+++ b/frontend/src/styles/main.scss
@@ -56,6 +56,7 @@
@import 'components/_query-runner';
@import 'components/_deploy';
@import 'components/_git-connect';
+@import 'components/_docs-link';
@import 'components/_build';
@import 'components/_users';
@import 'components/_linked-apps';
diff --git a/frontend/src/styles/pages/_new-service.scss b/frontend/src/styles/pages/_new-service.scss
index 8eeb8390..e61c8bce 100644
--- a/frontend/src/styles/pages/_new-service.scss
+++ b/frontend/src/styles/pages/_new-service.scss
@@ -185,6 +185,60 @@
}
}
+ &__section-docs {
+ margin-left: auto;
+ }
+
+ // Per-source explainer strip above the selected source's form.
+ &__source-guide {
+ margin: $space-3 0 $space-4;
+ padding: $space-3 $space-4;
+ border: 1px solid $border-color;
+ border-radius: $radius-md;
+ background: $bg-elevated;
+
+ p {
+ margin: 0 0 $space-2;
+ font-size: $font-size-sm;
+ color: $text-secondary;
+ }
+ }
+
+ &__source-guide-what {
+ color: $text-primary !important;
+ font-weight: $font-weight-medium;
+ }
+
+ &__source-guide-need strong {
+ color: $text-secondary;
+ }
+
+ &__source-guide-steps {
+ margin: 0;
+ padding-left: $space-4;
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+
+ li {
+ font-size: $font-size-sm;
+ color: $text-tertiary;
+ }
+ }
+
+ &__template-example {
+ margin-left: $space-2;
+ padding: 1px $space-2;
+ border-radius: $radius-sm;
+ background: rgba($accent-primary-raw, 0.15);
+ color: $accent-primary;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+ vertical-align: middle;
+ }
+
&__provider-grid {
display: grid;
grid-template-columns: repeat(4, minmax(0, 1fr));
diff --git a/frontend/src/styles/pages/_templates.scss b/frontend/src/styles/pages/_templates.scss
index dd55b17e..3bd7affb 100644
--- a/frontend/src/styles/pages/_templates.scss
+++ b/frontend/src/styles/pages/_templates.scss
@@ -364,6 +364,102 @@
}
// Results Header
+.deploy-templates-section {
+ margin-bottom: $space-5;
+ padding-bottom: $space-4;
+ border-bottom: 1px solid $border-color;
+
+ &__head {
+ margin-bottom: $space-3;
+
+ h3 {
+ margin: 0 0 2px;
+ font-size: $font-size-base;
+ font-weight: $font-weight-semibold;
+ color: $text-primary;
+ }
+
+ p {
+ margin: 0;
+ font-size: $font-size-sm;
+ color: $text-tertiary;
+ }
+ }
+}
+
+.deploy-templates-list {
+ display: grid;
+ grid-template-columns: repeat(auto-fill, minmax(360px, 1fr));
+ gap: $space-3;
+}
+
+.deploy-template-row {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-3;
+ padding: $space-3 $space-4;
+ border: 1px solid $border-color;
+ border-radius: $radius-md;
+ background: $bg-card;
+
+ &__main {
+ min-width: 0;
+
+ p {
+ margin: 2px 0 $space-1;
+ font-size: $font-size-sm;
+ color: $text-secondary;
+ }
+
+ code {
+ display: block;
+ font-size: $font-size-xs;
+ color: $text-tertiary;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+ }
+
+ &__title {
+ display: flex;
+ align-items: center;
+ gap: $space-2;
+
+ strong {
+ color: $text-primary;
+ font-weight: $font-weight-semibold;
+ }
+ }
+
+ &__example {
+ padding: 1px $space-2;
+ border-radius: $radius-sm;
+ background: rgba($accent-primary-raw, 0.15);
+ color: $accent-primary;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-medium;
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+ }
+
+ &__badges {
+ display: flex;
+ flex-wrap: wrap;
+ gap: $space-1;
+ margin-top: $space-2;
+
+ span {
+ padding: 1px $space-2;
+ border: 1px solid $border-color;
+ border-radius: $radius-sm;
+ font-size: $font-size-xs;
+ color: $text-tertiary;
+ }
+ }
+}
+
.templates-results-header {
display: grid;
grid-template-columns: auto minmax(0, 1fr) auto;
diff --git a/frontend/src/utils/docsLinks.js b/frontend/src/utils/docsLinks.js
new file mode 100644
index 00000000..8af451a2
--- /dev/null
+++ b/frontend/src/utils/docsLinks.js
@@ -0,0 +1,21 @@
+// Single map of panel surface -> serverkit.ai docs URL. Keeping every external
+// docs link in one place means the White Label "hide external links" rule lives
+// in exactly one component (DocsLink), and URLs don't drift page to page.
+
+const DOCS_BASE = 'https://serverkit.ai/docs';
+
+export const DOCS_LINKS = {
+ deploySources: `${DOCS_BASE}/deploy-sources`,
+ manifest: `${DOCS_BASE}/manifest`,
+ extensions: `${DOCS_BASE}/extensions`,
+ extensionsInstalling: `${DOCS_BASE}/extensions/installing`,
+ extensionsBuilding: `${DOCS_BASE}/extensions/building`,
+ extensionsPublishing: `${DOCS_BASE}/extensions/publishing`,
+ extensionsSecurity: `${DOCS_BASE}/extensions/security`,
+};
+
+export function docsUrl(key) {
+ return DOCS_LINKS[key] || DOCS_BASE;
+}
+
+export default DOCS_LINKS;