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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(services): New Service wizard clarity — guides, shared templates, docs links
Juan Denis6accbf9655ec
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 anddiff --git a/frontend/src/components/DocsLink.jsx b/frontend/src/components/DocsLink.jsxnew file mode 100644index 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.jsxindex 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.jsnew file mode 100644index 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.jsxindex 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.jsxindex 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.scssnew file mode 100644index 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.scssindex 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.scssindex 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.scssindex 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.jsnew file mode 100644index 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;