Skip to content

direct IP access #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 11, 2025
Merged

direct IP access #238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions apps/docs/content/features/access.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,10 @@ When using Let's Encrypt certificates (recommended):

For applications requiring direct port access or non-HTTP protocols, Zerops provides flexible port configuration options.

:::important
Currently, direct public port access is only available for runtime services and PostgreSQL databases.
:::

<p align="center">
<Image
src="/img/gui/ipv6-public-port.webp"
Expand All @@ -183,8 +187,11 @@ For applications requiring direct port access or non-HTTP protocols, Zerops prov

### Port Configuration

1. Navigate to service detail page in Zerops GUI, select **Public access & internal ports** and click **Setup first access through IPv6** or activate **Unique IPv4 add-on**
1. Navigate to service detail page in Zerops GUI
- For runtime services select **Subdomain & domain & IP access**
- For PostgreSQL select **Direct access through IP address**
2. Configure your port settings:
- Either **Setup first access through IPv6** or activate **Unique IPv4 add-on** (if needed)
- Choose any port from 10-65435 (except 80 and 443)
- Select destination service and internal port
- Each public port can be mapped to any internal service port
Expand All @@ -209,5 +216,4 @@ Optionally secure your ports with firewall rules:
alt="Enable Firewall"
style={{ width: '90%', height: 'auto' }}
/>
</p>

</p>
85 changes: 70 additions & 15 deletions apps/docs/content/postgresql/how-to/connect.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,35 +3,67 @@ title: Connect to PostgreSQL in Zerops
description: Learn how to connect to your PostgreSQL database in Zerops from various environments.
---

This guide covers how to connect to your PostgreSQL database in Zerops, both from services within the same project and from your local workstation.
This guide covers how to connect to your PostgreSQL database in Zerops, both from services within the same project and from outside the Zerops environment.

## Connection Options Overview

Zerops provides two primary ways to connect to PostgreSQL:
Zerops provides several ways to connect to PostgreSQL:

1. **Internal connections** - Between services in the same Zerops project (via private network)
2. **Remote connections** - From your local machine (via Zerops VPN)

:::caution
For security reasons, Zerops doesn't allow exposing PostgreSQL services directly to the internet.
:::
2. **Remote connections**:
- **VPN access** - From your local machine via Zerops VPN
- **Direct IP access** - Enables external applications to connect using TLS encryption by opening public ports on IPv6 (available by default) or IPv4 (requires add-on activation if not already enabled)

## Connection Details

You'll find PostgreSQL connection details in two places in the Zerops GUI:
You'll find internal PostgreSQL connection details in two places in the Zerops GUI:

1. Under the **Access details** button in the project dashboard
2. In the service detail page under the **Peek access details** button

### Connection Parameters

| Parameter | Description |
| --------------------- | --------------------------------------------------------------------- |
| **Hostname** | Identical to the service hostname |
| **Port** | **5432** (fixed for all PostgreSQL services) |
| **User** | Identical to the service hostname |
| **Password** | Randomly generated during service creation |
| **Connection string** | `postgresql://${user}:${password}@{hostname}:5432` |
<table className="w-full my-1.5">
<thead>
<tr>
<th className="w-fit">Parameter</th>
<th className="w-fit">Internal Connection</th>
<th className="w-fit">Direct IP Access (TLS)</th>
</tr>
</thead>
<tbody>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">Hostname/IP</td>
<td className="w-fit">Service hostname</td>
<td className="w-full">Public IP address</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">Port</td>
<td className="w-fit">5432</td>
<td className="w-full">6432</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">User</td>
<td className="w-fit">Identical to the service hostname</td>
<td className="w-full">Same as internal</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">Password</td>
<td className="w-fit">Randomly generated during service creation</td>
<td className="w-full">Same as internal</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">Port env variable</td>
<td className="w-fit">`port`</td>
<td className="w-full">`portTls`</td>
</tr>
<tr>
<td className="w-fit font-semibold whitespace-nowrap">Connection string env variable</td>
<td className="w-fit">`connectionString`</td>
<td className="w-full">`connectionTlsString`</td>
</tr>
</tbody>
</table>

:::warning
Zerops creates a system user named `zps` with full privileges for maintenance purposes. Do not delete, change the password, or remove privileges from this user, as it will disrupt Zerops' ability to maintain the database cluster.
Expand Down Expand Up @@ -72,6 +104,10 @@ For more details on how to use environment variables, and instructions for addin

## Connect Remotely

Zerops offers two methods for connecting to your PostgreSQL database from outside the Zerops environment:

### Method 1: Connect via Zerops VPN

You can securely connect to PostgreSQL from your local workstation via Zerops VPN:

1. [Install & set up zCLI](/references/cli)
Expand All @@ -84,4 +120,23 @@ You can securely connect to PostgreSQL from your local workstation via Zerops VP
* If your connection over VPN doesn't work, try adding `.zerops` suffix to the service hostname (e.g., `database1.zerops`). For additional help, check the [VPN troubleshooting page](/references/vpn/troubleshooting).
:::

### Method 2: Connect via Direct IP Access

Direct IP Access uses [pgBouncer](https://www.pgbouncer.org/) for connection pooling and TLS termination.

Internally, port `5432` is available without SSL. Externally, connections are secured with TLS through pgBouncer (port `6432`) before being routed to your PostgreSQL service.

#### Enable external access

1. Navigate to your PostgreSQL service in the Zerops GUI and choose the **Public Access through IP Addresses** section
2. Choose either IPv6 (available by default) or IPv4 (requires the [unique IPv4](/features/access#dedicated-ipv4-address-330-days) add-on)
3. Open one or more ports and point them to your PostgreSQL service (the system will direct them through pgBouncer)
- Choose any port from 10-65435 (except 80 and 443)
- Select destination service and internal port
- Each public port can be mapped to any internal service port
- Multiple public ports can point to the same internal port if needed
- Port configurations can be set independently for IPv4 and IPv6
4. Optionally enable firewall protection for additional security
5. Click the **Publish X IP access change(s)** button to apply your settings

For database management tools and how to manage users and databases, see [Manage PostgreSQL Users and Databases](/postgresql/how-to/manage).
Loading