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}:9090" }
  alertmanager : { domain: a.pigsty, endpoint: "${admin_ip}:9093" }
  blackbox     : { endpoint: "${admin_ip}:9115" }
  loki         : { endpoint: "${admin_ip}:3100" }

Complex Example

infra_portal:
  home         : { domain: home.pigsty.cc }
  grafana      : { domain: demo.pigsty.cc, 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}:9090" }
  alertmanager : { domain: a.pigsty.cc, endpoint: "${admin_ip}:9093" }
  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

Public internet domain via DNS provider
Internal network DNS server
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

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

Nginx Portal

On this page