Networking

Hubfly Space networking connects containers, Compose services, public endpoints, custom domains, load balancers, and private access workflows inside a project. The platform gives every project a private network for internal service-to-service traffic, then lets you selectively expose only the ports that should receive public traffic.

Use this page when you need to understand how Hubfly private networking, public HTTP endpoints, TCP endpoints, custom domains, SSL, internal aliases, load balancers, and HubTunnels work together in production.

Overview

Hubfly networking has two main layers:

Private networking is available by default inside a project. Public networking is opt-in. A container can run without any public endpoint and still be reachable by other containers in the same project.

This model supports production patterns such as:

• Public API with private PostgreSQL
• Web app with private Redis and workers
• Internal dashboard accessed through HubTunnels
• Multiple app replicas behind a load balancer
• Custom domain with SSL and force HTTPS
• Raw TCP service exposed on an assigned public port
• Compose stack with service-to-service communication over the project network

Core Concepts

Use Cases

Use private networking when one service depends on another inside the same project. For example, an API should connect to PostgreSQL over the project network instead of exposing the database publicly.

Use a public HTTP endpoint when users, browsers, webhooks, or external systems need to reach an HTTP application. This is the normal path for APIs, web apps, documentation sites, dashboards, and webhook receivers.

Use a custom domain when the service needs a stable production hostname such as api.example.com, app.example.com, or admin.example.com.

Use a TCP endpoint when the service speaks a raw TCP protocol and must be reachable from outside Hubfly. TCP exposure should be used carefully because it publishes a lower-level network service directly.

Use a load balancer when one hostname should route to multiple containers. This is useful for multiple replicas of the same app, weighted backend traffic, or controlled traffic distribution.

Use HubTunnels when you need access without public ingress. This is the preferred path for private databases, internal dashboards, and administrative services.

Architecture And Workflow Overview

A typical production networking workflow looks like this:

1. Deploy containers or a Compose stack inside a project.
2. Keep service-to-service dependencies on the private project network.
3. Identify which service is the public entry point.
4. Add a public HTTP endpoint or TCP endpoint only for that service.
5. Attach a verified custom domain when the service is production-facing.
6. Enable SSL and force SSL for browser or API traffic.
7. Add edge templates such as security headers or basic caching where appropriate.
8. Use a load balancer if one hostname should route to multiple containers.
9. Use HubTunnels for private access instead of exposing internal services publicly.
10. Monitor endpoint status, certificate status, container logs, and service health.

The most important design principle is separation of public and private traffic. A project can contain many containers, but only a small number should usually have public endpoints.

Private Project Networking

Containers inside a project can reach each other over the project network. This private network is the right place for internal application traffic: API to database, web to Redis, worker to queue, app to MinIO, or service to service inside a Compose stack.

Hubfly generates managed internal aliases for containers unless a supported deployment flow overrides or extends them. The internal naming model is region-scoped and may look like this:

<generated-alias>.eu1.hubfly.internal

The exact alias depends on the project, region, and container naming flow. Use the alias shown in the dashboard instead of guessing the hostname.

When To Use Private Networking

Use private networking for:

• Databases such as PostgreSQL, MySQL, and MongoDB
• Redis, queues, search engines, and caches
• Internal APIs
• Admin panels
• Metrics or debug endpoints
• MinIO or object storage control surfaces
• Services inside a Compose stack

Private networking reduces public attack surface and avoids unnecessary internet routing for internal traffic.

Internal DNS And Aliases

Internal aliases make service discovery predictable. Instead of using container IP addresses, configure applications with internal hostnames or dynamic service references where supported.

For Compose stacks, service names and imported network aliases help preserve service-to-service communication patterns. A service named db should be reachable by the app through the internal project network rather than through localhost.

Public Endpoints

Public endpoints expose a container port outside the private project network. Hubfly supports public endpoint types for HTTP traffic and TCP traffic.

Use public endpoints only for services that should receive external connections. A backend API may need a public HTTP endpoint, but its database, Redis cache, and worker process usually should not.

