# Port Mapping Configuration

> Use when when you have a containerized web application with a fixed internal port (e.g., Tomcat on port 8080) and need to expose it on a different localhost port for local access or testing.

- Skill: `holobiomicslab/port-mapping-configuration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/port-mapping-configuration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/port-mapping-configuration/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/port-mapping-configuration

---


# port-mapping-configuration

> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->
## Summary

Configure Docker port mapping to expose containerized web applications at a specified localhost port, enabling HTTP access to the service. This skill is essential when deploying containerized scientific software (such as MetFrag webapp) that runs on a fixed internal port but must be accessible at a user-specified external port.

## When to use

When you have a containerized web application with a fixed internal port (e.g., Tomcat on port 8080) and need to expose it on a different localhost port for local access or testing. Specifically applicable when validating that a Docker container successfully launches and serves an HTTP endpoint at a documented URL.

## When NOT to use

- When the container requires bidirectional communication (socket/streaming) beyond simple HTTP request–response; use `-it` flag and volume mounts instead.
- When port HOST_PORT is already in use on the host system; choose an alternative port or stop the conflicting service first.
- When the image documentation does not specify the internal container port; inspect the Dockerfile or container logs first.

## Inputs

- Docker image name and tag (e.g., ipbhalle/metfragweb)
- Desired host port (integer, typically 8000–9000 for development)
- Container internal port (from image documentation, e.g., 8080 for Tomcat)
- Optional environment variables (WEBPREFIX, JAVA_OPTS)

## Outputs

- Running Docker container accessible via mapped host port
- HTTP endpoint accessible at http://localhost:HOST_PORT/WEBPREFIX
- HTTP 200 status code response confirming service availability

## How to apply

Use the Docker `docker run` command with the `-p` flag to map the host port to the container's internal port in the format `-p HOST_PORT:CONTAINER_PORT`. For MetFrag, the container's Tomcat server runs on internal port 8080; mapping `-p 8888:8080` makes it accessible at http://localhost:8888. After launching, wait for the application server (Tomcat) to fully initialize within the container, then verify accessibility by sending an HTTP GET request to the mapped URL and confirming a 200 status code response. The WEBPREFIX environment variable can further customize the webapp path (e.g., `/MetFragWeb` or `/mymetfrag`) within the exposed port.

## Related tools

- **Docker** (Container runtime and orchestration engine used to run and expose the MetFrag webapp container via port mapping) — https://www.docker.com/
- **Tomcat** (Java application server running inside the MetFrag container on internal port 8080, mapped to host port via -p flag) — https://hub.docker.com/_/tomcat
- **ipbhalle/metfragweb** (Pre-built Docker image containing MetFrag webapp and Tomcat; pulled from Docker Hub and run with port mapping configuration) — https://hub.docker.com/r/ipbhalle/metfragweb

## Examples

```
docker run -it --rm -p 8888:8080 ipbhalle/metfragweb
```

## Evaluation signals

- Docker container launches without errors and remains running after the `docker run` command completes initialization
- HTTP GET request to http://localhost:HOST_PORT/WEBPREFIX returns status code 200 and valid HTML content
- Tomcat logs visible in container output show successful application deployment (e.g., 'INFO: Server startup in ... ms')
- Repeated requests to the mapped URL consistently return 200 status and expected webapp interface
- Port mapping is verified via `docker ps` showing the correct port mapping (e.g., '0.0.0.0:8888->8080/tcp')

## Limitations

- Port mapping only works for TCP-based protocols; UDP or other protocols require different Docker networking modes.
- The mapped host port must be unprivileged (≥1024) unless Docker daemon runs as root; ports <1024 may fail on non-root systems.
- Port mapping does not persist across container restarts unless the same `-p` flag is reapplied; use Docker Compose or volume definitions for persistence.
- WEBPREFIX environment variable is specific to the ipbhalle/metfragweb image; other containers may use different configuration mechanisms.
- If the container's application server takes significant time to initialize (>30 seconds), immediate requests may fail before readiness; add explicit wait logic.

## Evidence

- [readme] Run MetFrag at http://localhost:8888/MetFragWeb: "Run MetFrag at http://localhost:8888/MetFragWeb
```
docker run -it --rm -p 8888:8080 ipbhalle/metfragweb
```"
- [readme] Port mapping with WEBPREFIX environment variable: "Run Metfrag at http://localhost:8888/mymetfrag with 4GB JVM size using a settings file from `./settings.properties`
```
docker run -it --rm -e  JAVA_OPTS="-Xmx4g -Xms4g" -e WEBPREFIX=mymetfrag"
- [other] Workflow validation step: "Query http://localhost:8888/MetFragWeb via HTTP to verify the webapp is accessible and returns a 200 status code."
- [other] Tomcat initialization requirement: "Wait for the Tomcat application server to fully initialize within the container."
- [readme] Container configuration options: "Following options are supported:
* environment variable JAVA_OPTS="-Xmx?g -Xms?g" to adjust jvm memory
* environment variable WEBPREFIX to adjust the web app name"