Skip to content

docs: updates for PR #730 #736

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dosubot wants to merge 1 commit into
base: canary
Choose a base branch
from
Open

docs: updates for PR #730 #736

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,13 @@ The "why": Enables rapid, standardized deployment of 200+ OSS apps on Dokploy wi

- `meta.json`: Array of template objects. Always process after edits using `node dedupe-and-sort-meta.js` to remove duplicates (by `id`) and sort alphabetically.
- `blueprints/<service>/`:
- `docker-compose.yml`: Standard Docker Compose v3.8. Avoid `ports`, `container_name`, `networks`—Dokploy handles isolation via internal networks.
- `docker-compose.yml`: Standard Docker Compose v3.8. **NEVER use `ports` with host port mappings**—use `expose` only. Avoid `container_name`, `networks`—Dokploy handles isolation via internal networks.
- `template.toml`: Defines variables (e.g., `${domain}`), domains (service:port → host), env vars, and mounts. Use helpers like `${password:32}`, `${uuid}`, `${jwt:secret_var}`.
- `logo.svg/png`: Service icon, referenced in `meta.json`.
- `dedupe-and-sort-meta.js`: Standalone script—reads `meta.json`, removes duplicate `id`s (keeps first), sorts by `id` (case-insensitive), creates timestamped backup.
- `build-scripts/process-meta.js`: Advanced processor with CLI options (`--verbose`, `--no-backup`, `--input`/`--output`), JSON schema validation (required: `id`, `name`, `version`, `description`, `links.github`, `logo`, `tags` array).

Exemplary blueprint: `blueprints/ghost/`—`docker-compose.yml` exposes port 2368; `template.toml` maps domain to Ghost service; meta entry tags as ["blogging", "cms"].
Exemplary blueprint: `blueprints/ghost/`—`docker-compose.yml` uses `expose: ["2368"]` for port exposure; `template.toml` maps domain to Ghost service; meta entry tags as ["blogging", "cms"].
Copy link
Copy Markdown

@greptile-apps greptile-apps bot Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inaccurate exemplary blueprint description

The updated description says blueprints/ghost/docker-compose.yml uses expose: ["2368"] for port exposure, but the actual file contains no expose directive at all. Ghost's port 2368 is handled purely through the template.toml domain configuration (port = 2_368), not via an explicit expose entry in the compose file. Since this line is presented as the canonical example for AI agents to follow, an inaccurate claim here could cause generated blueprints to be structured incorrectly.

Consider updating the line to reflect what the blueprint actually does:

Suggested change
Exemplary blueprint: `blueprints/ghost/`—`docker-compose.yml` uses `expose: ["2368"]` for port exposure; `template.toml` maps domain to Ghost service; meta entry tags as ["blogging", "cms"].
Exemplary blueprint: `blueprints/ghost/`—`docker-compose.yml` defines the service (port proxied by Dokploy via `template.toml`); `template.toml` maps domain to Ghost service on port 2368; meta entry tags as ["blogging", "cms"].


## Development Workflow

Expand All @@ -33,7 +33,7 @@ Exemplary blueprint: `blueprints/ghost/`—`docker-compose.yml` exposes port 236
- **REQUIREMENT**: Service **MUST** be open source. Only add templates for applications with an open-source license (e.g., MIT, Apache, GPL, AGPL). Proprietary or closed-source services are not allowed.
- **Verify Docker Images**: Before using any Docker image in `docker-compose.yml`, verify it exists using `docker manifest inspect <image:tag>` (e.g., `docker manifest inspect docker.io/bitnami/discourse:3.5.0`). This ensures the image is available and prevents deployment failures.
- Create `blueprints/<id>/` (e.g., `ghost`).
- Implement `docker-compose.yml` (single service typical; use volumes for persistence).
- Implement `docker-compose.yml` (single service typical; use `expose` for ports, volumes for persistence).
- Configure `template.toml`—reference vars in `[config.domains]`, `[config.env]`, `[config.mounts]`.
- Add/update `meta.json` entry with exact `id` matching folder.
- Run `node dedupe-and-sort-meta.js --backup` to validate/sort.
Expand All @@ -49,7 +49,10 @@ No tests in repo—focus on manual validation via scripts and Dokploy deploys. D

- **Open Source Requirement**: **ALL services MUST be open source**. Only applications with open-source licenses (MIT, Apache, GPL, AGPL, etc.) are allowed. Proprietary or closed-source services are strictly prohibited.
- **Template IDs**: Lowercase, kebab-case (e.g., `active-pieces`); unique across repo—enforced by dedupe script.
- **Docker Compose**: Minimal—omit `ports` (Dokploy proxies), persistent volumes (e.g., `- db-data:/var/lib/postgresql/data`). Services named after folder (e.g., `ghost` service).
- **Docker Compose**:
- **Port Mappings**: **NEVER use `ports` with host port mappings** (e.g., `"8080:8080"`)—**always use `expose` only** (e.g., `expose: ["8080"]`). Dokploy handles port proxying via its internal reverse proxy, so host port bindings are unnecessary and create potential port conflicts. This applies to ALL blueprints; some older templates may still incorrectly use `ports` and should be updated to use `expose` instead.
- Use persistent volumes for data storage (e.g., `- db-data:/var/lib/postgresql/data`).
- Services named after folder (e.g., `ghost` service).
- **template.toml**:
- Variables: `[variables] main_domain = "${domain}"`; use helpers for secrets (`${password:64}`, `${base64:32}`).
- Domains: `[[config.domains]] serviceName = "<service>" port = 80 host = "${main_domain}"` (path="/" optional).
Expand Down