HTTP Endpoints

HTTP endpoints are designed for web traffic. Use them for:

• Web applications
• REST APIs
• GraphQL APIs
• Webhook receivers
• Admin dashboards that are meant to be public
• Static or dynamic HTTP services

HTTP endpoints support:

• SSL toggle
• Force SSL toggle
• Proxy header overrides
• Extra proxy configuration
• Edge templates such as security-headers
• Edge templates such as basic-caching
• Certificate status tracking
• Managed generated endpoint hostnames

Use SSL for production traffic. Use force SSL when clients should be redirected from HTTP to HTTPS.

TCP Endpoints

TCP endpoints expose a raw TCP service on an assigned public port. Use TCP endpoints only when the service protocol is not HTTP and must be reachable externally.

TCP endpoints are useful for:

• Protocol-specific services that cannot use HTTP ingress
• Testing raw TCP services
• Controlled external access to custom protocols

TCP endpoints should be treated as higher risk than HTTP endpoints because they publish lower-level service access. Prefer HubTunnels for private database and admin access.

Suggested Ports

The networking UI detects open container ports and suggests them when adding an endpoint or attaching a domain. Suggested ports help avoid exposing the wrong port, especially for images with common defaults such as 80, 3000, 5000, 5432, 6379, or 9000.

Suggested ports are guidance, not a security decision. Always verify which process is listening on the port and whether that process should be public.

Custom Domains

Custom domains attach a verified domain you own to a container port. Use custom domains for production services that need stable hostnames and user-facing URLs.

Custom domain attachment supports:

• Choosing one of your verified owned domains
• Selecting the target container port
• SSL toggle
• Force SSL toggle
• Edge templates such as security-headers
• Edge templates such as basic-caching
• Certificate status tracking
• Domain transfer handling when a domain is already attached elsewhere

A custom domain can point to a container endpoint or to a load balancer group depending on your routing needs.

Domain Verification And DNS

Before attaching a custom domain, verify ownership and configure the required DNS records. The dashboard shows expected records and CNAME targets where needed.

DNS changes can take time to propagate. If a domain does not work immediately after setup, verify the record value, DNS provider configuration, proxy status if using a DNS proxy, and certificate status.

Domain Transfer Behavior

If a domain is already attached to another container or load balancer, the attach flow can request transfer. Use transfer carefully because moving a domain changes where production traffic is routed.

Before transferring a domain, confirm:

• The new target container is healthy
• The new port is correct
• SSL settings are correct
• The old service no longer needs the domain
• The change is expected by the team operating the service

SSL, HTTPS, And Certificates

HTTP endpoints and custom domains can use SSL. Production browser and API traffic should normally use HTTPS.

Use force SSL when clients should always use HTTPS. This prevents accidental plaintext access and gives users a consistent secure URL.

Certificate issuance can take time after endpoint or domain setup. The dashboard can show certificate status, retry state, deploy status, and related errors for HTTP endpoints and custom domains.

SSL Recommendations

Use SSL for:

• Production web apps
• Public APIs
• Login pages
• Dashboards
• Webhook receivers
• Any service handling credentials, tokens, cookies, or user data

Use force SSL unless you have a compatibility requirement for HTTP.

Do not use public HTTP-only traffic for sensitive services.

Edge Templates

Hubfly endpoint and domain configuration can apply built-in edge templates.

Available templates include:

Use security-headers by default for public HTTP services unless the application requires custom header behavior.

Use basic-caching only when caching is safe. Avoid caching private dashboards, personalized API responses, authenticated content, or frequently changing dynamic data unless the application is designed for it.

Load Balancers

Load balancers distribute traffic across multiple container targets behind one entry point. Use a load balancer when one hostname should route to more than one container.

Load balancers support:

• Multiple container targets
• Weighted targets
• Balancing algorithms such as round_robin, least_conn, and ip_hash
• Healthcheck path and interval settings
• Hubfly-managed domains
• Verified custom domains
• SSL and force SSL settings
• Edge templates

