Skip to content

Commit decfac6

Browse files
SiumauricioSiumauricio
authored
Merge pull request #980 from Dokploy/canary
New 85 Templates
2 parents cdee0c3 + c7c84ff commit decfac6

792 files changed

Lines changed: 16909 additions & 8226 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/validate-meta.yml‎

Lines changed: 21 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
1-
name: Validate and Process Meta.json
1+
name: Validate Template Metadata
22

33
on:
44
push:
55
branches: [canary]
6-
paths: ["meta.json"]
6+
paths:
7+
- "blueprints/**"
8+
- "build-scripts/generate-meta.js"
9+
- "meta.json"
710
pull_request:
811
branches: [canary]
9-
paths: ["meta.json"]
12+
paths:
13+
- "blueprints/**"
14+
- "build-scripts/generate-meta.js"
15+
- "meta.json"
1016
workflow_dispatch:
1117

1218
jobs:
@@ -17,64 +23,19 @@ jobs:
1723
- name: Checkout repository
1824
uses: actions/checkout@v4
1925

20-
- name: Setup Node.js
21-
uses: actions/setup-node@v4
22-
with:
23-
node-version: "18"
24-
25-
- name: Validate meta.json structure
26+
- name: Reject root meta.json
2627
run: |
27-
echo "🔍 Validating meta.json structure..."
28-
node -e "
29-
const fs = require('fs');
30-
const data = JSON.parse(fs.readFileSync('meta.json', 'utf8'));
31-
if (!Array.isArray(data)) throw new Error('meta.json must be an array');
32-
console.log('✅ meta.json structure is valid');
33-
console.log('📊 Found', data.length, 'entries');
34-
"
35-
36-
- name: Check for duplicates and sort order
37-
run: |
38-
echo "🔍 Checking for duplicates and sort order..."
39-
node build-scripts/process-meta.js --verbose --output /tmp/meta-test.json
40-
41-
- name: Compare with original
42-
run: |
43-
echo "🔍 Comparing processed file with original..."
44-
if ! diff -q meta.json /tmp/meta-test.json > /dev/null; then
45-
echo "⚠️ meta.json needs processing (duplicates found or not sorted)"
46-
echo "Original entries:"
47-
node -e "console.log(JSON.parse(require('fs').readFileSync('meta.json', 'utf8')).length)"
48-
echo "Processed entries:"
49-
node -e "console.log(JSON.parse(require('fs').readFileSync('/tmp/meta-test.json', 'utf8')).length)"
50-
echo ""
51-
echo "To fix this, run: npm run process-meta"
28+
if [ -f "meta.json" ]; then
29+
echo "❌ The root meta.json is generated at build time and must not be committed."
30+
echo " Add your template's metadata to blueprints/<id>/meta.json instead."
5231
exit 1
53-
else
54-
echo "✅ meta.json is properly deduplicated and sorted"
5532
fi
33+
echo "✅ No root meta.json present"
5634
57-
- name: Validate required fields
58-
run: |
59-
echo "🔍 Validating required fields..."
60-
node -e "
61-
const fs = require('fs');
62-
const data = JSON.parse(fs.readFileSync('meta.json', 'utf8'));
63-
const required = ['id', 'name', 'version', 'description', 'links', 'logo', 'tags'];
64-
let issues = 0;
65-
66-
data.forEach((item, index) => {
67-
const missing = required.filter(field => !item[field]);
68-
if (missing.length > 0) {
69-
console.log('❌ Entry', index, '(' + item.id + '):', 'Missing fields:', missing.join(', '));
70-
issues++;
71-
}
72-
});
73-
74-
if (issues > 0) {
75-
console.log('🚨 Found', issues, 'entries with missing required fields');
76-
process.exit(1);
77-
} else {
78-
console.log('✅ All entries have required fields');
79-
}
80-
"
35+
- name: Setup Node.js
36+
uses: actions/setup-node@v4
37+
with:
38+
node-version: "20"
39+
40+
- name: Validate per-template metadata
41+
run: node build-scripts/generate-meta.js --check

‎.github/workflows/validate.yml‎

