Brimble exposes web services over HTTPS and forwards requests to the port your service listens on. Your service does not manage public certificates. It reads PORT, listens for HTTP traffic, and Brimble handles the public edge.
Public HTTPS
Every public Brimble URL serves over HTTPS:
- Default project URLs, such as
<project>.brimble.app.
- Preview URLs.
- Custom domains after DNS and certificate provisioning finish.
TLS terminates before the request reaches your container. Inside Brimble, your service receives plain HTTP on its assigned port. Use X-Forwarded-Proto if your framework needs to know the original request was HTTPS.
What your service should listen on
Your web service must listen on the port in the PORT environment variable:
const port = Number(process.env.PORT);
app.listen(port, "0.0.0.0", () => {
console.log(`listening on ${port}`);
});
0.0.0.0, not localhost, so the gateway can reach your process from outside the container.
Supported public protocols
| Protocol | Support | Notes |
|---|
| HTTP/1.1 | Supported by default | Use this for normal websites, APIs, and webhooks. |
| HTTPS | Supported at the public edge | Your container still listens with plain HTTP. |
| WebSockets | Supported by default | Any request with a valid Upgrade: websocket header is proxied bidirectionally. |
| Server-Sent Events | Supported | Keep the response open and flush events from your framework. |
| HTTP/2 and gRPC | Available for HTTP/2-enabled projects | Your service must serve HTTP and gRPC on the same PORT. |
HTTP/2 and gRPC services
Most projects should keep the default HTTP/1.1 behavior. Enable HTTP/2 only when your service needs gRPC or another HTTP/2-only protocol.
For HTTP/2-enabled projects, Brimble expects your service to:
- Listen on the same
PORT as the rest of your web traffic.
- Serve normal HTTP routes and gRPC routes from the same process.
- Accept cleartext HTTP/2, also called h2c, behind the Brimble gateway.
- Keep a lightweight HTTP health check route available, such as
GET /healthz.
This single-port model lets one project handle both browser traffic and gRPC clients without exposing a second public port.
Do not configure your container to terminate public TLS for Brimble traffic. Brimble terminates public TLS at the edge. Your service should listen for HTTP on PORT, including h2c when HTTP/2 is enabled.
gRPC client behavior
External gRPC clients connect to your public Brimble hostname over TLS. Include :443 in the address:
For example, in Go:
conn, err := grpc.Dial(
"api.example.com:443",
grpc.WithTransportCredentials(credentials.NewTLS(nil)),
)
Health checks
Brimble health checks for web services are HTTP GET requests. Even if your main API is gRPC, expose a simple HTTP endpoint for liveness:
Return any 2xx or 3xx status when the service is ready to receive traffic. Keep this endpoint fast and independent of slow downstream services.
Common issues
The service works locally but returns 502 on Brimble.
Check that it listens on process.env.PORT and binds to 0.0.0.0.
The app redirects to http:// URLs.
Your framework may not trust proxy headers. Configure it to respect X-Forwarded-Proto: https.
gRPC requests fail but normal HTTP works.
Confirm the project has HTTP/2 enabled, the client is dialing your-domain.com:443 over TLS, and the service accepts h2c on the same port as the HTTP server. A separate gRPC-only port is not exposed publicly.
Next steps
