# Port Reference

> Source: https://parallelworks.com/docs/self-hosting/ports

# Port Reference

This document provides a comprehensive reference for all network ports required when self-hosting the ACTIVATE platform. Use this guide to configure firewalls, network security groups, and load balancers for your deployment.

## Architecture Overview

The ACTIVATE platform uses a hub-and-spoke network model:

- The **control plane** runs in a central Kubernetes cluster and exposes a small set of external ports.
- **Compute cluster agents** (on cloud, managed, or existing clusters) establish outbound WebSocket connections to the control plane. No inbound ports need to be opened on compute clusters.
- All inter-service communication within the control plane cluster uses internal Kubernetes networking.

## External Ports {#external-ports}

These ports must be exposed on the control plane cluster's load balancer or ingress for the platform to function.

| Port | Protocol | Required | Purpose |
|------|----------|----------|---------|
| **443** | TCP (HTTPS) | Yes | Platform web UI, REST API, and agent WebSocket tunnels |
| **80** | TCP (HTTP) | Recommended | HTTP-to-HTTPS redirect |
| **8443** | TCP (HTTPS) | Optional | CAC/Smart Card authentication (mTLS) |

### Port 443 (HTTPS)

This is the primary entry point for all platform traffic. A single port serves:

- **Web interface**: the ACTIVATE UI
- **REST API**: all platform API requests (`/api/...`)
- **Agent tunnel connections**: compute cluster agents connect via `wss://<platform-host>/ws/ssh/tunnel` using persistent multiplexed WebSocket connections
- **SSH-over-WebSocket**: browser-based terminal sessions to user workspaces
- **SSE streams**: real-time event delivery to the UI

TLS termination can be handled by the ACTIVATE ingress service itself (using the configured TLS secret) or by an external load balancer / reverse proxy.

### Port 80 (HTTP)

Serves only as an HTTP-to-HTTPS redirect. Can be omitted if your load balancer handles redirection externally.

### Port 8443 (CAC Authentication)

Required only for deployments using DoD CAC / smart card authentication. This port runs a separate TLS listener that requires mutual TLS (client certificate verification) against the DoD PKE certificate chain. If your deployment uses CAC authentication, **TLS must be terminated by ACTIVATE**. An external load balancer or reverse proxy cannot terminate TLS on this port, as the platform needs direct access to the client certificate. If your deployment does not use CAC authentication, this port does not need to be exposed.

## Internal Cluster Ports {#internal-ports}

These ports are used for communication between services inside the control plane Kubernetes cluster. They should **not** be exposed externally. Kubernetes internal networking handles routing.

### Databases

| Port | Protocol | Service | Notes |
|------|----------|---------|-------|
| **5432** | TCP | PostgreSQL | Usage metrics, billing, and activity tracking |
| **27017** | TCP | MongoDB (replica set) | User accounts, platform configuration, and metadata |

If using managed database services outside the cluster, ensure the control plane can reach the database endpoints on these ports. This may require VNet peering, private endpoints, or firewall rules on the database service.

### Message Queue

| Port | Protocol | Service | Notes |
|------|----------|---------|-------|
| **5672** | TCP (AMQP) | RabbitMQ | Inter-service messaging for job orchestration and cluster operations |
| **15672** | TCP (HTTP) | RabbitMQ Management | Optional management UI for debugging. Do not expose externally. |

### Secrets Management

| Port | Protocol | Service | Notes |
|------|----------|---------|-------|
| **8200** | TCP (HTTP) | HashiCorp Vault | Credential storage. Must be initialized and unsealed. |

### Platform Services

These are internal HTTP services that communicate behind the ingress. They do not need external exposure or special firewall rules. Kubernetes service discovery handles routing.

| Port | Service | Purpose |
|------|---------|---------|
| 3000 | Cloud cacher | Cloud resource caching service |
| 4006 | Legacy API | REST API (Node.js). Scheduled for removal in v8. |
| 8888 | Internal API | Workspace scaling, cost routes (admin, not externally exposed) |

## Compute Cluster Agent Connectivity {#agent-connectivity}

Compute cluster agents running on cloud clusters, managed clusters, or existing on-premises clusters communicate with the control plane over a single outbound connection. **No inbound ports need to be opened on the compute cluster side.**

### Connection Architecture