Lines changed: 6 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -49,133 +49,10 @@ jobs:
4949
echo "✅ Blueprint folders validated successfully."
5050
fi
5151
52-
- name: Validate meta.json structure and required fields
53-
run: |
54-
echo "🔍 Validating meta.json structure and required fields..."
55-
56-
# First check if meta.json exists and is valid JSON
57-
if [ ! -f "meta.json" ]; then
58-
echo "❌ meta.json file not found"
59-
exit 1
60-
fi
61-
62-
if ! jq empty meta.json 2>/dev/null; then
63-
echo "❌ meta.json is not a valid JSON file"
64-
exit 1
65-
fi
66-
67-
ERROR=0
68-
ERRORS_FOUND=""
69-
70-
# Debug: Show total number of entries
71-
TOTAL_ENTRIES=$(jq '. | length' meta.json)
72-
echo "📊 Total entries in meta.json: $TOTAL_ENTRIES"
73-
74-
# Get all entries at once and process them
75-
TOTAL_INDEX=$(($TOTAL_ENTRIES - 1))
76-
77-
for i in $(seq 0 $TOTAL_INDEX); do
78-
entry=$(jq -c ".[$i]" meta.json)
79-
INDEX=$((i + 1))
80-
81-
echo "-------------------------------------------"
82-
echo "🔍 Checking entry #$INDEX..."
83-
84-
# Get the ID for better error reporting
85-
ID=$(echo "$entry" | jq -r '.id // "UNKNOWN"')
86-
echo "📝 Processing entry with ID: $ID"
87-
88-
# Validate required top-level fields
89-
for field in "id" "name" "version" "description" "logo" "links" "tags"; do
90-
if [ "$(echo "$entry" | jq "has(\"$field\")")" != "true" ]; then
91-
ERROR_MSG="❌ Entry #$INDEX (ID: $ID) is missing required field: $field"
92-
echo "$ERROR_MSG"
93-
ERRORS_FOUND="${ERRORS_FOUND}${ERROR_MSG}\n"
94-
ERROR=1
95-
fi
96-
done
97-
98-
# Validate links object required fields
99-
if [ "$(echo "$entry" | jq 'has("links")')" == "true" ]; then
100-
for link_field in "github" "website" "docs"; do
101-
if [ "$(echo "$entry" | jq ".links | has(\"$link_field\")")" != "true" ]; then
102-
ERROR_MSG="❌ Entry #$INDEX (ID: $ID): links object is missing required field: $link_field"
103-
echo "$ERROR_MSG"
104-
ERRORS_FOUND="${ERRORS_FOUND}${ERROR_MSG}\n"
105-
ERROR=1
106-
fi
107-
done
108-
fi
109-
110-
# Validate tags array is not empty
111-
if [ "$(echo "$entry" | jq '.tags | length')" -eq 0 ]; then
112-
ERROR_MSG="❌ Entry #$INDEX (ID: $ID): tags array cannot be empty"
113-
echo "$ERROR_MSG"
114-
ERRORS_FOUND="${ERRORS_FOUND}${ERROR_MSG}\n"
115-
ERROR=1
116-
fi
117-
done
118-
119-
echo "-------------------------------------------"
120-
if [ $ERROR -eq 1 ]; then
121-
echo "❌ meta.json structure validation failed."
122-
echo -e "Summary of all errors found:${ERRORS_FOUND}"
123-
exit 1
124-
else
125-
echo "✅ meta.json structure validated successfully."
126-
fi
127-
128-
- name: Validate meta.json matches blueprint folders and logo files
129-
run: |
130-
echo "🔍 Validating meta.json against blueprint folders and logos..."
131-
132-
ERROR=0
133-
134-
# Read all blueprint folder names into an array
135-
FOLDERS=($(ls -1 blueprints))
136-
137-
# Extract ids and logos from meta.json
138-
IDS_AND_LOGOS=$(jq -c '.[] | {id, logo}' meta.json)
139-
140-
# Validate each id in meta.json exists as a folder
141-
for item in $IDS_AND_LOGOS; do
142-
ID=$(echo "$item" | jq -r '.id')
143-
LOGO=$(echo "$item" | jq -r '.logo')
144-
145-
# Check if folder exists
146-
if [ ! -d "blueprints/$ID" ]; then
147-
echo "❌ meta.json id \"$ID\" does not have a matching folder in blueprints/"
148-
ERROR=1
149-
continue
150-
fi
151-
152-
# Check if logo file exists inside its folder
153-
if [ ! -f "blueprints/$ID/$LOGO" ]; then
154-
echo "❌ Logo \"$LOGO\" defined for \"$ID\" does not exist in blueprints/$ID/"
155-
ERROR=1
156-
fi
157-
done
158-
159-
# Validate each folder has a matching id in meta.json
160-
META_IDS=$(jq -r '.[].id' meta.json)
161-
for FOLDER in "${FOLDERS[@]}"; do
162-
FOUND=0
163-
for ID in $META_IDS; do
164-
if [ "$FOLDER" == "$ID" ]; then
165-
FOUND=1
166-
break
167-
fi
168-
done
52+
- name: Setup Node.js
53+
uses: actions/setup-node@v4
54+
with:
55+
node-version: "20"
16956

170-
if [ "$FOUND" -eq 0 ]; then
171-
echo "❌ Folder \"$FOLDER\" has no matching id in meta.json"
172-
ERROR=1
173-
fi
174-
done
175-
176-
if [ $ERROR -eq 1 ]; then
177-
echo "❌ meta.json validation failed."
178-
exit 1
179-
else
180-
echo "✅ meta.json validated successfully."
181-
fi
57+
- name: Validate per-template metadata (blueprints/<id>/meta.json)
58+
run: node build-scripts/generate-meta.js --check

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
node_modules
22
package-lock.json
3-
meta.json.backup.*
3+
meta.json.backup.*

‎AGENTS.md‎

Lines changed: 19 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ This document provides essential context for AI models interacting with this pro
2929
- `/src/hooks`: Custom React hooks (e.g., `useFuseSearch.ts` for fuzzy search).
3030
- `/src/store`: Zustand state management store.
3131
- `/src/lib`: Utility functions and helpers.
32-
- `/build-scripts`: Advanced meta.json processing tools with CLI options and JSON schema validation.
32+
- `/build-scripts`: Metadata tooling — `generate-meta.js` (aggregates and validates every `blueprints/<id>/meta.json` into the served `meta.json` artifact) and `explode-meta.js` (one-shot migration reference).
3333
- `/.github/workflows`: CI/CD workflows for validation, preview builds, and deployments.
34-
- Root level: Core processing scripts (`dedupe-and-sort-meta.js`), metadata index (`meta.json`), build configuration (`Makefile`, `package.json`).
34+
- Root level: There is NO root `meta.json` in the repo — each template's metadata lives in `blueprints/<id>/meta.json` and the global registry is generated at build time.
3535
- **Module Organization:** Node.js scripts for metadata processing, React components for frontend UI, Docker Compose files for service definitions, TOML files for Dokploy configuration. Frontend uses component-based architecture with hooks for business logic and Zustand for global state.
3636

3737
## 4. Coding Conventions & Style Guide
@@ -42,7 +42,7 @@ This document provides essential context for AI models interacting with this pro
4242
- React components: PascalCase (`TemplateGrid`, `SearchBar`)
4343
- Constants: SCREAMING_SNAKE_CASE (`MAX_BUFFER_SIZE`)
4444
- Template IDs: lowercase, kebab-case (`activepieces`, `ghost`) - **MUST** be unique across repository
45-
- Files: snake_case for scripts (`dedupe-and-sort-meta.js`), PascalCase for React components (`TemplateGrid.tsx`), kebab-case for directories (`build-scripts`)
45+
- Files: kebab-case for scripts (`generate-meta.js`), PascalCase for React components (`TemplateGrid.tsx`), kebab-case for directories (`build-scripts`)
4646
- Docker services: **MUST** match blueprint folder name exactly (e.g., `ghost` service in `blueprints/ghost/`)
4747
- **API Design:**
4848
- **Backend:** Procedural scripting approach with CLI interfaces. Template system uses declarative configuration over imperative code.
@@ -65,17 +65,15 @@ This document provides essential context for AI models interacting with this pro
6565
## 5. Key Files & Entrypoints
6666

6767
- **Main Entrypoints:**
68-
- **Backend:** `dedupe-and-sort-meta.js` - Primary script for processing meta.json file.
68+
- **Backend:** `build-scripts/generate-meta.js` - Aggregates and validates all `blueprints/<id>/meta.json` files into the served `meta.json` artifact (`app/public/meta.json`, gitignored).
6969
- **Frontend:** `app/src/main.tsx` - React application entry point.
7070
- **Configuration:**
71-
- `package.json` - Root Node.js project configuration and npm scripts.
72-
- `app/package.json` - Frontend dependencies and pnpm scripts.
73-
- `meta.json` - Centralized template registry (200+ entries).
74-
- `Makefile` - Build automation with targets for processing, validation, and cleanup.
71+
- `app/package.json` - Frontend dependencies and pnpm scripts (`dev` and `build` run `generate-meta.js` first).
72+
- `blueprints/<id>/meta.json` - Per-template metadata (one object per template; 400+ templates).
7573
- `app/vite.config.ts` - Vite build configuration with static copy plugin.
7674
- `app/tsconfig.json` - TypeScript compiler configuration.
7775
- **CI/CD Pipeline:**
78-
- `.github/workflows/validate-meta.yml` - Validates meta.json structure, duplicates, and sort order.
76+
- `.github/workflows/validate-meta.yml` - Validates every `blueprints/<id>/meta.json` (via `generate-meta.js --check`) and rejects a committed root `meta.json`.
7977
- `.github/workflows/build-preview.yml` - Builds preview deployments for PRs.
8078
- `.github/workflows/deploy-preview.yml` - Deploys previews to Cloudflare Pages.
8179

@@ -92,58 +90,37 @@ This document provides essential context for AI models interacting with this pro
9290
cd app && pnpm install
9391
```
9492

95-
- **Process meta.json** (CRITICAL: Run after ANY meta.json edits)
93+
- **Validate template metadata** (CRITICAL: run after adding/editing any `blueprints/<id>/meta.json`)
9694
```bash
97-
npm run process-meta
98-
# or
99-
make process-meta
100-
# or
101-
node dedupe-and-sort-meta.js
95+
node build-scripts/generate-meta.js --check
10296
```
103-
- **Validate without modifying**
97+
- **Generate the served meta.json artifact** (done automatically by `pnpm dev` / `pnpm build` in `app/`)
10498
```bash
105-
npm run validate-meta
106-
# or
107-
make validate
108-
```
109-
- **Quick check for duplicates/sort status**
110-
```bash
111-
make check
112-
```
113-
- **Clean backup files**
114-
```bash
115-
make clean
99+
node build-scripts/generate-meta.js # writes app/public/meta.json
116100
```
117101
- **Task Configuration:**
118-
- **NPM Scripts:** Run `npm run` to list available scripts. Key scripts:
119-
- `process-meta`: Remove duplicates and sort meta.json
120-
- `process-meta-verbose`: Process with detailed output
121-
- `validate-meta`: Validate structure without changes
122-
- **Makefile Targets:** Run `make help` to list targets. Key targets:
123-
- `process-meta`: Process meta.json
124-
- `validate`: Validate without modifying
125-
- `check`: Quick duplicate/sort check
126-
- `build`: Full build process
127-
- `clean`: Remove backup files
102+
- **App scripts (`app/package.json`, pnpm):**
103+
- `dev`: Generate meta artifact + start Vite dev server
104+
- `build`: Generate meta artifact + typecheck + Vite build
105+
- `generate-meta`: Generate the meta artifact only
128106
- **Testing:** No formal unit testing framework. Validation occurs through:
129-
- Script-based validation of meta.json structure and schema
107+
- Script-based validation of every `blueprints/<id>/meta.json` (`build-scripts/generate-meta.js --check`)
130108
- Manual testing via Dokploy preview deployments (import base64 from PR preview)
131-
- JSON schema validation in `build-scripts/process-meta.js`
132109
- TypeScript compilation errors caught during build
133110
- ESLint for code quality in frontend
134111
- **CI/CD Process:**
135-
- **On meta.json changes:** Validates structure, checks for duplicates, verifies sort order, compares processed vs original.
112+
- **On blueprint changes:** Validates each template's metadata (required fields, id/folder match, logo file exists) and rejects a committed root `meta.json`.
136113
- **On PR creation:** Builds preview deployment, generates base64 import for testing in Dokploy.
137114
- **Preview testing:** Use PR description link → Search template → Copy base64 → Import in Dokploy instance.
138115
139116
## 7. Specific Instructions for AI Collaboration
140117
141118
- **Contribution Guidelines:**
142119
- Follow existing Dokploy template structure strictly. Each blueprint must be independent with no shared state.
143-
- **CRITICAL:** Always run `node dedupe-and-sort-meta.js` or `npm run process-meta` after ANY meta.json edits.
120+
- **CRITICAL:** Template metadata lives in `blueprints/<id>/meta.json` (one object per template). Never create or edit a root-level `meta.json` — it is generated at build time. Run `node build-scripts/generate-meta.js --check` after any metadata edits.
144121
- Test templates in Dokploy preview before submitting PRs (use base64 import from PR preview).
145122
- Add logo file (SVG preferred, ~128x128px) to blueprint folder.
146-
- Ensure template `id` in meta.json exactly matches blueprint folder name (lowercase kebab-case).
123+
- Ensure the `id` in `blueprints/<id>/meta.json` exactly matches the blueprint folder name (lowercase kebab-case).
147124
- **Docker Compose Conventions (CRITICAL):**
148125
149126
- **Version:** MUST be `3.8`

‎CONTRIBUTING.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -73,16 +73,16 @@ To add a new template, follow these steps:
7373
"""
7474
```
7575

76-
4. **Update `meta.json`**: Add an entry for your template in the root `meta.json`. Include:
76+
4. **Add `meta.json` in your template folder**: Create `blueprints/<id>/meta.json` with a single JSON object describing your template. Do NOT create or edit a root-level `meta.json` — the global registry is generated automatically at build time from every `blueprints/<id>/meta.json` (this is what makes template PRs conflict-free). Include:
7777

78-
- `id`: Folder name (e.g., "grafana").
78+
- `id`: Folder name (e.g., "grafana") — must match the folder exactly.
7979
- `name`: Display name.
8080
- `version`: Image/tag version.
8181
- `description`: Brief overview.
8282
- `logo`: Filename of the logo (e.g., "grafana.svg").
83-
- `links`: Object with `github`, `website`, `docs` (URLs).
83+
- `links`: Object with `github`, `website`, `docs` (URLs; use `""` if not applicable).
8484
- `tags`: Array of categories (e.g., ["monitoring"]).
85-
- Example:
85+
- Example (`blueprints/grafana/meta.json`):
8686
```json
8787
{
8888
"id": "grafana",
@@ -101,7 +101,7 @@ To add a new template, follow these steps:
101101

102102
5. **Add a Logo**: Place an SVG or PNG logo (e.g., `grafana.svg`) in the template folder. Keep it simple and representative (ideally 512x512 or similar).
103103

104-
6. **Run Validation**: Before pushing, run `node dedupe-and-sort-meta.js` (if available) or manually check for syntax errors in YAML/TOML/JSON.
104+
6. **Run Validation**: Before pushing, run `node build-scripts/generate-meta.js --check` to validate every template's metadata (same check CI runs), and manually check for syntax errors in YAML/TOML.
105105

106106
7. **Commit and PR**: Push your branch and open a PR. Include:
107107
- A description of the template.
@@ -195,7 +195,7 @@ If issues arise, debug locally or in the preview. Fix and update your PR.
195195
## Updating Existing Templates
196196

197197
- Follow the same structure as adding new ones.
198-
- Bump `version` in `meta.json` and update `docker-compose.yml` image tags.
198+
- Bump `version` in the template's `blueprints/<id>/meta.json` and update `docker-compose.yml` image tags.
199199
- Test thoroughly, as changes may affect users.
200200

201201
## Reporting Bugs or Requesting Features

0 commit comments

Comments
 (0)