Private Networking and .internal Domains on Dockup

Private networking lets services and managed databases inside one Dockup project communicate without sending same-project traffic over the public internet. Each resource receives a stable <slug>.internal hostname, while separate projects remain isolated from one another.

The network is opt-in. Enabling it connects existing project resources without requiring application traffic to switch immediately, and services receive internal connection variables after redeployment.

How does service-to-service networking reduce public exposure?

A public database endpoint is reachable from the internet even when authentication blocks unauthorized use. A private route removes that exposure for application traffic and gives services a stable internal name that does not depend on a public address.

The same principle applies to service-to-service calls. An API can call a worker, internal admin service, or backend over the project network rather than through a public custom domain.

Traffic path	Public route	Private route
API to PostgreSQL	Public host and port	main-db.internal
Web to API	Public custom domain	api.internal
Worker to Redis	Public host and port	app-redis.internal
Preview to production DB	Public DB credential	Read-only internal user
Cross-project call	Public endpoint required	Blocked by project isolation

Private does not mean unauthenticated. Continue using database users, service authorization, and secrets. The network determines reachability; credentials determine permission.

How do you enable project private networking?

Enable the network for the project slug:

dockup network enable production --json

The operation connects services and managed databases to the project network. Existing public listeners remain available by default, so adoption can be gradual.

Redeploy each application service that should receive internal environment variables:

dockup deploy production/api --wait --json
dockup deploy production/worker --wait --json

Dockup injects connection data such as DATABASE_URL_INTERNAL, database-specific internal URL and host variables, and service host/port values. Inspect the service environment keys without exposing secrets:

dockup env list -s production/api --json

Do not manually construct a URL from a display name. Resource slugs determine the <slug>.internal hostname.

Before changing application config, verify that every dependency lives in the same project. Separate projects have separate networks and cannot resolve or reach one another through the internal path.

How do .internal domains change service configuration?

Internal DNS gives a stable name while containers and nodes change underneath. An API service with slug api is reachable as api.internal from same-project services; a database with slug main-db is reachable as main-db.internal.

Prefer the injected connection variables when available. They encode the correct protocol, credentials, database name, and host format. A hand-built string may omit TLS, password encoding, or database parameters.

Migrate one dependency at a time:

1. Enable the network.
2. Redeploy the consuming service.
3. Confirm the internal variable exists.
4. Change the application to use it.
5. Deploy with --wait.
6. Verify fresh connections.
7. Observe runtime logs and response time.
8. Continue to the next dependency.

A service can retain its public custom domain for user traffic while using private hostnames for backend calls. Public and private paths serve different trust boundaries.

The environment variables and secrets guide explains why connection changes require redeployment.

How do you make a managed database private-only?

After every required consumer uses the internal path, remove the public listener:

dockup db private production/main-db --json

Restore public plus private access when necessary:

dockup db private production/main-db --off --json

This database operation recreates the container while preserving data. Plan a maintenance window appropriate to the workload, confirm a recent backup, and test application reconnection.

Before making it private-only, check:

• Every production service using the database is in the same project.
• Operational tools do not require the public endpoint.
• Preview access uses the supported private path.
• A backup exists and recovery is understood.
• Connection pools retry safely.
• The exact project/db target is recorded.

A private-only database cannot be reached directly from an operator laptop over the public internet. Use supported platform access and application-level diagnostics rather than reopening the listener casually.

For database operations, see managed PostgreSQL.

How do PR previews access production data safely?

Each Dockup PR or branch preview receives its own isolated deployment and URL. In a project with private networking, the preview joins the project network and can resolve <slug>.internal.

Dockup automatically creates a read-only user for the production managed database used by the preview. The preview can query production-shaped data but cannot write through that user.

This design reduces the risk of a feature branch modifying customer records, but read access still has consequences:

• Personal or sensitive data may appear in the preview.
• New application code may log queried data.
• A vulnerable preview URL may expose read results.
• Expensive queries can affect production load.
• Schema assumptions may differ between branch and production.

