From 3ecbbe526ebe09b8830fd97566844e11e457e17c Mon Sep 17 00:00:00 2001 From: hhftechnologies Date: Fri, 21 Nov 2025 10:50:41 +0530 Subject: [PATCH] new-template --- .github/ISSUE_TEMPLATE/bug-report.yml | 17 ++- .github/ISSUE_TEMPLATE/feature-request.yml | 128 +++++++++++++++--- .../pull_request_template.md | 57 +++++++- README.md | 116 ++++++++++++++-- compose-files/services/nginx/.env | 15 ++ compose-files/services/nginx/.env.example | 15 ++ compose-files/services/nginx/README.md | 32 +++++ .../services/nginx/docker-compose.yml | 14 ++ compose-files/services/nginx/template.toml | 44 ++++++ compose-files/services/redis/.env.example | 15 ++ compose-files/services/redis/README.md | 44 ++++++ .../services/redis/docker-compose.yml | 27 ++++ compose-files/services/redis/template.toml | 18 +++ 13 files changed, 502 insertions(+), 40 deletions(-) create mode 100644 compose-files/services/nginx/.env create mode 100644 compose-files/services/nginx/.env.example create mode 100644 compose-files/services/nginx/README.md create mode 100644 compose-files/services/nginx/docker-compose.yml create mode 100644 compose-files/services/nginx/template.toml create mode 100644 compose-files/services/redis/.env.example create mode 100644 compose-files/services/redis/README.md create mode 100644 compose-files/services/redis/docker-compose.yml create mode 100644 compose-files/services/redis/template.toml diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml index 664eb28..bd14b05 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -11,9 +11,20 @@ body: - type: input attributes: - label: Template Name - description: Which template is experiencing the bug? - placeholder: "e.g: Adguard, Appwrite, Plausible, etc." + label: Service/Template Name + description: Which service or template is experiencing the bug? + placeholder: "e.g: nginx, redis, adguard, etc." + validations: + required: true + + - type: dropdown + attributes: + label: Structure Type + description: Which structure format is this service using? + options: + - "Flat file (compose-files/service-name.yml)" + - "Folder structure (compose-files/services/service-name/)" + - "Not sure" validations: required: true diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml index e1916e2..5974209 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.yml +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -2,48 +2,136 @@ name: New Template Request description: Suggest a new template for the project labels: ["template"] body: + - type: markdown + attributes: + value: | + Before submitting, please review the [README.md](https://github.com/hhftechnology/Marketplace/blob/main/README.md) to understand the repository structure and submission guidelines. + - type: input attributes: - label: Template Name - description: Provide a clear and descriptive name for the template - placeholder: "e.g: Adguard, Appwrite, etc." + label: Service Name + description: Provide a clear and descriptive name for the service/template + placeholder: "e.g: nginx, redis, postgres, etc." validations: required: true - - type: input + - type: dropdown attributes: - label: Template URL - description: Link to the repository or resource where the template is located - placeholder: "https://github.com/username/repo" + label: Structure Preference + description: Choose the structure format for this service + options: + - "Flat file (compose-files/service-name.yml)" + - "Folder structure (compose-files/services/service-name/)" + - "No preference" validations: required: true - - type: input + - type: textarea attributes: - label: Docker Compose Link - description: Link to docker-compose.yml file or Docker documentation (optional) but would be helpful - placeholder: "https://github.com/username/repo/blob/main/docker-compose.yml" + label: Docker Compose Configuration + description: | + Paste your complete `docker-compose.yml` configuration here. + + **Guidelines:** + - Include inline comments (ScaleTail style) for clarity + - Use `${VARIABLE_NAME}` syntax for configurable values + - Use descriptive volume placeholders (e.g., `/WORK_DIR` instead of absolute paths) + - Set timezone to `Etc/UTC` by default + placeholder: | + ```yaml + services: + service-name: + image: service:latest + container_name: service-name + restart: unless-stopped + ports: + - "${PORT:-8080}:8080" # Service port + environment: + - SERVICE_VAR=${SERVICE_VAR} + ``` + validations: + required: true + + - type: textarea + attributes: + label: Template Metadata (Optional - Folder Structure Only) + description: | + If using folder structure and the service needs template variables, domain configuration, or custom mounts, provide the `template.toml` content here. + + See examples in `compose-files/services/nginx/template.toml` or `compose-files/services/redis/template.toml` + placeholder: | + ```toml + [variables] + main_domain = "${domain}" + service_port = "80" + + [config] + [[config.domains]] + serviceName = "service-name" + port = 80 + host = "${main_domain}" + path = "/" + ``` validations: required: false - type: textarea attributes: - label: Resources - description: List the resources, links, or any other information that would be helpful to know about the template + label: Environment Variables Example (Optional - Folder Structure Only) + description: | + If using folder structure and the service has environment variables, provide the `.env.example` content here. + + See examples in the service folders for the format. placeholder: | - - Link to the template - - Link to the documentation - - Link to the repository - - Link to the website + ```bash + # Service Configuration + SERVICE=service-name + IMAGE_URL=service:latest + SERVICEPORT=8080 + + # Template Variables + MAIN_DOMAIN=example.com + ``` validations: required: false - type: textarea attributes: - label: Template Description - description: Provide a detailed description of what this template does and when to use it + label: Service Documentation (Optional - Folder Structure Only) + description: | + If using folder structure, provide a README.md content with setup instructions, features, and usage notes. placeholder: | - This template is perfect for creating modern web applications with React and TypeScript... + # Service Name + + Brief description of the service. + + ## Features + - Feature 1 + - Feature 2 + + ## Configuration + Setup instructions... + validations: + required: false + + - type: textarea + attributes: + label: Resources and References + description: List the resources, links, or any other information that would be helpful + placeholder: | + - Link to official documentation + - Link to Docker Hub page + - Link to GitHub repository + - Link to website + validations: + required: false + + - type: textarea + attributes: + label: Service Description + description: Provide a detailed description of what this service does and when to use it + placeholder: | + This service is perfect for [use case]... validations: required: false diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index e2bea6e..04ec12d 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -1,16 +1,63 @@ ## What is this PR about? -New PR of [Template Name] + +- [ ] New service/template +- [ ] Update to existing service +- [ ] Bug fix +- [ ] Documentation update +- [ ] Other (please describe) + +**Service Name:** [e.g., nginx, redis, postgres] + +**Structure Type:** +- [ ] Flat file (`compose-files/service-name.yml`) +- [ ] Folder structure (`compose-files/services/service-name/`) ## Checklist Before submitting this PR, please make sure that: -- [ ] I have read the suggestions in the README.md file https://github.com/hhftechnology/Marketplace?tab=readme#general-suggestions-when-creating-a-template -- [ ] I have tested the template in my instance, so the maintainers don't spend time trying to figure out what's wrong. -- [ ] I have added tests that demonstrate that my correction works or that my new feature works. +### General Requirements +- [ ] I have read the [README.md](https://github.com/hhftechnology/Marketplace/blob/main/README.md) and followed the submission guidelines +- [ ] I have tested the template/service in my instance +- [ ] The Docker image(s) are publicly accessible (no private registries) +- [ ] I have used `${VARIABLE_NAME}` syntax for configurable values +- [ ] I have used descriptive volume placeholders (e.g., `/WORK_DIR` instead of absolute paths) +- [ ] Timezone is set to `Etc/UTC` (if applicable) -## Issues related (if applicable) +### Docker Compose File +- [ ] Includes inline comments (ScaleTail style) for clarity +- [ ] Minimized unnecessary ports, environment variables, or configurations +- [ ] Uses `latest` tag where possible (or specific version if required) +- [ ] Multi-service support is properly configured (if applicable) + +### Folder Structure (If Applicable) +- [ ] `docker-compose.yml` is included and properly formatted +- [ ] `template.toml` is included (if template variables/domain config needed) +- [ ] `.env.example` is included (if environment variables are needed) +- [ ] `README.md` is included (if detailed setup instructions are needed) + +### Testing +- [ ] I have tested the service deployment +- [ ] I have verified all environment variables work correctly +- [ ] I have checked that volumes and ports are correctly configured +- [ ] I have verified the service starts and runs without errors + +## Files Changed + + +- `compose-files/[service-name].yml` (flat file structure) +- OR +- `compose-files/services/[service-name]/docker-compose.yml` +- `compose-files/services/[service-name]/template.toml` (if applicable) +- `compose-files/services/[service-name]/.env.example` (if applicable) +- `compose-files/services/[service-name]/README.md` (if applicable) + +## Additional Notes + + + +## Issues Related (if applicable) Close automatically the related issues using the keywords: `closes #ISSUE_NUMBER`, `fixes #ISSUE_NUMBER`, `resolves #ISSUE_NUMBER` diff --git a/README.md b/README.md index d1efa31..0737e35 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,36 @@ -# How to Contribute +# Marketplace Repository + +A collection of Docker Compose files for self-hosted services, supporting both traditional flat file structure and the new folder-based structure with template support. + +## Repository Structure + +This repository supports a **hybrid approach** that maintains backward compatibility while enabling advanced features: + +### Option 1: Folder Structure (Recommended - New Format) + +``` +compose-files/ +└── services/ + ├── nginx/ + │ ├── docker-compose.yml # Main compose file + │ ├── template.toml # Template metadata (optional) + │ ├── .env.example # Example env file (optional) + │ └── README.md # Service docs (optional) + │ + └── redis/ + ├── docker-compose.yml + ├── template.toml + └── .env.example +``` + +### File Formats + +- **docker-compose.yml**: Standard Docker Compose file with comments (ScaleTail style) +- **template.toml**: Dokploy-style template metadata for template variables and domain configuration (optional) +- **.env.example**: ScaleTail-style environment file with comments showing required variables (optional) +- **README.md**: Service-specific documentation (optional) + +## How to Contribute The Marketplace is a community-driven project. We welcome contributions from everyone! To add a new self-hosted service or update an existing one, please open a GitHub [Issue](https://github.com/hhftechnology/Marketplace/issues) using the template below. This helps us review and integrate your submission efficiently. @@ -7,30 +39,90 @@ The Marketplace is a community-driven project. We welcome contributions from eve Use this structure in your issue description: ### Service Name + [Enter the name of the service, e.g., `nginx` or `redis`. Keep it concise and descriptive.] +### Structure Preference + +[Choose one:] + +- **Flat file**: Simple `service-name.yml` in `compose-files/` +- **Folder structure**: `compose-files/services/service-name/` with `docker-compose.yml` and optional files + ### Example docker-compose.yml + ```yaml -[Paste a complete, working `docker-compose.yml` configuration here. Use code block formatting for readability.] +[ + Paste a complete, + working `docker-compose.yml` configuration here. Use code block formatting for readability., +] ``` +### Optional Files (Folder Structure Only) + +If using folder structure, you may include: + +**template.toml** (if template variables are needed): + +```toml +[variables] +main_domain = "${domain}" +service_port = "80" + +[config] +[[config.domains]] +serviceName = "nginx" +port = 80 +host = "${main_domain}" +path = "/" + +[config.env] +NGINX_HOST = "${main_domain}" +``` + +**.env.example** (if environment variables are needed): + +```bash +# Service Configuration +SERVICE=nginx +IMAGE_URL=nginx:latest +SERVICEPORT=80 + +# Template Variables +MAIN_DOMAIN=example.com +``` + +**README.md** (service documentation): +[Service-specific setup instructions, features, and usage notes] + ### Documentation or References + [Provide links to official documentation, Docker Hub pages, GitHub repositories, or other relevant resources.] ### Notes + [Any additional context, setup instructions, or caveats. If this is an update to an existing service, prefix with "Update: " and describe the changes.] ## Submission Guidelines -Before opening your issue, please verify that your `docker-compose.yml` meets these standards to streamline the review process: +Before opening your issue, please verify that your submission meets these standards to streamline the review process: -- **Remove comments**: Strip out all inline comments from the file for cleanliness. -- **Minimize extras**: Eliminate unnecessary ports, environment variables, volumes, or other configurations. -- **Public images only**: Ensure the Docker image(s) are publicly accessible (no private registries). -- **Inline environment variables**: Include all required environment variables directly in the file—do not reference external `.env` files. -- **Prefer latest tags**: Use the `latest` image tag where possible, unless a specific version is required for stability. -- **Multi-service support**: It's okay to include multiple related services in one compose file (e.g., a main app + dependencies), as long as they function together. -- **Standardize volumes**: Replace absolute host paths with descriptive, uppercase placeholders (e.g., change `/data/adguard-home/work:/opt/adguardhome/work` to `/WORK_DIR:/opt/adguardhome/work`). -- **Set timezone**: Default to `Etc/UTC` for consistency across environments. +### Docker Compose File Requirements -Once your issue is submitted, a maintainer will review it and merge the changes into the main repository. Thank you for helping grow the Marketplace—your contributions make it better for everyone! If you have questions, feel free to comment on an existing issue or discuss in the repo's Discussions section. \ No newline at end of file +- **Comments allowed**: Inline comments are welcome and encouraged (ScaleTail style) for clarity +- **Minimize extras**: Eliminate unnecessary ports, environment variables, volumes, or other configurations +- **Public images only**: Ensure the Docker image(s) are publicly accessible (no private registries) +- **Environment variables**: Use `${VARIABLE_NAME}` syntax for configurable values +- **Prefer latest tags**: Use the `latest` image tag where possible, unless a specific version is required for stability +- **Multi-service support**: It's okay to include multiple related services in one compose file (e.g., a main app + dependencies), as long as they function together +- **Standardize volumes**: Replace absolute host paths with descriptive, uppercase placeholders (e.g., change `/data/adguard-home/work:/opt/adguardhome/work` to `/WORK_DIR:/opt/adguardhome/work`) +- **Set timezone**: Default to `Etc/UTC` for consistency across environments + +### Folder Structure Requirements (If Using) + +- **docker-compose.yml**: Required - Main compose file +- **template.toml**: Optional - Include if service needs template variables, domain configuration, or custom mounts +- **.env.example**: Optional - Include if service has environment variables that users need to configure +- **README.md**: Optional - Include for services that need detailed setup instructions or have special requirements + +Once your issue is submitted, a maintainer will review it and merge the changes into the main repository. Thank you for helping grow the Marketplace—your contributions make it better for everyone! If you have questions, feel free to comment on an existing issue or discuss in the repo's Discussions section. diff --git a/compose-files/services/nginx/.env b/compose-files/services/nginx/.env new file mode 100644 index 0000000..df57b7b --- /dev/null +++ b/compose-files/services/nginx/.env @@ -0,0 +1,15 @@ +# .env file for nginx service +# Make sure you have updated/checked the .env file with the correct variables. +# All the need to be defined here. + +# Service Configuration +SERVICE=nginx +IMAGE_URL=nginx:latest +SERVICEPORT=80 + +# Template Variables +MAIN_DOMAIN=example.com +NGINX_PORT=80 + +# DNS Configuration +DNS_SERVER=9.9.9.9 diff --git a/compose-files/services/nginx/.env.example b/compose-files/services/nginx/.env.example new file mode 100644 index 0000000..d99e2dc --- /dev/null +++ b/compose-files/services/nginx/.env.example @@ -0,0 +1,15 @@ +# .env file for nginx service +# Make sure you have updated/checked the .env file with the correct variables. +# All the ${ xx } need to be defined here. + +# Service Configuration +SERVICE=nginx +IMAGE_URL=nginx:latest +SERVICEPORT=80 + +# Template Variables +MAIN_DOMAIN=example.com +NGINX_PORT=80 + +# DNS Configuration +DNS_SERVER=9.9.9.9 diff --git a/compose-files/services/nginx/README.md b/compose-files/services/nginx/README.md new file mode 100644 index 0000000..5cf6d3f --- /dev/null +++ b/compose-files/services/nginx/README.md @@ -0,0 +1,32 @@ +# Nginx Service + +A lightweight and high-performance web server and reverse proxy. + +## Features + +- HTTP/HTTPS web server +- Reverse proxy capabilities +- Load balancing +- SSL/TLS termination + +## Configuration + +1. Copy `.env.example` to `.env` and update the variables +2. Update the `template.toml` if using template variables +3. Customize nginx configuration in the mounted volume + +## Usage + +```bash +docker-compose up -d +``` + +## Ports + +- `80`: HTTP port (configurable via `NGINX_PORT`) + +## Environment Variables + +- `NGINX_HOST`: Domain name for the nginx server +- `NGINX_PORT`: Port number for HTTP (default: 80) + diff --git a/compose-files/services/nginx/docker-compose.yml b/compose-files/services/nginx/docker-compose.yml new file mode 100644 index 0000000..ec829d4 --- /dev/null +++ b/compose-files/services/nginx/docker-compose.yml @@ -0,0 +1,14 @@ +# nginx service +# Image: nginx:latest +services: + nginx: + image: nginx:latest + container_name: nginx + restart: unless-stopped + ports: + - "${NGINX_PORT:-80}:80" # HTTP port + volumes: + - ./config:/etc/nginx/conf.d # Nginx configuration + environment: + - NGINX_HOST=${NGINX_HOST} + - NGINX_PORT=${NGINX_PORT} diff --git a/compose-files/services/nginx/template.toml b/compose-files/services/nginx/template.toml new file mode 100644 index 0000000..bb0de8a --- /dev/null +++ b/compose-files/services/nginx/template.toml @@ -0,0 +1,44 @@ +[variables] +main_domain = "${domain}" +nginx_port = "80" + +[config] +[[config.domains]] +serviceName = "nginx" +port = 80 +host = "${main_domain}" +path = "/" + +[config.env] +NGINX_HOST = "${main_domain}" +NGINX_PORT = "${nginx_port}" + +[[config.mounts]] +filePath = "/etc/nginx/nginx.conf" +content = """ +# Custom nginx config +user nginx; +worker_processes auto; +error_log /var/log/nginx/error.log; +pid /var/run/nginx.pid; + +events { + worker_connections 1024; +} + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + + server { + listen 80; + server_name ${main_domain}; + + location / { + root /usr/share/nginx/html; + index index.html; + } + } +} +""" + diff --git a/compose-files/services/redis/.env.example b/compose-files/services/redis/.env.example new file mode 100644 index 0000000..b8149b3 --- /dev/null +++ b/compose-files/services/redis/.env.example @@ -0,0 +1,15 @@ +# .env file for redis service +# Make sure you have updated/checked the .env file with the correct variables. +# All the ${ xx } need to be defined here. + +# Service Configuration +SERVICE=redis +REDIS_PORT=6379 +REDIS_INSIGHT_PORT=8001 + +# Template Variables +MAIN_DOMAIN=example.com +REDIS_PASSWORD=your_secure_password_here + +# DNS Configuration +DNS_SERVER=9.9.9.9 diff --git a/compose-files/services/redis/README.md b/compose-files/services/redis/README.md new file mode 100644 index 0000000..ecd2c74 --- /dev/null +++ b/compose-files/services/redis/README.md @@ -0,0 +1,44 @@ +# Redis Service + +An in-memory data structure store, used as a database, cache, and message broker. + +## Features + +- In-memory data storage +- Data persistence with AOF (Append Only File) +- Redis Insight web UI for monitoring and management +- High-performance caching + +## Configuration + +1. Copy `.env.example` to `.env` and update the variables +2. Set a secure `REDIS_PASSWORD` for production use +3. Update the `template.toml` if using template variables + +## Usage + +```bash +docker-compose up -d +``` + +## Ports + +- `6379`: Redis server port (configurable via `REDIS_PORT`) +- `8001`: Redis Insight web UI port (configurable via `REDIS_INSIGHT_PORT`) + +## Environment Variables + +- `REDIS_PORT`: Redis server port (default: 6379) +- `REDIS_INSIGHT_PORT`: Redis Insight web UI port (default: 8001) +- `REDIS_PASSWORD`: Password for Redis authentication (optional but recommended) + +## Access + +- Redis CLI: `redis-cli -h localhost -p 6379` +- Redis Insight: `http://localhost:8001` or `http://${MAIN_DOMAIN}/redis` + +## Volumes + +- `redis_volume_data`: Persistent storage for Redis data +- `redis_insight_volume_data`: Persistent storage for Redis Insight data + diff --git a/compose-files/services/redis/docker-compose.yml b/compose-files/services/redis/docker-compose.yml new file mode 100644 index 0000000..d239a47 --- /dev/null +++ b/compose-files/services/redis/docker-compose.yml @@ -0,0 +1,27 @@ +# redis service +# Image: redis:6.0.7 +services: + redis: + image: redis:6.0.7 + container_name: redis + restart: unless-stopped + volumes: + - redis_volume_data:/data # Redis data persistence + ports: + - "${REDIS_PORT:-6379}:6379" # Redis default port + environment: + - REDIS_PASSWORD=${REDIS_PASSWORD:-} + command: redis-server --appendonly yes + redis_insight: + image: redislabs/redisinsight:1.14.0 + container_name: redis_insight + restart: unless-stopped + ports: + - "${REDIS_INSIGHT_PORT:-8001}:8001" # Redis Insight web UI + volumes: + - redis_insight_volume_data:/db # Redis Insight data + +volumes: + redis_volume_data: + redis_insight_volume_data: + diff --git a/compose-files/services/redis/template.toml b/compose-files/services/redis/template.toml new file mode 100644 index 0000000..0024842 --- /dev/null +++ b/compose-files/services/redis/template.toml @@ -0,0 +1,18 @@ +[variables] +main_domain = "${domain}" +redis_port = "6379" +redis_insight_port = "8001" +redis_password = "${redis_password}" + +[config] +[[config.domains]] +serviceName = "redis_insight" +port = 8001 +host = "${main_domain}" +path = "/redis" + +[config.env] +REDIS_PORT = "${redis_port}" +REDIS_INSIGHT_PORT = "${redis_insight_port}" +REDIS_PASSWORD = "${redis_password}" +