PIGSTY

DNS Domain

Setup domain names for Web Services

After installing Pigsty, users can access most Infra components’ web interfaces via IP + Port.

Let’s say your node’s internal IP is 10.10.10.10, then by default:

While IP + Port works fine for dev/test environments (hey, we’re all lazy sometimes!), for more serious deployments, I strongly recommend accessing these services via domain names.

Using domains has numerous advantages, doesn’t cost extra, and requires just one simple config line.

Let’s dive into these topics:

TL;DR

Add this static resolution record to your /etc/hosts (Linux/MacOS) or C:\Windows\System32\drivers\etc\hosts (Windows):

sudo tee -a /etc/hosts <<EOF
10.10.10.10 h.pigsty g.pigsty p.pigsty a.pigsty
EOF

Replace placeholder IP 10.10.10.10 with your Pigsty node’s IP (public/private, as long as it’s reachable).

If you modified default domains in infra_portal, replace them with your custom domains.

Why Use Domains?

Pigsty strongly recommends using domains instead of direct IP+Port access for several reasons:

  • Domains are easier to remember (unless you’re a robot 🤖)
  • More flexible — point to different IPs without changing configs
  • Consolidate all services behind Nginx for better management, auditing, and reduced attack surface
  • Enable HTTPS encryption to prevent traffic snooping
  • In China, HTTP access to unregistered domains gets hijacked by ISPs, but HTTPS doesn’t
  • Access services bound to 127.0.0.1 or internal Docker networks via Nginx proxy

Pigsty uses internal static domains by default — just add DNS records locally, no need to register real domains.

For internet-facing deployments, consider using real domains with free HTTPS certs.

How DNS Works

If you’re not familiar with HTTP/DNS protocols, here’s a quick primer on how Nginx serves multiple domains on a single port (80 + HTTPS 443):

DNS Protocol

HTTP Protocol

  • HTTP requests (HTTP/1.1+) include a Host header with the requested domain
  • This Host header is crucial — HTTP/1.1 spec requires clients to include it
  • Nginx uses the Host header to match and route requests to different sites
  • Thus, one port can serve different content based on the Host value

Pigsty Default Domains

Pigsty configures these four internal domains by default:

DomainNamePortComponentDescription
h.pigstyhome80/443NginxDefault server, local repo
g.pigstygrafana3000GrafanaMonitoring & visualization
p.pigstyprometheus9090PrometheusTime series DB
a.pigstyalertmanager9093AlertManagerAlert aggregation & routing

Since these domains don’t use TLDs, you’ll need local static or internal dynamic resolution.

Don’t worry — it’s just one config line away! 🚀

Local Static Resolution

Assuming Pigsty’s internal IP is 10.10.10.10, add this to your client machine’s hosts file:

# Pigsty core components & default domains
10.10.10.10 h.pigsty g.pigsty p.pigsty a.pigsty

Adding Resolution

The client machine is where you browse Pigsty services — your laptop, desktop, VM, etc.

For Linux / macOS: sudo nano /etc/hosts For Windows: Run notepad as admin, edit C:\Windows\System32\drivers\etc\hosts

After adding the record, you can access Pigsty web services via these domains.

Custom Domains

Not a fan of default domains? Modify them in infra_portal before installation:

infra_portal:
  home         : { domain: h.pigsty.xxx }
  grafana      : { domain: g.pigsty.xxx ,endpoint: "${admin_ip}:3000" ,websocket: true }
  prometheus   : { domain: p.pigsty.xxx ,endpoint: "${admin_ip}:9090" }
  alertmanager : { domain: a.pigsty.xxx ,endpoint: "${admin_ip}:9093" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }

Then update your hosts file accordingly:

10.10.10.10 h.pigsty.xxx g.pigsty.xxx p.pigsty.xxx a.pigsty.xxx

Use any domain you like — real or made-up - as long as it resolves to Pigsty’s IP via local, internal, or public DNS.

Additional Records

Running other Pigsty extensions? Add these records too:

# Pigsty extension tools & default domains
10.10.10.10 adm.pigsty   # pgAdmin GUI
10.10.10.10 ddl.pigsty   # Bytebase DDL management
10.10.10.10 cli.pigsty   # pig CLI reserved
10.10.10.10 api.pigsty   # Pigsty API reserved
10.10.10.10 lab.pigsty   # JupyterLab reserved
10.10.10.10 git.pigsty   # Gitea reserved
10.10.10.10 wiki.pigsty  # Wiki.js reserved
10.10.10.10 noco.pigsty  # NocoDB reserved
10.10.10.10 supa.pigsty  # Supabase reserved
10.10.10.10 dify.pigsty  # Dify reserved
10.10.10.10 odoo.pigsty  # Odoo reserved
10.10.10.10 mm.pigsty    # MinIO reserved