<MermaidDiagram chart={`
%%{init: {"theme": "neutral", "flowchart": {"padding": 20, "nodeSpacing": 30, "rankSpacing": 60}, "themeVariables": {"edgeLabelBackground": "#f8fafc", "clusterBkg": "transparent"}} }%%
flowchart LR
    user@{ icon: "lucide:user", form: "circle", label: "User", pos: "b" }

    subgraph controlplane["Control Plane"]
        direction TB
        ingress@{ icon: "lucide:shield", form: "circle", label: "Ingress", pos: "b" }
        api@{ icon: "lucide:server", form: "circle", label: "Platform Services", pos: "b" }
    end

    subgraph workspace["User Workspaces"]
        ws@{ icon: "lucide:monitor", form: "circle", label: "Workspace", pos: "b" }
    end

    subgraph compute["Compute Cluster"]
        direction TB
        agent@{ icon: "lucide:satellite-dish", form: "circle", label: "Agent", pos: "b" }
        sshd@{ icon: "lucide:lock", form: "circle", label: "SSH", pos: "b" }
    end

    user -->|"port 443"| ingress
    ingress -->|"port 443"| ws
    ingress -->|"port 443 · reverse tunnel"| agent
    ws -->|"port 22"| sshd

    classDef cpNode fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f
    classDef wsNode fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f
    classDef clusterNode fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#064e3b
    classDef userNode fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#4c1d95

    class ingress,api cpNode
    class ws wsNode
    class agent,sshd clusterNode
    class user userNode

    style controlplane stroke:#3b82f6,stroke-width:2px
    style workspace stroke:#f59e0b,stroke-width:2px
    style compute stroke:#10b981,stroke-width:2px
`} />

### How It Works

1. The agent on the compute cluster initiates an **outbound WebSocket connection** to `wss://<platform-host>/ws/ssh/tunnel` (port 443).
2. The connection is upgraded to a **multiplexed session**, allowing multiple logical streams over the single TCP connection.
3. The control plane can open new streams on this connection to reach the agent (effectively a reverse tunnel) without the agent needing any inbound ports.
4. The agent sends periodic heartbeats with resource metrics over the same HTTPS endpoint.

### SSH Access to Clusters (Port 22)

User workspaces and the platform connect to compute clusters over SSH (port 22) for running jobs and interactive sessions. The `pw ssh` command intelligently selects the connection method based on network configuration:

- **Direct (public IP)**: If the cluster node has a public IP, the platform connects directly to port 22.
- **Direct (peered network)**: If the cluster's network is peered with the control plane network, the platform connects directly to the private IP on port 22.
- **Via agent tunnel**: If the cluster is in an isolated network (not peered), SSH traffic is routed through the agent's existing WebSocket tunnel. No additional ports need to be opened since port 22 is reached internally through the tunnel.

This means clusters should have **port 22 open for SSH** from the control plane, unless all SSH traffic is routed through the agent tunnel.

### Cloud Clusters

Cloud clusters are provisioned by the platform through a configured cloud account (e.g., AWS, Azure, GCP). The platform provisions compute nodes in the cloud provider, and each node's agent automatically establishes a tunnel connection back to the control plane.

**Network requirements from the cloud cluster:**

| Direction | Destination | Port | Protocol | Purpose |
|-----------|------------|------|----------|---------|
| Outbound | Control plane host | 443 | TCP (WSS/HTTPS) | Agent tunnel, API calls, heartbeats |
| Inbound | Controller node | 22 | TCP (SSH) | SSH access from workspaces (if not using tunnel) |

### Managed Clusters

Managed clusters are batch scheduler clusters (e.g., PBS, Slurm, LSF) registered with the platform. Node agents are installed using a one-time registration token and maintain a persistent tunnel connection to the control plane.

**Network requirements from the managed cluster:**

| Direction | Destination | Port | Protocol | Purpose |
|-----------|------------|------|----------|---------|
| Outbound | Control plane host | 443 | TCP (WSS/HTTPS) | Agent tunnel, API calls, heartbeats |
| Inbound | Controller node | 22 | TCP (SSH) | SSH access from workspaces (if not using tunnel) |

### Existing Clusters (On-Premises)

Existing clusters are user-provided infrastructure that you register with the platform. They use the same outbound-only agent tunnel as cloud and managed clusters.

**Network requirements from the existing cluster:**

| Direction | Destination | Port | Protocol | Purpose |
|-----------|------------|------|----------|---------|
| Outbound | Control plane host | 443 | TCP (WSS/HTTPS) | Agent tunnel, API calls, heartbeats |
| Inbound | Controller node | 22 | TCP (SSH) | SSH access from workspaces (if not using tunnel) |

:::tip On-Premises Firewall Configuration
Since agents only make **outbound** connections to port 443 on the control plane, on-premises clusters behind restrictive firewalls only need a single egress rule allowing HTTPS traffic to the platform hostname. No inbound firewall rules or port forwarding are required on the on-premises network.
:::

## Cloud Cluster Internal Ports {#cloud-cluster-ports}

