# Nginx Portal

> Configure infra portal and nginx settings
---

Pigsty installs Nginx on the INFRA Node as a web service proxy, using ports 80/443 by default.
The global parameter [`infra_portal`](/docs/infra/param#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

```yaml
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

```yaml
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:

```bash
./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

```yaml
# 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:

```bash
# 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

```bash
./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