mirror of
https://github.com/Dokploy/templates.git
synced 2026-06-15 20:25:24 +02:00
docs: reorganize GitHub directory structure and improve PR template (#413)
* docs: reorganize GitHub directory structure and improve PR template - Move pull_request_template.md from .github/.github/ to .github/ - Change PR template heading from markdown level 2 to level 1 - Convert README.md reference in PR template to a markdown link * chore: move pull request template to uppercase directory Relocated pull_request_template.md from .github/ to .github/PULL_REQUEST_TEMPLATE/ to align with GitHub's recommended directory structure. No content changes. * added * chore: remove outdated pull request templates for bug fixes, documentation updates, and feature additions * chore: remove outdated pull request template * chore: replace old pull request template with a new structured version * chore: add contributing guidelines for Dokploy Open Source Templates * chore: update contributing guidelines and refine pull request template - Changed validation step in contributing guidelines to use `node dedupe-and-sort-meta.js`. - Simplified pull request template by removing unnecessary sections and improving checklist formatting. --------- Co-authored-by: Mauricio Siu <47042324+Siumauricio@users.noreply.github.com>
This commit is contained in:
Jainil Prajapati
GitHub
@@ -14,4 +14,4 @@ Before submitting this PR, please make sure that:
|
||||
|
||||
Close automatically the related issues using the keywords: `closes #ISSUE_NUMBER`, `fixes #ISSUE_NUMBER`, `resolves #ISSUE_NUMBER`
|
||||
|
||||
Example: `closes #123`
|
||||
Example: `closes #123`
|
||||
209
CONTRIBUTING.md
Normal file
209
CONTRIBUTING.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# Contributing to Dokploy Open Source Templates
|
||||
|
||||
Thank you for your interest in contributing to the Dokploy Open Source Templates repository! This project maintains a collection of Docker Compose templates for easy deployment via Dokploy. Contributions help expand and improve the available templates for the community.
|
||||
|
||||
We welcome contributions in the form of new templates, improvements to existing ones, bug fixes, documentation updates, and more. Please follow the guidelines below to ensure a smooth review and integration process.
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
This project adheres to the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). By participating, you are expected to uphold this code. Reports of unacceptable behavior can be directed to the project maintainers.
|
||||
|
||||
## How to Contribute
|
||||
|
||||
1. **Fork the Repository**: Start by forking this repository to your GitHub account.
|
||||
2. **Create a New Branch**: From your fork, create a feature branch named descriptively (e.g., `add-grafana-template`).
|
||||
3. **Make Your Changes**: Follow the specific guidelines for the type of contribution (e.g., adding a template).
|
||||
4. **Commit and Push**: Commit your changes with clear, concise messages. Push the branch to your fork.
|
||||
5. **Open a Pull Request (PR)**: Create a PR from your branch to the main repository. Reference any related issues in the PR description.
|
||||
6. **Automated Preview**: Every PR automatically deploys a preview of your template to Dokploy. You can test it before merging (see "Testing Your Contribution" below).
|
||||
7. **Review and Merge**: Respond to feedback from maintainers. Once approved, your changes will be merged.
|
||||
|
||||
For larger changes or questions, open an issue first to discuss your ideas.
|
||||
|
||||
## Adding a New Template
|
||||
|
||||
To add a new template, follow these steps:
|
||||
|
||||
1. **Create a Folder in `blueprints/`**: Name it after the template (e.g., `grafana`). Use lowercase with hyphens for multi-word names.
|
||||
2. **Add `docker-compose.yml`**: Define the services, volumes, and other Compose configurations. Key guidelines:
|
||||
|
||||
- Use `version: "3.8"` or later.
|
||||
- Avoid exposing ports explicitly (e.g., no `ports: - "3000:3000"`; just `- 3000` if needed for internal reference).
|
||||
- Do not use `container_name`.
|
||||
- Avoid custom networks like `dokploy-network`; Dokploy handles isolation automatically.
|
||||
- Example for Grafana:
|
||||
```yaml
|
||||
version: "3.8"
|
||||
services:
|
||||
grafana:
|
||||
image: grafana/grafana-enterprise:9.5.20
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- grafana-storage:/var/lib/grafana
|
||||
volumes:
|
||||
grafana-storage: {}
|
||||
```
|
||||
|
||||
3. **Add `template.toml`**: Configure domains, environment variables, mounts, and variables. This file is crucial for Dokploy integration.
|
||||
|
||||
- Sections: `[variables]` (optional), `[config]` with `[[config.domains]]`, `[[config.env]]`, `[[config.mounts]]`.
|
||||
- Use `${variable}` syntax to reference variables or helpers (e.g., `${domain}`, `${password:32}`).
|
||||
- Match `serviceName` in domains to the service name in `docker-compose.yml`.
|
||||
- Example for Grafana:
|
||||
|
||||
```toml
|
||||
[variables]
|
||||
main_domain = "${domain}"
|
||||
|
||||
[config]
|
||||
[[config.domains]]
|
||||
serviceName = "grafana"
|
||||
port = 3000
|
||||
host = "${main_domain}"
|
||||
|
||||
[[config.mounts]]
|
||||
filePath = "/content/file.txt"
|
||||
content = """
|
||||
My content
|
||||
"""
|
||||
```
|
||||
|
||||
4. **Update `meta.json`**: Add an entry for your template in the root `meta.json`. Include:
|
||||
|
||||
- `id`: Folder name (e.g., "grafana").
|
||||
- `name`: Display name.
|
||||
- `version`: Image/tag version.
|
||||
- `description`: Brief overview.
|
||||
- `logo`: Filename of the logo (e.g., "grafana.svg").
|
||||
- `links`: Object with `github`, `website`, `docs` (URLs).
|
||||
- `tags`: Array of categories (e.g., ["monitoring"]).
|
||||
- Example:
|
||||
```json
|
||||
{
|
||||
"id": "grafana",
|
||||
"name": "Grafana",
|
||||
"version": "9.5.20",
|
||||
"description": "Grafana is an open source platform for data visualization and monitoring.",
|
||||
"logo": "grafana.svg",
|
||||
"links": {
|
||||
"github": "https://github.com/grafana/grafana",
|
||||
"website": "https://grafana.com/",
|
||||
"docs": "https://grafana.com/docs/"
|
||||
},
|
||||
"tags": ["monitoring"]
|
||||
}
|
||||
```
|
||||
|
||||
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).
|
||||
|
||||
6. **Run Validation**: Before pushing, run `node dedupe-and-sort-meta.js` (if available) or manually check for syntax errors in YAML/TOML/JSON.
|
||||
|
||||
7. **Commit and PR**: Push your branch and open a PR. Include:
|
||||
- A description of the template.
|
||||
- The preview URL (auto-generated).
|
||||
- Any testing notes.
|
||||
|
||||
## Template.toml Structure
|
||||
|
||||
- **[variables]**: Define reusable values or use helpers.
|
||||
Example:
|
||||
|
||||
```toml
|
||||
[variables]
|
||||
main_domain = "${domain}"
|
||||
my_password = "${password:32}"
|
||||
```
|
||||
|
||||
- **[config.domains]**: Map services to domains/ports.
|
||||
|
||||
- Required: `serviceName`, `port`, `host`.
|
||||
- Optional: `path`.
|
||||
|
||||
- **[config.env]**: Array of environment variables (strings).
|
||||
Example: `env = ["GF_SECURITY_ADMIN_PASSWORD=${password:32}"]`
|
||||
|
||||
- **[config.mounts]**: Inline files or configs.
|
||||
- `filePath`: Destination in container.
|
||||
- `content`: Multi-line string.
|
||||
|
||||
### Helpers
|
||||
|
||||
Use these in `${}` for dynamic values:
|
||||
|
||||
- `${domain}`: Random subdomain.
|
||||
- `${password:length}`: Random password (default 32 chars).
|
||||
- `${base64:length}`: Base64-encoded random string.
|
||||
- `${hash:length}`: Random hash.
|
||||
- `${uuid}`: UUID.
|
||||
- `${randomPort}`: Random port.
|
||||
- `${email}`: Random email.
|
||||
- `${username}`: Random lowercase username.
|
||||
- `${timestamp}`: Current timestamp (ms).
|
||||
- `${timestamps:datetime}` or `${timestampms:datetime}`: Timestamp at specific date (e.g., `${timestamps:2030-01-01T00:00:00Z}`).
|
||||
- `${jwt:secret_var:payload_var}`: JWT token (advanced; see README for details).
|
||||
|
||||
## Best Practices and Suggestions
|
||||
|
||||
- **Docker Compose**:
|
||||
|
||||
- Omit explicit ports; let Dokploy handle exposure.
|
||||
- Use persistent volumes for data (e.g., databases).
|
||||
- Set `restart: unless-stopped` for services.
|
||||
|
||||
- **Template.toml**:
|
||||
|
||||
- Keep service names consistent across files.
|
||||
- Use variables/helpers for secrets (e.g., passwords, API keys).
|
||||
- Minimize env vars; only include essentials.
|
||||
|
||||
- **General**:
|
||||
|
||||
- Templates should be self-contained and deployable out-of-the-box.
|
||||
- Use official/latest stable images.
|
||||
- Avoid hardcoding domains, networks, or secrets.
|
||||
- Ensure compatibility with Dokploy's isolated deployments.
|
||||
|
||||
- **Logo and Metadata**:
|
||||
- Logos should be vector (SVG preferred) or high-res PNG.
|
||||
- Descriptions: 1-2 sentences, SEO-friendly.
|
||||
- Tags: Relevant categories (e.g., "database", "web", "monitoring").
|
||||
|
||||
## Testing Your Contribution
|
||||
|
||||
Before submitting a PR:
|
||||
|
||||
1. Run the project locally:
|
||||
```bash
|
||||
cd app
|
||||
pnpm install
|
||||
pnpm run dev
|
||||
# Visit http://localhost:5173/
|
||||
```
|
||||
2. Use the PR preview:
|
||||
- After pushing, check the PR for the auto-generated preview URL.
|
||||
- Search for your template, copy the Base64 config.
|
||||
- In your Dokploy instance: Create a Compose service > Advanced > Import > Paste Base64 > Deploy.
|
||||
- Verify the service starts and is accessible (e.g., via assigned domain).
|
||||
3. Test edge cases: Restart, volume persistence, env vars.
|
||||
|
||||
If issues arise, debug locally or in the preview. Fix and update your PR.
|
||||
|
||||
## Updating Existing Templates
|
||||
|
||||
- Follow the same structure as adding new ones.
|
||||
- Bump `version` in `meta.json` and update `docker-compose.yml` image tags.
|
||||
- Test thoroughly, as changes may affect users.
|
||||
|
||||
## Reporting Bugs or Requesting Features
|
||||
|
||||
- Open an issue with:
|
||||
- Clear title and description.
|
||||
- Steps to reproduce (for bugs).
|
||||
- Template details (for feature requests).
|
||||
- Use the issue templates in `.github/ISSUE_TEMPLATE/`.
|
||||
|
||||
## Questions?
|
||||
|
||||
If you're unsure about anything, open a discussion or issue. We're here to help!
|
||||
|
||||
Happy contributing! 🚀
|
||||
Reference in New Issue
Block a user