# Configure app networking > Set how an Orchard app is reached, connect apps with internal addresses, publish raw TCP or UDP ports, and read client details from request headers. Source: https://docs.orchard.hackclub.com/deploy/networking/ Networking decides who can reach an app and how. Each port gets a reach, from a public HTTPS URL to an address that only other apps in the same environment can use, so you expose exactly what you mean to. Behind every port, a Kubernetes Service balances traffic across the app's replicas. You manage ports on the app's **Network** tab. ## Reach Reach sets who can connect to a port. You choose it when you create an app. | Reach | Result | | ---------------- | ---------------------------------------------------------------------------------------- | | **Private link** | An HTTPS URL behind Orchard sign-in. Only people with access to the project can open it. | | **Public link** | An HTTPS URL open to anyone. | | **Public port** | Raw TCP or UDP on an external address. | | **Internal** | A cluster-internal address with no URL. | UDP ports support only **Public port** and **Internal**. ## Connect apps inside the cluster To call another app in the same environment, use its internal address. **Network** > **Ports** shows the address below each port, in this form: ```text ..svc.cluster.local: ``` Inside the same namespace, the short form `:` also resolves. Use the internal address for traffic between apps. A request to a public URL leaves the cluster, depends on public DNS, and passes through the ingress. [Tenant namespaces deny incoming traffic by default](/operate/security/#network-isolation). Apps in the same namespace can reach each other. Each [environment](/start/concepts/#environment) has its own namespace, so apps in different environments cannot use internal addresses to reach each other. ## Add a port **Dashboard** 1. Open the app. 2. Go to **Network**. 3. In **Ports**, select **Add port**. 4. In **Port**, enter the port your process listens on inside the container. 5. Select **TCP** or **UDP**. 6. Select **Add port**. **CLI** ```sh orchard service create --deployment --port 8080 ``` To use UDP, add `--protocol UDP`. ## Publish a TCP or UDP port Publish a raw port to reach a game server or another non-HTTP service from outside the cluster. ### Prerequisites - A layer 4 (L4) load balancer in the cluster. - A public IP address. To set one for your organization, go to **Organization settings** > **Database defaults** > **Public database IP**. Otherwise, the organization inherits the instance default. If neither exists, publishing fails with an error. A superadmin sets the instance default as described in [Set a default public IP](/operate/finishing-setup/#set-a-default-public-ip). This feature is not available in Cloudflare Tunnel mode, because tunnels carry HTTP only. ### Steps **Dashboard** 1. Open the app. 2. Go to **Network**. 3. In **Ports**, turn on **Public** for the port. 4. Select **Make public**. The public address replaces the internal address on the row. Until the load balancer assigns the address, the row shows **Waiting for an address**. If the load balancer reports an error, the row shows the reason instead. For the causes, refer to [Troubleshoot a public address](#troubleshoot-a-public-address). **CLI** ```sh orchard service port public enable --deployment ``` > **Caution** > > Public TCP and UDP traffic skips the HTTP layer, so [app protection](/deploy/protection/) does not apply. The service must handle its own authentication. ### Troubleshoot a public address A public port or a [public database](/data/databases/#public-access) is reachable only after the cluster's load balancer assigns it an address. Orchard reads the state from Kubernetes and shows one of these states: | State | Meaning | | -------------------------- | ------------------------------------------------------------------------------------------ | | **Live** | The load balancer assigned the address. The port accepts connections. | | **Waiting for an address** | The load balancer has not assigned an address yet. A cloud load balancer can take minutes. | | An error with a reason | The load balancer reported a problem. The address does not accept connections. | If Orchard cannot read the state from Kubernetes, the row shows the address without **Live**. | Reason | Cause and fix | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Port _N_ is already in use on the server** | On k3s, the built-in load balancer (ServiceLB) listens on the port on every node, and another LoadBalancer Service or a pod with a host port already holds that port. Turn **Public** off and on to get a new port, or remove the other Service. | | **No address could be allocated** or **No address could be assigned** | MetalLB or Cilium has no free address in its pool, or the public IP is not in a pool. Add the organization's public IP to an address pool, or free an address. | | **The load balancer could not be created** | The cloud provider rejected the request. The reason includes the provider's message, for example a quota limit. Fix the cause in the cloud account. Orchard picks up the address when the provider assigns it. | | **The load balancer assigned _X_ instead of _Y_** | The load balancer ignores the requested IP address. Set the organization's public IP to the assigned address, or configure the load balancer to honor `spec.loadBalancerIP`. | | **No load balancer assigned an address after 5 minutes** | Nothing in the cluster handles LoadBalancer Services. Install a load balancer such as MetalLB, or use k3s with ServiceLB. | To read the full history, run `kubectl describe service -n ` and check **Events**. ## Outbound traffic Apps can reach the public internet. The tenant network policy blocks traffic to private address ranges and to the link-local range that holds cloud metadata services. It also blocks the Kubernetes API, the control-plane database, and unpublished services in other namespaces. ## Request headers Traffic reaches your app through at least one proxy, so the socket peer is the proxy. Client details arrive in headers. | Header | Set by | Contains | | ------------------- | ---------------------------------- | --------------------------------------- | | `X-Real-IP` | The ingress | The peer of the inbound TCP connection | | `X-Forwarded-For` | The ingress, appended for each hop | The client chain, left to right | | `X-Forwarded-Proto` | The ingress | `https` or `http`, as the client saw it | | `X-Forwarded-Host` | The proxy | The hostname the client requested | To get the client address, use `X-Real-IP`. The ingress sets it to the actual peer and overwrites any value from the client. Clients can add entries to `X-Forwarded-For`. Trust only the entries your own proxies added. If your framework derives the client IP from this header, configure the number of proxy hops to trust. A domain with [protection](/deploy/protection/) adds a hop. The protection proxy forwards these headers and appends the peer it saw. It removes `x-orchard-protection-bypass` before the request reaches your app. To build absolute URLs, use `X-Forwarded-Proto` and `X-Forwarded-Host`. Otherwise, a framework can generate links that point at a pod IP address. ## Databases Managed databases are reachable inside the cluster by default. To publish one, refer to [Public access](/data/databases/#public-access). ## Related resources - [Manage domains and HTTPS](/deploy/domains/) - Add a custom domain to an app and redirect domains. - [Reach apps over Tailscale](/deploy/tailscale/) - Give an app a private address on your tailnet.