Good load balancer use cases include:

• Multiple replicas of the same web service
• Horizontal scaling behind one domain
• Weighted traffic distribution
• Shared entry point for app containers
• Stable routing while backend containers change

For a single container, a normal public endpoint or custom domain is simpler. For multiple targets, use Load Balancers.

HubTunnels

HubTunnels let you access private containers without creating a public endpoint. The CLI provisions a temporary access path into the project network and forwards a local port to a target container port.

Use HubTunnels for:

• Private PostgreSQL access
• Redis debugging
• Internal dashboards
• Admin tools
• Development access to staging services
• One-time maintenance tasks

Example database tunnel:

hubfly tunnel create --project <project_id> --container <container_id> --port 5432 --local 5432

Then connect locally:

psql -h localhost -p 5432 -U postgres postgres

Use HubTunnels when you need access without DNS, SSL, or public ingress configuration.

Configuration Examples

Public Web API

Service: api
Container port: 3000
Endpoint type: HTTP
SSL: enabled
Force SSL: enabled
Edge templates: security-headers
Public access: yes
Database access: private project network

Use this pattern for production APIs, dashboards, and web apps.

Private Database

Service: postgres
Container port: 5432
Public endpoint: none
Custom domain: none
Access path: private project network or HubTunnel
Storage: High Performance managed volume

Use this pattern for PostgreSQL, MySQL, Redis, queues, and other internal dependencies.

Custom Domain For App

Domain: app.example.com
Target: web container port 8080
SSL: enabled
Force SSL: enabled
Edge templates: security-headers, basic-caching if safe

Use this pattern for production user-facing services.

Multiple Replicas Behind One Domain

Domain: api.example.com
Routing: load balancer group
Targets: api-1:3000, api-2:3000, api-3:3000
Algorithm: round_robin or least_conn
Healthcheck path: /health
SSL: enabled
Force SSL: enabled

Use this pattern for horizontally scaled services.

Setup Steps

Add A Public HTTP Endpoint

1. Open the container networking tab.
2. Review detected open ports.
3. Choose the container port that serves HTTP traffic.
4. Select HTTP as the endpoint type.
5. Enable SSL for production traffic.
6. Enable force SSL unless HTTP compatibility is required.
7. Choose edge templates such as security-headers or basic-caching where appropriate.
8. Save the endpoint.
9. Wait for certificate or proxy status to become ready.
10. Test the endpoint from outside the project.

Add A TCP Endpoint

1. Confirm the service protocol really needs raw TCP access.
2. Open the container networking tab.
3. Select the target container port.
4. Choose TCP as the endpoint type.
5. Save the endpoint.
6. Use the assigned public host and port to connect.
7. Remove the TCP endpoint when public access is no longer required.

Attach A Custom Domain

1. Verify ownership of the domain.
2. Configure the required DNS record.
3. Open the target container or load balancer.
4. Select the verified domain.
5. Choose the target port or load balancer group.
6. Enable SSL and force SSL for production traffic.
7. Apply edge templates if appropriate.
8. Save the attachment.
9. Wait for DNS and certificate status to settle.
10. Test the domain with the expected protocol and path.

Use A HubTunnel Instead Of Public Ingress

1. Install and authenticate the Hubfly CLI.
2. Identify the project, container, and target port.
3. Create a tunnel with a local port.
4. Connect locally to localhost:<local_port>.
5. Stop the tunnel after the maintenance or debugging session.

CI/CD Integration

Networking should be part of the release checklist, especially for production APIs and domain changes.

A production CI/CD workflow should verify:

• The service listens on the expected container port
• The application binds to 0.0.0.0, not only localhost
• Required environment variables are present
• Health check path returns success
• Public endpoint or custom domain routes to the correct service
• SSL is enabled and certificates are healthy
• Internal dependencies are private and reachable over project networking
• Load balancer targets are healthy before traffic is shifted

