Nginx Portal

Pigsty installs Nginx on the INFRA Node as a web service proxy, using ports 80/443 by default. The global parameter infra_portal configures Nginx proxy rules and upstream services.

The Nginx server configuration is specified through the infra_portal parameter. Users declare all domains to be proxied through Nginx, along with corresponding upstream server endpoints or local directory paths.

Basic Example

infra_portal:  # domain names and upstream servers
  home         : { domain: h.pigsty }
  grafana      : { domain: g.pigsty, endpoint: "${admin_ip}:3000", websocket: true }
  prometheus   : { domain: p.pigsty, endpoint: "${admin_ip}:9058" }
  alertmanager : { domain: a.pigsty, endpoint: "${admin_ip}:9059" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }

Complex Example

infra_portal:
  home         : { domain: home.pigsty.cc }
  grafana      : { domain: g.pgsty.com, endpoint: "${admin_ip}:3000", websocket: true }
  cc           : { domain: pigsty.cc, path: "/www/pigsty.cc" }
  en           : { domain: pigsty.io, path: "/www/pigsty.io" }
  prometheus   : { domain: p.pigsty.cc, endpoint: "${admin_ip}:9058" }
  alertmanager : { domain: a.pigsty.cc, endpoint: "${admin_ip}:9059" }
  minio        : { domain: s3.pigsty.cc, endpoint: "${admin_ip}:9001", websocket: true }
  jupyter      : { domain: lab.pigsty.cc, endpoint: "${admin_ip}:8888", websocket: true }
  repo         : { domain: repo.pigsty.cc, path: "/www/repo", index: true }
  wiki         : { domain: wiki.pigsty.cc, endpoint: "${admin_ip}:9002" }
  noco         : { domain: noco.pigsty.cc, endpoint: "${admin_ip}:8080" }
  supa         : { domain: supa.pigsty.cc, endpoint: "${admin_ip}:3001" }
  dify         : { domain: dify.pigsty.cc, endpoint: "${admin_ip}:8001" }
  pg1          : { domain: pg1.pigsty.cc, endpoint: "10.10.10.11:5432", scheme: tcp }
  pg2          : { domain: pg2.pigsty.cc, endpoint: "10.10.10.12:5432", scheme: tcp }
  pg3          : { domain: pg3.pigsty.cc, endpoint: "10.10.10.13:5432", scheme: tcp }

Playbook Configuration

Nginx can be reconfigured using Ansible playbooks:

./infra.yml -t nginx           # Reconfigure Nginx completely
./infra.yml -t nginx_config    # Regenerate Nginx configuration files
./infra.yml -t nginx_launch    # Restart Nginx service
./infra.yml -t nginx_cert      # Regenerate SSL certificates

Server

Each server record in infra_portal supports the following configuration options:

Core Parameters

• domain - Optional proxy domain name
• endpoint - Upstream service address (IP:PORT or socket path)
• path - Local web server root directory for static content
• scheme - Protocol specification (http/https/tcp/udp)

SSL/TLS Parameters

• certbot - Enable Let’s Encrypt certificate management
• cert - Custom SSL certificate file path
• key - Custom SSL private key file path

Advanced Parameters

• conf - Custom Nginx configuration template
• domains - Additional domain names for the service
• index - Enable directory listing for static content
• log - Custom log file configuration
• websocket - Enable WebSocket support for real-time applications

Parameter Usage Examples

# Static file serving with directory listing
repo: { domain: repo.pigsty.cc, path: "/www/repo", index: true }

# WebSocket-enabled service
grafana: { domain: g.pigsty.cc, endpoint: "${admin_ip}:3000", websocket: true }

# Custom SSL certificate
secure_app: {
  domain: secure.pigsty.cc,
  endpoint: "${admin_ip}:8443",
  cert: "/etc/ssl/certs/custom.crt",
  key: "/etc/ssl/private/custom.key"
}

# Let's Encrypt managed certificate
public_api: { domain: api.pigsty.cc, endpoint: "${admin_ip}:8080", certbot: true }

# TCP stream proxy
pg_primary: { domain: pg.pigsty.cc, endpoint: "10.10.10.11:5432", scheme: tcp }

Using Domain Names

DNS Resolution Methods

1. Public internet domain via DNS provider
2. Internal network DNS server
3. Local /etc/hosts file modification

Recommended Local Configuration

For local development and testing, add entries to your /etc/hosts file:

# Add to /etc/hosts
<your_public_ip_address> h.pigsty g.pigsty p.pigsty a.pigsty

Replace <your_public_ip_address> with your actual admin node IP address.

HTTPS Configuration

Configure HTTPS access via the nginx_sslmode parameter with the following options:

• disabled - HTTP only, no SSL
• self-signed - Use self-signed certificates (default)
• provided - Use provided certificates
• letsencrypt - Use Let’s Encrypt certificates

Certificate Management

./infra.yml -t nginx_cert      # Regenerate SSL certificates

HTTPS Access Methods

For self-signed certificates, you can:

• Trust the self-signed CA in your browser
• Use browser security bypass options (type thisisunsafe in Chrome)
• Configure proper CA-signed certificates for production

Service Access Examples

With the default configuration, services are accessible via:

• Home Page: http://h.pigsty or https://h.pigsty
• Grafana Dashboard: http://g.pigsty or https://g.pigsty
• Prometheus Metrics: http://p.pigsty or https://p.pigsty
• Alertmanager: http://a.pigsty or https://a.pigsty

Best Practices

1. Use domain names for service access rather than direct IP:PORT
2. Configure DNS resolution or update local hosts file appropriately
3. Enable WebSocket support for services that require it (like Grafana, Jupyter)
4. Use HTTPS in production environments with proper certificates
5. Organize services logically with meaningful subdomain naming
6. Monitor certificate expiration for Let’s Encrypt certificates
7. Centralize web service proxy through Nginx for better management
8. Use static file serving for documentation and repository browsing