[GH-ISSUE #640] Compose file practices re. ports (vs expose) and version #2294

New Issue

GiteaMirror · 2026-04-23T03:19:18-05:00

GiteaMirror commented

2026-04-23 03:19:18 -05:00

Originally created by @dtinth on GitHub (Jan 5, 2026).
Original GitHub issue: https://github.com/Dokploy/templates/issues/640

First, thank you for all your work on Dokploy! Really enjoying it and deploying a lot of stuff with it.

I raise this issue to ask if we should improve the General Requirements when creating a template as follows:

Proposal 1 - Remove `version` property

Many templates (example) includes a version property. However, it is now obsolete and completely ignored. Deploying a service with most templates will produce with warning:

time="2026-01-05T09:44:29Z" level=warning msg="/etc/dokploy/compose/netdata-netdata-rqhquh/code/docker-compose.yml: the attribute version is obsolete, it will be ignored, please remove it to avoid potential confusion"

The proposal is to completely remove version field from all compose files. If you think this is a good idea, I can submit a PR that removes the version field from all compose files.

Proposal 2 - Use `expose` instead of `ports` for HTTP services.

netdata’s service compose file specifies:

    ports:
      - "19999" # ❌ This causes Docker to assign a random port on the host to bind to the container

This has an unintended side effect of binding a random port on the host to the port 19999 inside the container. However, this is documented in General Requirements when creating a template like this:

Don't use this way in your docker compose file:

services:
  grafana:
    image: grafana/grafana-enterprise:9.5.20
    restart: unless-stopped
    ports:
      - 3000:3000

    # Instead use this way:
    ports:
      - 3000

Since it is an HTTP service, it’s supposed to be accessed through Traefik. Therefore, I believe the intended way is to do use expose instead of ports:

    expose:
      - "19999" # ✅ Documents the intended port without binding to host.

An exception is for non-HTTP service or services that should be accessed directly (bypassing Traefik).

The proposal is to replace ports with expose for HTTP services with Domains already configured. This may have to be evaluated on a case-by-case basis. But if this is a good idea, I can submit PRs for services that I use when I found it.

Originally created by @dtinth on GitHub (Jan 5, 2026). Original GitHub issue: https://github.com/Dokploy/templates/issues/640 First, thank you for all your work on Dokploy! Really enjoying it and deploying a lot of stuff with it. I raise this issue to ask if we should improve the [General Requirements when creating a template](https://github.com/Dokploy/templates#general-requirements-when-creating-a-template) as follows: ## Proposal 1 - Remove `version` property Many templates ([example](https://github.com/Dokploy/templates/blob/canary/blueprints/netdata/docker-compose.yml)) includes a `version` property. [However, it is now obsolete and completely ignored.](https://docs.docker.com/reference/compose-file/version-and-name/) Deploying a service with most templates will produce with warning: > time="2026-01-05T09:44:29Z" level=warning msg="/etc/dokploy/compose/netdata-netdata-rqhquh/code/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion" The proposal is to completely remove `version` field from all compose files. If you think this is a good idea, I can submit a PR that removes the `version` field from all compose files. ## Proposal 2 - Use `expose` instead of `ports` for HTTP services. netdata’s service compose file specifies: ```yaml ports: - "19999" # ❌ This causes Docker to assign a random port on the host to bind to the container ``` This has an unintended side effect of binding a random port on the host to the port 19999 inside the container. However, this is documented in [General Requirements when creating a template](https://github.com/Dokploy/templates#general-requirements-when-creating-a-template) like this: <blockquote> - Don't use this way in your docker compose file: ```yaml services: grafana: image: grafana/grafana-enterprise:9.5.20 restart: unless-stopped ports: - 3000:3000 # Instead use this way: ports: - 3000 ``` </blockquote> Since it is an HTTP service, it’s supposed to be accessed through Traefik. Therefore, I believe the intended way is to do use `expose` instead of ports: ```yaml expose: - "19999" # ✅ Documents the intended port without binding to host. ``` An exception is for non-HTTP service or services that should be accessed directly (bypassing Traefik). The proposal is to replace `ports` with `expose` for HTTP services with Domains already configured. This may have to be evaluated on a case-by-case basis. But if this is a good idea, I can submit PRs for services that I use when I found it.

GiteaMirror commented

2026-04-23 03:19:19 -05:00

@bruxaodev commented on GitHub (Jan 26, 2026):

👍

@bruxaodev commented on GitHub (Jan 26, 2026): 👍

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/templates#2294

[GH-ISSUE #640] Compose file practices re. ports (vs expose) and version #2294

Proposal 1 - Remove version property

Proposal 2 - Use expose instead of ports for HTTP services.

[GH-ISSUE #640] Compose file practices re. `ports` (vs `expose`) and `version` #2294

Proposal 1 - Remove `version` property

Proposal 2 - Use `expose` instead of `ports` for HTTP services.