Port sharing

Port sharing allows you to expose ports from your running Ona environment to the internet, enabling easy sharing and collaboration. This feature supports both HTTP and HTTPS communication and is available for cloud-hosted Ona environments not Gitpod Desktop environments.

How it works

When you share a port, Ona creates a URL with automatic TLS termination. Ona handles incoming HTTPS connections and forwards them to your service using either HTTP or HTTPS protocol, depending on your configuration.

URL Accessibility

The accessibility of shared port URLs depends on your Ona deployment configuration:

• Ona Cloud: Open ports are accessible via public URLs on the internet. Anyone with the URL can access the service.
• Enterprise Runners: Open ports are accessible through your runner’s Network Load Balancer. Access is controlled by your network configuration and requires connectivity to your runner infrastructure. These URLs are not publicly accessible on the internet unless your runner’s load balancer is configured to allow public access.

Protocol Support

When sharing a port, you can configure how Ona communicates with your service:

• HTTP (default): Standard HTTP communication to your service
• HTTPS: Secure HTTPS communication for services requiring SSL/TLS connections

All open port URLs use HTTPS encryption. The protocol setting only affects how Ona connects to your service within the environment.

Limitations

• Not available on Gitpod Desktop environments.
• Subject to Ona’s fair use policies and bandwidth limits.

Prerequisites

To ensure port sharing works correctly, services must:

• listen on 0.0.0.0 instead of localhost or 127.0.0.1
• be exposed from the Dev Container on the virtual machine using the host network stack.

For example, if you’re running a Node.js server, make sure to bind it to 0.0.0.0 instead of localhost.

const app = express();
app.listen(3000, '0.0.0.0', () => {
	console.log('Server is running on port 3000');
});

Security considerations

While port sharing is convenient, it’s important to be mindful of security:

• Only share ports when necessary and unshare them when you’re done.
• Be cautious about sharing ports running sensitive services or containing confidential data.
• Ona Cloud: Shared URLs are publicly accessible on the internet. Anyone with the URL can access your service.
• Enterprise Runners: Open URLs are accessible through your runner’s infrastructure. Access is restricted to users who can reach your runner’s Network Load Balancer, which is controlled by your network configuration and security policies.

Sharing ports

There are two ways to share ports from your Gitpod environment:

Using the UI

In the Ona UI, you’ll see a section labeled “Public Ports” that allows you to manage port sharing for your environment.

To share a new port:

1. Click the “Open Port” button in the “Public Ports” section.
2. A dialog will appear titled “Open a public port”.
3. Enter a name for the port (optional) and the port number you wish to share.
4. Select the protocol (HTTP or HTTPS) for service communication.
5. Click “Open Port” to confirm.

For ports that are already open:

They will be listed in the “Public Ports” section. Each open port will show its name (if given), port number, and protocol. A green indicator next to the port signifies it’s currently active and accessible.

Security notice: When you open a port on Ona Cloud, it will be accessible on the public internet. For Enterprise Runners, access is controlled by your network configuration. Be careful when sharing URLs.

This interface provides an easy way to manage which ports are exposed from your Ona environment, allowing you to quickly share access to services or applications you’re running.

Using the CLI

The Gitpod CLI provides a set of commands to manage port sharing. These commands allow you to list, open, and close ports directly from your terminal.

Listing ports

To view all currently open ports:

gitpod environment port list

This command will display a list of all ports that are currently open and available for sharing.

Opening a Port

To open and share a new port:

gitpod environment port open 3000 --name my-app

To open a port with HTTPS protocol:

gitpod environment port open 3000 --name my-app --protocol https

The --protocol flag accepts:

• http (default): Standard HTTP communication
• https: Secure HTTPS communication

Closing a Port

To close a previously opened port:

gitpod environment port close <port-number>

For example, to close port 3000:

gitpod environment port close 3000

Examples

1. Open a port for a web server:

   gitpod environment port open 8080 --name webserver
   

2. Open a port for an API server:

   gitpod environment port open 4000 --name api
   

3. Open a port for a development server that requires HTTPS:

   gitpod environment port open 3000 --name dev-server --protocol https
   

4. List all open ports:

   gitpod environment port list
   

5. Close a port that’s no longer needed:

   gitpod environment port close 4000
   

These CLI commands provide a quick and efficient way to manage port sharing directly from your terminal, especially useful for scripting or when you prefer command-line interactions.

Use cases

Port sharing enables various scenarios that enhance development workflows and collaboration:

1. Demonstrating work-in-progress: Quickly share your application with teammates or clients without deploying to a staging environment.
2. API testing: Expose your development API server to test integrations with external services or mobile apps.
3. Collaborative debugging: Share a running application with a colleague to troubleshoot issues together in real-time.
4. Design reviews: Make your development server accessible so designers can review and provide feedback on UI changes.
5. Webhooks development: Test webhook integrations by exposing your server to receive real-time events from external services.
6. HTTPS-dependent applications: Test applications that require HTTPS protocol, such as:
   • Applications with HTTPS-only policies or redirects
   • Streaming APIs requiring secure connections
   • Integration with external services requiring HTTPS callbacks