Enable preview deployment only under a reviewed policy:

dockup pr-preview production/api --on --json
dockup preview branch feature/search production/api --json

Use the preview’s isolated environment for feature flags and non-database secrets. Do not replace the automatic read-only credential with the production write credential.

How should private networking be observed and troubleshot?

Start with topology and configuration rather than assuming a platform outage.

Symptom	Likely area	Check
Name not found	Wrong slug/project or service not redeployed	Service list and env keys
Connection refused	Resource stopped or wrong port	Status and DB/service logs
Authentication failed	Wrong credential	Secret rotation and user
Public works, private fails	Internal variable or network adoption	Network enable, redeploy
Preview can read but not write	Expected read-only policy	Do not replace credential
Cross-project call fails	Expected isolation	Use public authenticated API

Inspect application runtime logs:

dockup logs production/api --json

Inspect database size and application connection errors:

dockup db size production/main-db --json
dockup logs production/api --json

Do not print full internal connection URLs in incident notes. They may include credentials even though the hostname itself is not secret.

Migration and rollback plan

Keep the public listener during the first phase. If the internal deployment fails, restore the application’s previous configuration and redeploy. Only make the database private-only after the internal path has been stable.

To disable the entire project network:

dockup network disable production --json

This should be a deliberate rollback, not the first troubleshooting step. Disabling the network affects every connected resource in the project.

Record network mutations through the audit log:

dockup audit --writes --json

Private networking production checklist

A complete private networking runbook includes project slug, service and database slugs, internal hostnames, injected variable names, public-listener policy, preview access policy, backup status, redeployment order, and rollback path.

CPU, RAM, and disk remain usage-based and measured per minute; private routing is an architecture choice, not a fixed instance class. Use PaaS pricing explained for cost modeling.

The Dockup CLI reference contains the current network and database commands. For general deployment isolation, see security best practices.

Model service authorization separately from reachability

An internal hostname proves only that the caller is on the project network. It does not prove which service made the request or whether that service may perform the action. Keep application authentication for sensitive internal APIs and database credentials for data access.

Use service-specific secrets rather than one shared internal token. If a preview receives read-only database access, do not also give it a production service token that can trigger writes through an API.

Measure the effect of the cutover

Compare connection latency, error rate, and p95 response time before and after switching to internal endpoints. The goal is primarily isolation and a stable private path; any latency improvement should be measured rather than promised.

dockup uptime production/api --hours 24 --json

Retain the observation window and deployment ID. This gives the private networking change a measurable completion criterion instead of ending at “DNS resolved.”

Document the public-path exception

Some external integration, operator tool, or cross-project service may still require a public endpoint. List each exception, its authentication, owner, and removal condition. This prevents the public listener from remaining indefinitely because no one remembers why it exists.

A complete private networking rollout can be partial, but every public path should be intentional.

Review internal dependencies after renames

A resource rename or replacement can change the slug used by .internal addressing. Inventory consumers before changing names, redeploy them with updated injected variables, and verify every private connection.

This keeps private networking stable as the project evolves.

Start with a verifiable deployment

Enable networking in a non-production project, migrate one dependency to its .internal endpoint, and prove the rollback path before removing any public listener.

Start free at app.dockup.ai. The Free plan is $0 per month, includes $2.50 in starting credit, and supports one workspace, three databases, and three deployments.

FAQ

What hostname do Dockup resources use on the private network?

Each same-project service and managed database is reachable through a stable hostname in the form <slug>.internal.

Does enabling private networking remove public database access?

No. The network is additive by default. Use the separate database private command to remove the public listener after consumers use the internal path.

Can different Dockup projects reach each other privately?

No. Each project has an isolated network, so cross-project communication must use an appropriate public and authenticated interface.

Can a PR preview write to the production database?

In a private-networking project, Dockup automatically provisions a read-only database user for the preview, allowing reads but preventing writes through that credential.

Why must services redeploy after networking is enabled?

Redeployment gives the new container the internal connection variables and lets the application start with the private endpoint configuration.