diff --git a/.github/.github/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md similarity index 96% rename from .github/.github/pull_request_template.md rename to .github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 4d644bf6..0c5e03d5 100644 --- a/.github/.github/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -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` \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..657ce29d --- /dev/null +++ b/CONTRIBUTING.md @@ -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! 🚀