Cloud clusters provisioned by the platform use additional ports for internal communication between the controller node and compute nodes. These ports do **not** need to be exposed to the control plane. They are used within the cluster's own network.

### Shared Storage

| Port | Protocol | Purpose |
|------|----------|---------|
| **2049** | TCP (NFS) | NFS exports from controller to compute nodes |

### Slurm Scheduler

| Port | Protocol | Purpose |
|------|----------|---------|
| **6817** | TCP | Slurmctld (Slurm controller daemon) |
| **6819** | TCP | Slurmdbd (Slurm database daemon) |
| **3306** | TCP | MySQL for Slurm accounting database |
| **8192–60000** | TCP | Slurm srun interactive job step communication |

### General

| Port | Protocol | Purpose |
|------|----------|---------|
| **1024–65535** | TCP | User workflows and application traffic between controller and compute nodes |

:::note
These ports are for communication **within** the cloud cluster network. They do not need to be reachable from the control plane or the internet.
:::

## User Workspace Ports {#workspace-ports}

User workspaces can run on a dedicated user host, in a separate Kubernetes cluster, or in a dedicated namespace. The following ports are used by workspace containers and accessed by platform services.

| Port | Protocol | Purpose |
|------|----------|---------|
| **22** | TCP (SSH) | SSH access to the workspace |
| **3000** | TCP (HTTP) | IDE (code editor) |
| **3001** | TCP (HTTP) | Workspace API |
| **3003** | TCP (HTTP) | Workspace API |
| **3004** | TCP (HTTP) | Workspace API (also used by connected clusters) |
| **1024–65535** | TCP | User-started services and application traffic |

These ports are internal and do not need external exposure.

## Shared Storage (NFS) {#shared-storage}

If using NFS or a shared filesystem for platform storage (see [Kubernetes Deployment Guide](/docs/self-hosting/kubernetes-deployment)), the control plane services need access to the NFS endpoint.

| Port | Protocol | Direction | Purpose |
|------|----------|-----------|---------|
| **2049** | TCP (NFS) | Control plane → Storage | Shared filesystem for user uploads and workflow assets |

## Email (SMTP)

If the platform is configured to send email notifications (billing alerts, user invitations), the control plane needs outbound access to your SMTP server.

| Direction | Destination | Port | Protocol | Purpose |
|-----------|------------|------|----------|---------|
| Outbound | SMTP server | 587 | TCP (SMTP/STARTTLS) | Email delivery |

## Summary {#summary}

### Minimum Required External Ports

For a standard deployment, only **one port** needs external exposure on the control plane:

| Port | Protocol | Purpose |
|------|----------|---------|
| **443** | TCP | All platform traffic (UI, API, agent tunnels) |

### Complete Port Reference

| Port | Protocol | Location | Direction | Required | Purpose |
|------|----------|----------|-----------|----------|---------|
| 443 | HTTPS/WSS | Control plane LB | Inbound | Yes | UI, API, agent tunnels |
| 80 | HTTP | Control plane LB | Inbound | Optional | HTTP redirect |
| 8443 | HTTPS (mTLS) | Control plane LB | Inbound | Optional | CAC/Smart Card auth |
| 2049 | NFS | Control plane → Storage | Outbound | Yes | Shared filesystem |
| 3000 | HTTP | Internal | — | Yes | Cloud cacher |
| 4006 | HTTP | Internal | — | Yes | Legacy API (removal planned in v8) |
| 5432 | TCP | Internal | — | Yes | PostgreSQL |
| 5672 | AMQP | Internal | — | Yes | RabbitMQ |
| 8200 | HTTP | Internal | — | Yes | Vault |
| 8888 | HTTP | Internal | — | Yes | Internal API |
| 15672 | HTTP | Internal | — | Optional | RabbitMQ Management |
| 27017 | TCP | Internal | — | Yes | MongoDB |
| 587 | SMTP | Outbound | Outbound | Optional | Email notifications |
| 443 | WSS/HTTPS | Agent → Control plane | Outbound (from agent) | Yes | Agent tunnel and heartbeats |
| 22 | SSH | Compute clusters | Inbound (from control plane) | Conditional | SSH access from workspaces (not needed if using tunnel) |
| 2049 | NFS | Cloud cluster internal | — | Yes | NFS exports (controller → compute) |
| 6817 | TCP | Cloud cluster internal | — | Conditional | Slurmctld (Slurm clusters) |
| 6819 | TCP | Cloud cluster internal | — | Conditional | Slurmdbd (Slurm clusters) |
| 3306 | TCP | Cloud cluster internal | — | Conditional | MySQL for Slurm accounting |
| 8192–60000 | TCP | Cloud cluster internal | — | Conditional | Slurm srun ports |