Why isn’t port mapping applied when defined directly in docker-compose.yml for NetBox?

Below is some explanation on why adding the ports mapping directly in docker-compose.yml may not appear to work as expected:

---

Merging Behavior of Docker Compose Files

Docker Compose automatically reads both docker-compose.yml and docker-compose.override.yml (if it exists) and merges them. The official documentation sometimes suggests using an override file so that host-specific settings (like port mapping) remain separate from the “upstream” service definition. In the merged configuration, settings in docker-compose.override.yml have a higher priority.

Key point: There isn’t any intrinsic “magic” that makes ports work only when defined in the override file. It’s simply that if you have an override file present, its settings will be applied on top of what is in docker-compose.yml. When you move the ports directive into docker-compose.yml, you have to be careful that nothing else (for example, another config file or external variable) ends up overriding it at run time.

---

Possible Sources of the Issue

1. Multiple Composition Files
   If you still have a docker-compose.override.yml (or other compose files) present that do not define the ports mapping, those files may be overriding or “erasing” the ports mapping from your main file. Make sure you remove or update the override file when moving the configuration into docker-compose.yml.

2. Order and Merging Rules
   Docker Compose merges mappings (like lists) by appending. However, in some cases, if your service is defined in several places, the final merged configuration might not be what you expect. Verify that your docker-compose.yml is the only file being applied or that the merging follows your desired outcome.

3. Application Listening on the Expected Port
   The NetBox container (based on the official image) exposes port 8080 internally and the override file maps host port 8000 to container port 8080. Double-check that the container is indeed listening on port 8080. You can inspect this in the container logs or by running an interactive shell inside the container.

4. Docker Compose File Version/Format
   Although less likely, ensure your docker-compose.yml declares a version (or uses the Compose file format appropriate for your Docker Compose version). An incorrectly formatted file might result in unexpected behavior.

---

Recommendations

• Check for leftover override files:
  Remove or update docker-compose.override.yml to prevent it from interfering with your main docker-compose.yml settings.

• Verify Effective Configuration:
  Run the following command to inspect the merged configuration:

  BASHCopied
  docker-compose config

  This command prints the final configuration that Docker Compose uses. Confirm that the port mapping (8000:8080) appears under the netbox service.

• Test Container Connectivity:
  Make sure that the NetBox container is healthy and that the application is binding to port 8080. You can run a shell inside the container to test if the application is reachable on port 8080.

• Consider the Separation of Concerns:
  A benefit of keeping host-specific configuration (like port bindings) in an override file is that it decouples changes needed on different hosts from the service’s “upstream” definition. If everything is in a single file, you must be extra sure that no external settings conflict with yours.

---

Conclusion

There is no inherent requirement that forces you to use docker-compose.override.yml for port mapping. The issue you’re experiencing is most likely due to either an interference from an existing override file (or another compose file) or an unexpected merge in your configuration. Using the docker-compose config command should help you confirm whether the port mapping is present in the final configuration. Adjusting your setup based on that information should resolve the problem.