Docs / Apps (Docker & Git) / Port Mapping and Conflict Resolution

Port Mapping and Conflict Resolution

Published · Last updated: May 2026 · 3 min read

Who this is for

Users who need to understand how ports work in CloudAIPilot, how to avoid port conflicts, and how to resolve them.

What Is Port Mapping?

Port mapping connects a host port (on the server's network) to a container port (inside the Docker container). For example:

  • Host port 8080 → Container port 3000
  • A request to http://server-ip:8080 is forwarded to port 3000 inside the container.

This is identical to Docker's -p 8080:3000 flag.

How to Choose Ports

Port rangeRecommendation
1–1023System ports — avoid (requires root)
1024–8079Available — prefer this range
8080–8099Common web app ports
3000, 4000, 5000Common dev ports — fine for production
9000–9999Common admin/metric ports

Avoid using ports already reserved for:

  • 80 — Nginx HTTP
  • 443 — Nginx HTTPS
  • 22 — SSH
  • 3306 — MySQL
  • 5432 — PostgreSQL
  • 6379 — Redis

Port Conflict Detection

Before creating or updating an app, you can check for conflicts:

Via the UI:

  1. In the Create App form, if you enter a port that is already in use, a warning badge appears.
  2. The warning shows which app or site is using the port.

Via the port check endpoint:

  • CloudAIPilot checks port availability before finalizing any app creation.
  • If a conflict exists, it returns: which resource (app/site), its name, and its ID.

What Happens If You Try to Use a Conflicting Port

CloudAIPilot returns a PORT_CONFLICT error at create or update time. The app is not created. Choose a different host port.

For cloned apps, CloudAIPilot automatically bumps the port to the next available one if the original port is in use.

Compose App Port Mapping

For compose apps, port mappings are tracked per service:

  • Each service in the docker-compose.yml that exposes a host port must be listed in the Port Mappings section.
  • This allows CloudAIPilot to track which ports are in use and detect conflicts across apps and sites.

Viewing Registered Ports for an App

  1. Open the app detail.
  2. The Overview shows the registered port mappings.
  3. Or check the Ports section in the app detail page.

Cleaning Up Ports After App Deletion

When an app is deleted, CloudAIPilot:

  1. Stops the container and removes it.
  2. Closes the UFW firewall rule for the host port.
  3. Closes the cloud provider's firewall rule if one was opened.
  4. Soft-deletes the AppPort rows, releasing the port for future use.

What Success Looks Like

The app runs with the configured ports. No conflict errors. Accessing http://server-ip: reaches the container.

Common Issues and Fixes

IssueLikely causeFix
"PORT_CONFLICT" on createPort already in use by another app or siteUse the port check tool to see what's using the port. Choose a different port.
App running but port not accessibleServer firewall blocking the portAdd the port to the firewall in the server's Firewall tab.
Compose port not trackedPort defined in compose YAML but not in port mapping sectionAdd the port to the port mapping list in the Create App form.

Related Articles