Avoid changing domains, ports, and load balancer targets in the same release unless the team has a rollback plan.

Docker And Compose Usage

For single-container deployments, configure networking after the container is deployed or during the supported deployment flow. Add public endpoints only for the ports that should be externally reachable.

For Compose deployments, keep service-to-service traffic private. Compose services should connect through service names, internal aliases, or dynamic service references instead of public endpoints.

Example Compose pattern:

services:
  api:
    image: ghcr.io/acme/api:prod
    environment:
      DATABASE_HOST: "{{service:db.host}}"
    ports:
      - "3000:3000"
 
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data
 
volumes:
  db-data:

In this pattern, publish the API if it needs external traffic. Keep the database private.

Security Best Practices

Default to private networking. Only expose ports that users, integrations, or external systems actually need.

Do not expose databases publicly unless there is a strong reason and compensating access controls. Use HubTunnels for administrative database access.

Use SSL and force SSL for production HTTP services.

Use security-headers for public web services unless your application requires custom behavior.

Be careful with basic-caching. Do not cache authenticated, user-specific, sensitive, or frequently changing responses unless your application is designed for it.

Review domain transfer actions before confirming them. Moving a domain can redirect production traffic.

Remove unused endpoints. An old public endpoint is still part of your attack surface even if the application no longer uses it.

Keep internal admin panels private. If a dashboard is only for your team, use HubTunnels instead of a public endpoint.

Scaling Considerations

For a single service, a public HTTP endpoint or custom domain is usually enough.

For multiple replicas, use a load balancer so one hostname can distribute traffic across several containers.

Use health checks on load balancer targets so traffic is routed only to healthy services.

Choose the balancing algorithm based on workload behavior:

• round_robin for even distribution across similar targets
• least_conn for workloads where active connection count matters
• ip_hash when client affinity is useful

Scale private dependencies separately from public services. Adding more API containers does not automatically scale PostgreSQL, Redis, or object storage.

Performance Notes

Private project networking is the preferred path for internal service traffic because it avoids unnecessary public routing.

HTTP endpoints are best for HTTP-aware traffic because they can use SSL, redirects, headers, templates, custom domains, and certificate tracking.

TCP endpoints are lower-level and should be used only when HTTP routing is not appropriate.

Load balancers help distribute traffic, but they do not fix slow application code, overloaded databases, or unhealthy targets. Monitor backend services directly.

Caching can improve response time for safe static or cacheable content, but incorrect caching can create stale data or expose private content. Use basic-caching deliberately.

Monitoring And Logging

Monitor networking from several angles:

• Endpoint status
• Certificate status
• DNS record correctness
• Container logs
• Application health check responses
• Load balancer target health
• Public HTTP response codes
• TCP connection failures
• Cloud or DNS proxy status if used
• Project-level service health after domain or endpoint changes

Application logs should include enough context to identify routing issues: request path, status code, upstream dependency, request ID, and error type. Avoid logging credentials, cookies, tokens, or full sensitive URLs.

Troubleshooting

Public Endpoint Does Not Load

Check that the container is running, the application listens on the configured port, and the process binds to 0.0.0.0. If the app only listens on localhost, public ingress cannot reach it.

Custom Domain Does Not Resolve

Check the DNS record, expected CNAME target, domain verification status, and DNS propagation. If using a DNS proxy, confirm the proxy mode is compatible with the endpoint configuration.

HTTPS Certificate Is Pending

Certificate issuance can take time. Verify the domain points to the expected target, SSL is enabled, and the certificate status does not show a configuration error.

Force SSL Redirect Does Not Work As Expected

Confirm force SSL is enabled for the endpoint or domain and that clients are using the correct hostname. If a DNS proxy or external CDN is involved, check its HTTPS settings too.

App Can Reach Database Locally But Not In Hubfly

Check whether the app is using localhost. In Hubfly, the database is in another container, so the app should use the internal alias, service name, or dynamic service reference.