Public IP Resolution

For cloud deployments, resolve to your public IP, not internal IP.

If your server has internet access, it typically has two NICs - one for internet (public IP) and one for internal network (private IP).

Example: If your cloud server’s public IP is 1.2.3.4 and VPC IP is 10.10.10.10:

# For cloud deployments, resolve to public IP! Just change the IP part:
1.2.3.4 h.pigsty g.pigsty p.pigsty a.pigsty

Internal Dynamic Resolution

Want your office colleagues to access Pigsty via domains? Use internal dynamic resolution.

The simplest way: Ask your network admin to add the DNS records to your internal DNS server.

Using Internal DNS

If your internal DNS server is 192.168.1.1, on Linux/MacOS edit /etc/resolv.conf:

nameserver 192.168.1.1

On Windows: Network Settings → Network Adapter → TCP/IPv4 Properties → DNS config

Test internal DNS resolution:

dig h.pigsty @192.168.1.1

Using Pigsty’s DNS

Pigsty Infra module includes DNS server (port 53).

⚠️ Warning for China deployments: Public servers typically cannot run DNS services (port 53)!

Local HTTPS Access

HTTP access to Pigsty shows “Not Secure” - it’s plaintext, susceptible to MITM attacks.

By default, Pigsty uses a local self-signed CA to issue certs for all Nginx virtual hosts.

HTTPS access shows “Certificate Error” - these are self-signed certs, not from a trusted CA.

Your options:

  • Ignore it, use HTTP or IP+Port (it’s internal anyway, right? 😅)
  • Use HTTPS, click “Advanced → Proceed anyway”
  • Chrome users: Type thisisunsafe when warned (magic words!)
  • Trust the self-signed certs by adding Pigsty’s CA to your browser/OS
  • Use a real CA cert for Pigsty
  • Use real domains with proper HTTPS certs

For internal access needing HTTPS without constant warnings, trust Pigsty’s self-signed CA.

For production, we recommend using public domains with free HTTPS certs via certbot.

Trust Self-signed CA

Pigsty generates a self-signed CA in the admin node source directory (~/pigsty) during init.

To use HTTPS, distribute Pigsty’s CA cert to client trust stores (or use real CAs - expensive!).

Pigsty-managed Linux nodes auto-trust the CA. For other Linux systems:

  • Trust CA Cert
  • EL
  • Debian / Ubuntu
rm -rf /etc/pki/ca-trust/source/anchors/ca.crt
ln -s /etc/pki/ca.crt /etc/pki/ca-trust/source/anchors/ca.crt
/bin/update-ca-trust

MacOS: Double-click ca.crt, add to Keychain, search pigsty-ca, open and “Trust” the root cert.

Windows: Add ca.crt to “Trusted Root Certification Authorities”.

After trusting Pigsty’s CA, no more “untrusted certificate” warnings! 🎉

Public Domain Resolution

Use DNS providers like Cloudflare, Godaddy, Aliyun, or Tencent Cloud DNSPod.

Requires purchasing a domain - basic ones cost ~$10/year.

Add DNS records via provider’s console/API to point domains to Pigsty’s public IP.

Example: With domain pigsty.xxx, add wildcard * A record or individual A records:

  • h.pigsty.xxx → 1.2.3.4
  • a.pigsty.xxx → 1.2.3.4
  • p.pigsty.xxx → 1.2.3.4
  • g.pigsty.xxx → 1.2.3.4

Pigsty includes Certbot support for free HTTPS certs (renew every 3 months).

Further Reading

For more advanced configurations, check the Pigsty documentation for DNS, Nginx, and HTTPS certificate management.

On this page

TL;DRWhy Use Domains?How DNS WorksPigsty Default DomainsLocal Static ResolutionAdding ResolutionCustom DomainsAdditional RecordsPublic IP ResolutionInternal Dynamic ResolutionUsing Internal DNSUsing Pigsty’s DNSLocal HTTPS AccessTrust Self-signed CAPublic Domain ResolutionFurther Reading