hangar port

The ports a Hangar has open for the dev servers its agents run. Every open port is reachable from the team's applications at {name}:{port}, and a public one from everyone on the internet, with no IP access profile and no custom domain in front of it.

The argument is the one port set takes, but the Hangar is the first argument rather than --app, and nothing deploys: a save applies within seconds, and the terminal and its agents keep running. A Hangar can have up to 3 ports open and never 7070, and a dev server is reached only when it listens on 0.0.0.0.

hangar port list

List the ports a Hangar has open.

Usage

outplane hangar port list <HANGAR>

Arguments

Output

Examples

List a Hangar's ports

outplane hangar port list myhangar

Find the addresses in a script

outplane hangar port list myhangar --json --fields port,url,internal

{
  "items": [
    {
      "internal": "myhangar:3000",
      "port": 3000,
      "url": "https://myhangar-3000-acme.outplane.app"
    },
    {
      "internal": "myhangar:5432",
      "port": 5432,
      "url": null
    }
  ],
  "total": 2,
  "truncated": false
}

List one in another team

outplane hangar port list myhangar --team acme

What to Know

• url is null for a private port, which is not an error. internal is set on every port: the team's applications reach the Hangar at name:port whether the port is public or not.
• A public tcp port's url is a host and a port number, not a URL with a scheme. The outside port number comes from a shared pool and is not the one the dev server listens on.
• A public port is open to everyone on the internet. A Hangar takes no IP access profile and no custom domain.
• A dev server is reached only if it listens on 0.0.0.0. One that listens on localhost is not: a public web address answers 502, and applications and tcp clients have the connection refused.
• The same ports are in hangar get and hangar list under ports. An empty list means nothing outside the Hangar reaches its dev servers.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of hangar.not_found, hangar.ambiguous, usage.missing_argument, usage.empty_argument, context.no_team. Branch on that, or on the exit status. The message is prose and changes.

hangar port set

Open a port on a Hangar, or change one that is already open.

Usage

outplane hangar port set <HANGAR> <PORT...>

Arguments

Output

Examples

Open a public HTTP port for a dev server

outplane hangar port set myhangar 3000:http:public

Open several at once

outplane hangar port set myhangar 3000:http:public 5432:tcp

Make an open port private without touching its scheme

outplane hangar port set myhangar 3000::private

See the whole set that would be sent

outplane hangar port set myhangar 8080 --dry-run --json

{
  "action": "set",
  "changed": false,
  "hangar": "myhangar",
  "numbers": [
    8080
  ],
  "ports": [
    {
      "internal": "myhangar:3000",
      "port": 3000,
      "public": true,
      "scheme": "http",
      "url": null
    },
    {
      "internal": "myhangar:8080",
      "port": 8080,
      "public": false,
      "scheme": "http",
      "url": null
    }
  ],
  "serving": 2
}

What to Know

• A part left out keeps what the port already had. hangar port set myhangar 3000 does not make a public port private; 3000::private does. On a port that is not open yet, an omitted part takes the default of private HTTP.
• Saving applies the change to the running Hangar within seconds and restarts nothing: its terminal session and the agents in it keep running. There is no deployment and no --deploy.
• A Hangar can have at most 3 ports open, and 7070 is its own and never one of them. Both are checked on the whole set before anything is sent, as are the port range, 1 to 65535, and the scheme.
• The API replaces the whole set rather than merging, so this command reads the current ports and sends them back with the change applied. Two callers changing different ports at the same time can lose one of the changes. ports in the result is everything that was sent.
• url in the result is the address the server assigned, and null under --dry-run. Making a tcp port public allocates an outside port number from a shared pool.
• A dev server is reached only if it listens on 0.0.0.0. One that listens on localhost is not: a public web address answers 502, and applications and tcp clients have the connection refused.
• Exit 8 with hangar.ports_not_applied means the ports were saved and did not reach the Hangar. It is retryable, and the same command again applies them.
• A Hangar that never started answers exit 5 with hangar.never_started. The ports are saved all the same, but there is nothing to route them to, and deleting it and creating it again is the way back.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of hangar.port_invalid, hangar.scheme_invalid, hangar.port_duplicate, hangar.port_reserved, hangar.port_limit, hangar.never_started, hangar.ports_not_applied, hangar.not_found, hangar.ambiguous, usage.bad_port, usage.missing_argument, usage.empty_argument, context.no_team. Branch on that, or on the exit status. The message is prose and changes.

hangar port unset

Close a port on a Hangar.

Usage

outplane hangar port unset <HANGAR> <PORT...>

Arguments

Output

Examples

See what would be left

outplane hangar port unset myhangar 8080 --dry-run

Close a port

outplane hangar port unset myhangar 8080

Close several and read the result in a pipeline

outplane hangar port unset myhangar 8080 9000 --json --fields numbers,serving,changed

What to Know

• A number the Hangar has no port open on is an error, exit 5 with hangar.port_not_found, and nothing is sent. The error names the ports that are open.
• Closing every port is allowed. The Hangar keeps running, and nothing outside it reaches its dev servers.
• Saving applies the change to the running Hangar within seconds and restarts nothing: its terminal session and the agents in it keep running. There is no deployment and no --deploy.
• The API replaces the whole set rather than merging, so this command reads the current ports and sends them back with the change applied. Two callers changing different ports at the same time can lose one of the changes. ports in the result is everything that was sent.
• Exit 8 with hangar.ports_not_applied means the change was saved and did not reach the Hangar. It is not retryable as it stands: the ports named are already closed in the saved set, so the same command exits 5. hangar port set with a port still open sends the whole set again and applies it.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of hangar.port_not_found, hangar.scheme_invalid, hangar.never_started, hangar.ports_not_applied, hangar.not_found, hangar.ambiguous, usage.bad_port, usage.missing_argument, usage.empty_argument, context.no_team. Branch on that, or on the exit status. The message is prose and changes.

Related