Adding a new service template to Coolify

Services in Coolify are templates made from normal docker-compose files with some added Coolify magic.

IMPORTANT

The service’s Git repository must have at least 1,000 stars to be added to Coolify as a one click service.

info

See Coolify's docker-compose specs to learn more about Coolify's magic and how to benefit from generated variables and storage handling. Please use this magic when submitting your PR to make the merging process smoother.

1. Add metadata

   At the top of your docker-compose file, add the following metadata:

   # documentation: https://docs.example.com/
   # slogan: A brief description of your service
   # category: One word, broad app type
   # tags: tag1,tag2,tag3
   # logo: svgs/your-service.svg
   # port: 1234

   • documentation: Link to the service's official documentation
   • slogan: A short description of the service
   • category: A one word broad app type
   • tags: Comma-separated list for better searchability
   • logo: Path to the service's logo (see step 3)
   • port: The main entrypoint port of the service

Caution

Always specify a port, as Caddy Proxy cannot automatically determine the service's port.

2. Create the docker-compose file

   Below the metadata, add your docker-compose configuration. Use Coolify's environment variable magic here.

   Example:

   services:
     app:
       image: your-service-image:tag
       environment:
         - DATABASE_URL=${COOLIFY_DATABASE_URL}
       volumes:
         - ${COOLIFY_VOLUME_APP}:/data

   Using Required Environment Variables: When creating service templates, mark critical configuration as required to improve user experience:

   services:
     app:
       image: your-service:latest
       environment:
         # Required - critical configuration that must be set by the user
         - DATABASE_URL=${DATABASE_URL:?}
         - API_KEY=${API_KEY:?}
   
         # Required with sensible defaults - improves usability
         - PORT=${PORT:?8080}
         - LOG_LEVEL=${LOG_LEVEL:?info}
   
         # Optional - features that can be left empty
         - DEBUG=${DEBUG:-false}
         - CACHE_TTL=${CACHE_TTL:-3600}

   This helps users understand which configuration is essential and prevents deployment failures.

3. Add a logo

   • Create or obtain an SVG logo for your service (strongly preferred format)
   • If SVG is unavailable, use a high-quality.webp or JPG as a last resort
   • Add the logo file to the svgs folder in the Coolify repository
   • The logo filename should match the docker-compose service name exactly
     • For example, if your service name is wordpress, your logo should be wordpress.svg and the final path then is svgs/wordpress.svg use this path in the logo metadata.

4. Test your template

   Use the Docker Compose Empty deployment option in Coolify to test your template. This process mimics the one-click service deployment.

5. Submit a Pull Request

   Once your template works correctly:

   • Open a PR
   • Add your new <service>.yaml compose file under /templates/compose
   • Include the logo file in the svgs folder
   info

   Coolify uses a parsed version of the templates for deployment.

Adding a new service template to the Coolify Documentation

Once your service template is merged into Coolify, it will be important to also add documentation for it in the Coolify docs. In the Coolify Docs Contribute section we explain how to contribute and run the documentation on your own PC.

HOW THE SERVICE LIST IS BUILT

The services overview page and the All Services directory are generated automatically from the frontmatter of each markdown file in docs/services/. You do not need to edit List.vue or all.md manually anymore. The generators run as part of bun run dev, bun run build, and bun run preview.

• scripts/generate-service-list.mjs → writes docs/.vitepress/theme/data/services.json (consumed by the services overview component)
• scripts/generate-services-page.mjs → writes docs/services/all.md
• Both scripts share scripts/services-data.mjs, which parses each service's frontmatter and resolves its logo from docs/public/images/services/

As soon as you have your local setup ready, follow these steps to add your new service:

1. Add the service logo under /docs/public/images/services/

   • Use the same base name as your service slug, e.g. my-service.svg or my-service-logo.svg. The icon resolver tries <slug>-logo, <slug>_logo, <slug>logo, then bare <slug>, then the same variants based on the title.
   • Prefer SVG; otherwise WebP, then PNG. Avoid JPEG for logos.

2. Create the documentation file

   Create /docs/services/<service-slug>.md. The slug must be lowercase and kebab-case, and must match the filename. Use this frontmatter:

   ---
   title: "Service Name"
   description: "Short description that appears on the service card and search results."
   og:
     description: "SEO/social-card description (optional, longer than `description`)."
   category: "Analytics"
   icon: "/docs/images/services/service-name-logo.svg"
   ---

   Field	Required	Notes
   title	yes	Display name shown on the card
   description	yes	Used as the card description and in all.md
   category	yes	Determines the heading the service appears under in all.md and the filter in the overview
   icon	optional	Only set if auto-resolution can't find your logo
   og.description	optional	Longer description used for social/SEO meta tags
   disabled	optional	Set to true to hide the service from the listing while keeping the page reachable by direct URL

3. Write the documentation

   Start writing your documentation under the frontmatter. Use the following template as a starting point:

   # Service Name
   
   ![Service Name](/docs/images/services/service-name-logo.svg)
   
   ## What is Service Name?
   
   Brief description and use cases.
   
   ## Links
   
   - [Official website](https://example.com?utm_source=coolify.io)
   - [GitHub](https://github.com/example/repo?utm_source=coolify.io)

   Use <ZoomableImage> only for screenshots that benefit from a zoomable view, not for the logo.

4. Regenerate the listings (optional — happens automatically on dev/build)

   bun run generate:services

   This refreshes docs/.vitepress/theme/data/services.json and docs/services/all.md. Commit both regenerated files alongside your new service page.

5. Submit a Pull Request

   • Target the next branch
   • Verify the service renders correctly with bun run dev, including the listing card, the filter category, and the entry in /services/all

Request a new service

If there's a service template you'd like to see in Coolify:

1. Search GitHub discussions for existing requests.
2. If the service has been requested, upvote it. If not, create a new request.