Merge pull request #1 from AnsoCode/feature/app-templates

feat: App Templates & One-Click Installs
This commit is contained in:
Anso
2026-03-04 16:16:55 -05:00
committed by GitHub
8 changed files with 577 additions and 3 deletions
+3
View File
@@ -18,6 +18,9 @@ jobs:
with:
node-version: '20'
cache: 'npm'
cache-dependency-path: |
backend/package-lock.json
frontend/package-lock.json
- name: Install Backend Dependencies
working-directory: ./backend
+1
View File
@@ -8,3 +8,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- Git Flow branching strategy and branch protection.
- GitHub Actions CI pipeline for automated TypeScript build verification.
- **Added:** App Templates (App Store) with One-Click deployment, utilizing Portainer v2 JSON registries and auto-generating compose files.
+132
View File
@@ -13,6 +13,7 @@
"@types/dockerode": "^4.0.1",
"@types/express": "^5.0.6",
"@types/ws": "^8.18.1",
"axios": "^1.13.6",
"bcrypt": "^6.0.0",
"better-sqlite3": "^12.6.2",
"composerize": "^1.7.5",
@@ -566,6 +567,23 @@
"safer-buffer": "~2.1.0"
}
},
"node_modules/asynckit": {
"version": "0.4.0",
"resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
"integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==",
"license": "MIT"
},
"node_modules/axios": {
"version": "1.13.6",
"resolved": "https://registry.npmjs.org/axios/-/axios-1.13.6.tgz",
"integrity": "sha512-ChTCHMouEe2kn713WHbQGcuYrr6fXTBiu460OTwWrWob16g1bXn4vtz07Ope7ewMozJAnEquLk5lWQWtBig9DQ==",
"license": "MIT",
"dependencies": {
"follow-redirects": "^1.15.11",
"form-data": "^4.0.5",
"proxy-from-env": "^1.1.0"
}
},
"node_modules/balanced-match": {
"version": "4.0.3",
"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.3.tgz",
@@ -865,6 +883,18 @@
"integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
"license": "MIT"
},
"node_modules/combined-stream": {
"version": "1.0.8",
"resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
"integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==",
"license": "MIT",
"dependencies": {
"delayed-stream": "~1.0.0"
},
"engines": {
"node": ">= 0.8"
}
},
"node_modules/composerize": {
"version": "1.7.5",
"resolved": "https://registry.npmjs.org/composerize/-/composerize-1.7.5.tgz",
@@ -1067,6 +1097,15 @@
"node": ">=0.10.0"
}
},
"node_modules/delayed-stream": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
"integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==",
"license": "MIT",
"engines": {
"node": ">=0.4.0"
}
},
"node_modules/depd": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
@@ -1211,6 +1250,21 @@
"node": ">= 0.4"
}
},
"node_modules/es-set-tostringtag": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz",
"integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==",
"license": "MIT",
"dependencies": {
"es-errors": "^1.3.0",
"get-intrinsic": "^1.2.6",
"has-tostringtag": "^1.0.2",
"hasown": "^2.0.2"
},
"engines": {
"node": ">= 0.4"
}
},
"node_modules/escalade": {
"version": "3.2.0",
"resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
@@ -1349,6 +1403,63 @@
"url": "https://opencollective.com/express"
}
},
"node_modules/follow-redirects": {
"version": "1.15.11",
"resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.11.tgz",
"integrity": "sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ==",
"funding": [
{
"type": "individual",
"url": "https://github.com/sponsors/RubenVerborgh"
}
],
"license": "MIT",
"engines": {
"node": ">=4.0"
},
"peerDependenciesMeta": {
"debug": {
"optional": true
}
}
},
"node_modules/form-data": {
"version": "4.0.5",
"resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz",
"integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==",
"license": "MIT",
"dependencies": {
"asynckit": "^0.4.0",
"combined-stream": "^1.0.8",
"es-set-tostringtag": "^2.1.0",
"hasown": "^2.0.2",
"mime-types": "^2.1.12"
},
"engines": {
"node": ">= 6"
}
},
"node_modules/form-data/node_modules/mime-db": {
"version": "1.52.0",
"resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
"integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
"license": "MIT",
"engines": {
"node": ">= 0.6"
}
},
"node_modules/form-data/node_modules/mime-types": {
"version": "2.1.35",
"resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
"integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
"license": "MIT",
"dependencies": {
"mime-db": "1.52.0"
},
"engines": {
"node": ">= 0.6"
}
},
"node_modules/forwarded": {
"version": "0.2.0",
"resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -1496,6 +1607,21 @@
"url": "https://github.com/sponsors/ljharb"
}
},
"node_modules/has-tostringtag": {
"version": "1.0.2",
"resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz",
"integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==",
"license": "MIT",
"dependencies": {
"has-symbols": "^1.0.3"
},
"engines": {
"node": ">= 0.4"
},
"funding": {
"url": "https://github.com/sponsors/ljharb"
}
},
"node_modules/hasown": {
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz",
@@ -2141,6 +2267,12 @@
"node": ">= 0.10"
}
},
"node_modules/proxy-from-env": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz",
"integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==",
"license": "MIT"
},
"node_modules/pstree.remy": {
"version": "1.1.8",
"resolved": "https://registry.npmjs.org/pstree.remy/-/pstree.remy-1.1.8.tgz",
+2 -1
View File
@@ -29,6 +29,7 @@
"@types/dockerode": "^4.0.1",
"@types/express": "^5.0.6",
"@types/ws": "^8.18.1",
"axios": "^1.13.6",
"bcrypt": "^6.0.0",
"better-sqlite3": "^12.6.2",
"composerize": "^1.7.5",
@@ -42,4 +43,4 @@
"ws": "^8.19.0",
"yaml": "^2.8.2"
}
}
}
+46
View File
@@ -19,6 +19,7 @@ import { HostTerminalService } from './services/HostTerminalService';
import { DatabaseService } from './services/DatabaseService';
import { NotificationService } from './services/NotificationService';
import { MonitorService } from './services/MonitorService';
import { templateService } from './services/TemplateService';
import YAML from 'yaml';
import { promises as fsPromises } from 'fs';
@@ -1048,6 +1049,51 @@ app.post('/api/system/networks/delete', async (req: Request, res: Response) => {
}
});
// --- App Templates Routes ---
app.get('/api/templates', async (req: Request, res: Response) => {
try {
const templates = await templateService.getTemplates();
res.json(templates);
} catch (error) {
res.status(500).json({ error: 'Failed to fetch templates' });
}
});
app.post('/api/templates/deploy', async (req: Request, res: Response) => {
try {
const { stackName, template, envVars } = req.body;
if (!stackName || !template) {
return res.status(400).json({ error: 'stackName and template are required' });
}
// 1. Create stack directory
await fileSystemService.createStack(stackName);
// 2. Generate compose YAML and save
const composeYaml = templateService.generateComposeFromTemplate(template);
await fileSystemService.saveStackContent(stackName, composeYaml);
// 3. Generate env string and save to default .env
if (envVars) {
const envString = templateService.generateEnvString(envVars);
const stackDir = path.join(fileSystemService.getBaseDir(), stackName);
const defaultEnvPath = path.join(stackDir, '.env');
await fsPromises.writeFile(defaultEnvPath, envString, 'utf-8');
}
// 4. Deploy the stack
await composeService.deployStack(stackName, terminalWs || undefined);
res.json({ success: true, message: 'Template deployed successfully' });
} catch (error: any) {
console.error('Failed to deploy template:', error);
res.status(500).json({ error: error.message || 'Failed to deploy template' });
}
});
// Serve static files in production (for Docker deployment)
if (process.env.NODE_ENV === 'production') {
+106
View File
@@ -0,0 +1,106 @@
import axios from 'axios';
export interface TemplateEnv {
name: string;
label?: string;
default?: string;
}
export interface TemplateVolume {
container: string;
bind?: string;
readonly?: boolean;
}
export interface Template {
type?: number;
title: string;
description: string;
logo?: string;
image?: string;
ports?: string[];
volumes?: TemplateVolume[] | string[];
env?: TemplateEnv[];
categories?: string[];
platform?: string;
repository?: {
url: string;
stackfile: string;
};
}
export interface TemplatesResponse {
version: string;
templates: Template[];
}
export class TemplateService {
private cachedTemplates: Template[] = [];
private lastFetchTime: number = 0;
private readonly CACHE_DURATION_MS = 24 * 60 * 60 * 1000; // 24 hours
private readonly TEMPLATES_URL = 'https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json';
public async getTemplates(): Promise<Template[]> {
const now = Date.now();
if (this.cachedTemplates.length > 0 && now - this.lastFetchTime < this.CACHE_DURATION_MS) {
return this.cachedTemplates;
}
try {
const response = await axios.get<TemplatesResponse>(this.TEMPLATES_URL);
// Filter out templates without images as we are generating compose files from image, ports, etc.
this.cachedTemplates = (response.data.templates || []).filter((t: Template) => !!t.image && t.type === 1);
this.lastFetchTime = now;
return this.cachedTemplates;
} catch (error) {
console.error('Failed to fetch templates', error);
if (this.cachedTemplates.length > 0) {
return this.cachedTemplates;
}
throw new Error('Could not fetch templates from registry');
}
}
public generateComposeFromTemplate(template: Template): string {
let yaml = `services:\n app:\n`;
if (template.image) {
yaml += ` image: ${template.image}\n`;
}
yaml += ` restart: unless-stopped\n`;
if (template.ports && template.ports.length > 0) {
yaml += ` ports:\n`;
for (const port of template.ports) {
yaml += ` - "${port}"\n`;
}
}
if (template.volumes && template.volumes.length > 0) {
yaml += ` volumes:\n`;
for (const vol of template.volumes) {
if (typeof vol === 'string') {
yaml += ` - ${vol}\n`;
} else if (vol.container) {
// If bind is not provided, we extract the folder name from the container path
const containerFolder = vol.container.split('/').pop() || 'data';
const localBind = vol.bind ? vol.bind.replace(/^\//, './') : `./${containerFolder}`;
yaml += ` - ${localBind}:${vol.container}${vol.readonly ? ':ro' : ''}\n`;
}
}
}
yaml += ` env_file:\n - .env\n`;
return yaml;
}
public generateEnvString(envVars: Record<string, string>): string {
return Object.entries(envVars)
.map(([key, value]) => `${key}=${value}`)
.join('\n');
}
}
export const templateService = new TemplateService();
+17 -2
View File
@@ -28,6 +28,8 @@ import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigge
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
import { SettingsModal } from './SettingsModal';
import { StackAlertSheet } from './StackAlertSheet';
import { TemplatesView } from './TemplatesView';
interface ContainerInfo {
Id: string;
Names: string[];
@@ -76,7 +78,7 @@ export default function EditorLayout() {
}
return true; // Default to dark mode
});
const [activeView, setActiveView] = useState<'dashboard' | 'editor' | 'host-console' | 'resources'>('dashboard');
const [activeView, setActiveView] = useState<'dashboard' | 'editor' | 'host-console' | 'resources' | 'templates'>('dashboard');
const [isEditing, setIsEditing] = useState(false);
const [searchQuery, setSearchQuery] = useState('');
const [stackStatuses, setStackStatuses] = useState<StackStatus>({});
@@ -765,6 +767,17 @@ export default function EditorLayout() {
<HardDrive className="w-4 h-4 mr-2" />
Resources
</Button>
{/* Templates Toggle */}
<Button
variant="outline"
size="sm"
className="rounded-lg"
onClick={() => setActiveView('templates')}
title="App Templates"
>
<CloudDownload className="w-4 h-4 mr-2" />
Templates
</Button>
{/* Settings Modal Toggle */}
<Button
@@ -848,7 +861,9 @@ export default function EditorLayout() {
{/* Main Workspace */}
<div className="flex-1 overflow-y-auto p-6">
{activeView === 'resources' ? (
{activeView === 'templates' ? (
<TemplatesView onDeploySuccess={(stackName) => { refreshStacks(); loadFile(stackName); }} />
) : activeView === 'resources' ? (
<ResourcesView />
) : activeView === 'host-console' ? (
<HostConsole stackName={selectedFile} onClose={() => setActiveView(selectedFile ? 'editor' : 'dashboard')} />
+270
View File
@@ -0,0 +1,270 @@
import { useState, useEffect } from 'react';
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetFooter } from "@/components/ui/sheet";
import { Button } from "@/components/ui/button";
import { Search, Rocket, Loader2, Info } from "lucide-react";
import { toast } from "sonner";
export interface TemplateEnv {
name: string;
label?: string;
default?: string;
}
export interface Template {
type?: number;
title: string;
description: string;
logo?: string;
image?: string;
ports?: string[];
volumes?: any[];
env?: TemplateEnv[];
categories?: string[];
}
interface TemplatesViewProps {
onDeploySuccess: (stackName: string) => void;
}
export function TemplatesView({ onDeploySuccess }: TemplatesViewProps) {
const [templates, setTemplates] = useState<Template[]>([]);
const [searchQuery, setSearchQuery] = useState('');
const [selectedTemplate, setSelectedTemplate] = useState<Template | null>(null);
const [isSheetOpen, setIsSheetOpen] = useState(false);
const [stackName, setStackName] = useState('');
const [envVars, setEnvVars] = useState<Record<string, string>>({});
const [isDeploying, setIsDeploying] = useState(false);
const [loading, setLoading] = useState(true);
useEffect(() => {
fetchTemplates();
}, []);
const fetchTemplates = async () => {
try {
const res = await fetch('/api/templates');
if (!res.ok) throw new Error('Failed to fetch templates');
const data = await res.json();
setTemplates(data || []);
} catch (err: any) {
toast.error(err.message || "Failed to load App Shop");
} finally {
setLoading(false);
}
};
const handleSelectTemplate = (t: Template) => {
setSelectedTemplate(t);
// Init env vars with defaults
const initEnvs: Record<string, string> = {};
if (t.env && t.env.length > 0) {
t.env.forEach(e => {
initEnvs[e.name] = e.default || '';
});
}
setEnvVars(initEnvs);
// Auto-generate stack name from title
const defaultName = t.title
.toLowerCase()
.replace(/[^a-z0-9-]/g, '-')
.replace(/-+/g, '-')
.replace(/^-|-$/g, '');
setStackName(defaultName);
setIsSheetOpen(true);
};
const handleDeploy = async () => {
if (!stackName.trim()) {
toast.error("Stack name is required");
return;
}
setIsDeploying(true);
try {
const res = await fetch('/api/templates/deploy', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
stackName: stackName.trim(),
template: selectedTemplate,
envVars
})
});
const data = await res.json();
if (!res.ok) throw new Error(data.error || 'Failed to deploy template');
toast.success(`${selectedTemplate?.title} deployed successfully!`);
setIsSheetOpen(false);
onDeploySuccess(stackName.trim());
} catch (err: any) {
toast.error(err.message || 'Deployment failed');
} finally {
setIsDeploying(false);
}
};
const filtered = templates.filter(t =>
t.title.toLowerCase().includes(searchQuery.toLowerCase()) ||
t.description?.toLowerCase().includes(searchQuery.toLowerCase()) ||
(t.categories && t.categories.join(' ').toLowerCase().includes(searchQuery.toLowerCase()))
);
return (
<div className="flex flex-col h-full space-y-6">
<div className="flex items-center space-x-2">
<div className="relative flex-1">
<Search className="absolute left-2.5 top-2.5 h-4 w-4 text-muted-foreground" />
<Input
type="search"
placeholder="Search templates..."
className="pl-8"
value={searchQuery}
onChange={(e) => setSearchQuery(e.target.value)}
/>
</div>
</div>
<div className="flex-1 overflow-auto">
{loading ? (
<div className="flex items-center justify-center h-48">
<Loader2 className="w-8 h-8 animate-spin text-muted-foreground" />
</div>
) : (
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4 pb-8">
{filtered.map((t, idx) => (
<Card
key={idx}
className="cursor-pointer hover:border-primary transition-colors flex flex-col overflow-hidden h-full"
onClick={() => handleSelectTemplate(t)}
>
<CardHeader className="flex flex-row items-start gap-4 space-y-0">
<div className="w-12 h-12 rounded bg-muted/50 p-1 flex-shrink-0 flex items-center justify-center bg-white overflow-hidden">
{t.logo ? (
<img src={t.logo} alt={t.title} className="w-full h-full object-contain" />
) : (
<Rocket className="w-6 h-6 text-muted-foreground" />
)}
</div>
<div className="flex-1 min-w-0">
<CardTitle className="text-base truncate">{t.title}</CardTitle>
<p className="text-sm text-muted-foreground line-clamp-2 mt-1 min-h-[40px]">
{t.description}
</p>
</div>
</CardHeader>
{t.categories && t.categories.length > 0 && (
<CardContent className="pt-0 mt-auto">
<div className="flex flex-wrap gap-1 mt-2">
{t.categories.slice(0, 3).map(c => (
<Badge variant="secondary" key={c} className="text-[10px] px-1.5 py-0 pb-0.5">
{c}
</Badge>
))}
</div>
</CardContent>
)}
</Card>
))}
{filtered.length === 0 && (
<div className="col-span-full py-12 text-center text-muted-foreground">
<Info className="w-8 h-8 mx-auto mb-2 opacity-50" />
<p>No templates found matching "{searchQuery}"</p>
</div>
)}
</div>
)}
</div>
<Sheet open={isSheetOpen} onOpenChange={setIsSheetOpen}>
<SheetContent className="w-full sm:max-w-md overflow-y-auto" side="right">
{selectedTemplate && (
<div className="flex flex-col h-full">
<SheetHeader className="mb-6 text-left">
<div className="flex items-center gap-4 mb-4">
<div className="w-16 h-16 rounded bg-white p-1 flex-shrink-0 flex items-center justify-center overflow-hidden border">
{selectedTemplate.logo ? (
<img src={selectedTemplate.logo} alt={selectedTemplate.title} className="w-full h-full object-contain" />
) : (
<Rocket className="w-8 h-8 text-muted-foreground" />
)}
</div>
<div>
<SheetTitle className="text-xl">{selectedTemplate.title}</SheetTitle>
<SheetDescription className="line-clamp-2 mt-1">
{selectedTemplate.description}
</SheetDescription>
</div>
</div>
</SheetHeader>
<div className="space-y-6 flex-1 pr-2 pb-8">
<div className="space-y-2">
<Label htmlFor="stackName" className="font-semibold">
Stack Name <span className="text-red-500">*</span>
</Label>
<Input
id="stackName"
value={stackName}
onChange={(e) => setStackName(e.target.value)}
placeholder="e.g. my-app"
/>
<p className="text-xs text-muted-foreground">
This determines the directory name and docker project name.
</p>
</div>
{selectedTemplate.env && selectedTemplate.env.length > 0 && (
<div className="space-y-4 pt-4 border-t">
<h4 className="font-semibold">Environment Variables</h4>
{selectedTemplate.env.map((e, idx) => (
<div key={idx} className="space-y-1.5">
<Label htmlFor={`env-${e.name}`} className="text-sm">
{e.label || e.name}
</Label>
<Input
id={`env-${e.name}`}
value={envVars[e.name] !== undefined ? envVars[e.name] : ''}
onChange={(ev) => setEnvVars(prev => ({ ...prev, [e.name]: ev.target.value }))}
placeholder={e.default || `Enter value for ${e.name}`}
/>
<p className="text-[10px] text-muted-foreground font-mono">
{e.name}
</p>
</div>
))}
</div>
)}
</div>
<SheetFooter className="pt-4 mt-auto border-t sm:justify-start">
<Button
onClick={handleDeploy}
disabled={isDeploying || !stackName.trim()}
className="w-full"
size="lg"
>
{isDeploying ? (
<>
<Loader2 className="w-5 h-5 mr-2 animate-spin" />
Deploying Stack...
</>
) : (
<>
<Rocket className="w-5 h-5 mr-2" />
Deploy {selectedTemplate.title}
</>
)}
</Button>
</SheetFooter>
</div>
)}
</SheetContent>
</Sheet>
</div>
);
}