TCP Endpoint Connects But Protocol Fails

Confirm the client is using the assigned public port, the service speaks the expected protocol, and the container port matches the actual listening process.

Load Balancer Sends Traffic To Bad Targets

Check target health, target ports, healthcheck path, balancing algorithm, and whether the backend containers serve the same application version.

HubTunnel Cannot Connect

Verify CLI authentication, project access, container ID, target port, and local port availability. If the local port is already used, choose a different local port.

Common Errors

Best Practices

Keep databases, queues, caches, and admin services private.

Expose only one public entry point per app when possible. For many apps, that is the web or API service.

Use custom domains for production services and generated endpoint URLs for testing or previews.

Use load balancers for multiple replicas instead of attaching the same domain directly to one container.

Use HubTunnels for private maintenance access.

Use SSL and force SSL for production HTTP traffic.

Use clear service names and aliases so network configuration is understandable during incidents.

Remove unused public endpoints and stale domains during cleanup.

Production Recommendations

For a production API, publish only the API port, attach a custom domain, enable SSL and force SSL, use security-headers, keep dependencies private, and monitor endpoint and certificate status.

For a production database, do not create a public endpoint. Use private project networking for app traffic and HubTunnels for administrative access.

For a horizontally scaled app, put replicas behind a load balancer with a healthcheck path and a stable custom domain.

For internal dashboards, use HubTunnels unless the dashboard is intentionally public and protected by application-level authentication.

For Compose stacks, publish only the entrypoint service and keep internal services on the project network.

Limitations

Public endpoint types are focused on HTTP and TCP exposure. Use the endpoint type that matches the service protocol.

Private aliases are project and region scoped. Do not hardcode internal names across unrelated projects or regions.

Custom domain changes depend on DNS correctness and propagation outside Hubfly.

SSL issuance depends on valid routing and DNS configuration.

Load balancers route traffic to container targets, but they do not replace application health checks, database scaling, or release validation.

HubTunnels are intended for temporary private access, not permanent public ingress.

FAQ

Should My Database Have A Public Endpoint?

Usually no. Keep databases private and let application containers connect over the project network. Use HubTunnels for temporary administrative access.

When Should I Use HTTP Instead Of TCP?

Use HTTP endpoints for web apps, APIs, dashboards, and webhooks. Use TCP only for raw TCP protocols that cannot use HTTP routing.

Do I Need A Custom Domain?

Use a custom domain for production user-facing services. Generated endpoint URLs are fine for previews, testing, and early validation.

What Is Force SSL?

Force SSL redirects HTTP traffic to HTTPS so clients use encrypted connections consistently.

Can One Domain Route To Multiple Containers?

Yes. Use a load balancer group when one domain should distribute traffic across multiple container targets.

How Do I Access A Private Service From My Laptop?

Use HubTunnels. The CLI forwards a local port to the private container port without creating public ingress.

Why Does My App Work Locally But Fail In Hubfly Networking?

The most common reason is localhost. Locally, services may share a machine. In containers, localhost points to the same container. Use the internal service hostname or alias.

Real-World Examples

Public API With Private PostgreSQL

Deploy api and postgres in the same project. Attach an HTTP endpoint and custom domain to api:3000. Keep postgres:5432 private. Configure the API with the database internal alias and use HubTunnels for direct database maintenance.

Internal Admin Dashboard

Deploy the dashboard without a public endpoint. Use HubTunnels when the team needs access. This avoids exposing the admin interface to the public internet.

Horizontally Scaled Web App

Deploy multiple app containers with the same application image. Create a load balancer group with each container as a target. Attach app.example.com, enable SSL and force SSL, and configure a healthcheck path such as /health.

Webhook Receiver

Deploy the webhook service with a public HTTP endpoint or custom domain. Enable SSL, avoid caching, and log request IDs and status codes. Keep downstream services private.

Related Docs

• Platform
• Compose
• Load Balancers
• HubTunnels
• Volumes
• Deploy From Image
• Deploy From Git