Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Reference

Exact configuration, CLI, API, portal, and editor details for Piglet.

Use the reference when you already know what you need and want the exact command, option, path, or endpoint.

Choose a section below for Piglet configuration, CLI commands, API access, Nginx Portal, and VS Code details.

1 - CLI

Command-line interface reference for Piglet Run, powered by pig - the PostgreSQL package manager.

Overview

The pig CLI provides complete control over PostgreSQL installation, extension management, and system operations.

Installation 

# Default (Cloudflare CDN)
curl -fsSL https://repo.pigsty.io/pig | bash

# China Mirror
curl -fsSL https://repo.pigsty.io/pig | bash

Verify installation:

pig --version
pig --help

Global Options

Option Description
--help, -h Show help
--debug Enable debug mode
--log-level Set log level (debug/info/warn/error)
-H, --home Pigsty home directory
-i, --inventory Configuration inventory path

Main Commands

Repository Management (pig repo) 

pig repo list                    # List available repos and modules
pig repo info                    # Show repository information
pig repo status                  # Display current repo config
pig repo add [modules...]        # Add repositories
pig repo set                     # Setup all required repos (recommended)
pig repo rm [modules...]         # Remove repositories
pig repo update                  # Update package cache

Extension Management (pig ext) 

pig ext list [pattern]           # Search/list extensions
pig ext info <name>              # Show extension details
pig ext avail <name>             # Show availability matrix
pig ext status                   # Show installed extensions
pig ext scan                     # Scan installed extensions
pig ext add <name> [-v version]  # Install extension
pig ext rm <name>                # Remove extension
pig ext update                   # Update extensions

Installation Alias (pig install) 

pig install pg17                 # Install PostgreSQL 17
pig install pg_duckdb -v 17      # Install extension for PG 17
pig install vector postgis       # Install multiple extensions

PostgreSQL Management (pig pg) 

pig pg init                      # Initialize data directory
pig pg start                     # Start PostgreSQL
pig pg stop                      # Stop PostgreSQL
pig pg status                    # Check status
pig pg psql [database]           # Connect to database
pig pg ps                        # Show connections
pig pg vacuum [database]         # Vacuum database
pig pg log tail                  # View logs in real-time

Backup Management (pig pb) 

pig pb info                      # Show backup information
pig pb ls                        # List all backups
pig pb backup                    # Create backup
pig pb backup full               # Full backup
pig pb backup incr               # Incremental backup
pig pb restore                   # Restore to latest
pig pb restore -t <time>         # Restore to specific time
pig pb log tail                  # View backup logs

Patroni Cluster (pig pt) 

pig pt list                      # List cluster members
pig pt config                    # Show cluster config
pig pt status                    # View service status
pig pt log -f                    # View logs in real-time

Pigsty Management (pig sty) 

pig sty init                     # Download and install Pigsty
pig sty boot                     # Install Ansible dependencies
pig sty conf [-m template]       # Generate configuration
pig sty deploy                   # Run deployment playbook
pig sty list                     # List available versions

System Status (pig status) 

pig status                       # Show environment status

Environment Variables

Variable Description
PIGSTY_HOME Pigsty home directory (default: ~/pigsty)
PIG_LOG_LEVEL Log level

Examples 

# Quick setup for Piglet Run
pig repo set                     # Setup repositories
pig install pg17                 # Install PostgreSQL 17
pig install vector pg_duckdb    # Install extensions
pig sty init && pig sty deploy  # Deploy Pigsty

# Daily operations
pig pg status                    # Check PostgreSQL
pig pb info                      # Check backups
pig ext status                   # Check extensions

See Also

2 - Configuration

Configuration file reference for Piglet Run.

Overview

Piglet Run uses YAML configuration files located in /etc/piglet/.

Main Configuration

File: /etc/piglet/piglet.yml

# Piglet Run Configuration

# System settings
system:
  hostname: piglet
  timezone: UTC
  locale: en_US.UTF-8

# Database settings
database:
  host: localhost
  port: 5432
  user: dba
  database: postgres
  max_connections: 100
  shared_buffers: 256MB

# Services
services:
  vscode:
    enabled: true
    port: 8080
  jupyter:
    enabled: true
    port: 8888
  grafana:
    enabled: true
    port: 3000

# Storage
storage:
  data_dir: /data
  backup_dir: /data/backup
  temp_dir: /tmp/piglet

# Logging
logging:
  level: info
  file: /var/log/piglet/piglet.log
  max_size: 100M
  max_files: 10

Database Configuration

File: /etc/piglet/database.yml

# PostgreSQL Configuration

postgresql:
  version: 17
  data_directory: /data/postgres

  # Connection settings
  listen_addresses: localhost
  port: 5432
  max_connections: 100

  # Memory settings
  shared_buffers: 256MB
  effective_cache_size: 768MB
  work_mem: 4MB
  maintenance_work_mem: 64MB

  # WAL settings
  wal_level: replica
  max_wal_size: 1GB
  min_wal_size: 80MB

  # Logging
  log_destination: csvlog
  logging_collector: on
  log_directory: pg_log

Service Configuration

VS Code Server

File: /etc/piglet/vscode.yml

vscode:
  enabled: true
  port: 8080
  auth: password
  extensions:
    - ms-python.python
    - rust-lang.rust-analyzer

JupyterLab

File: /etc/piglet/jupyter.yml

jupyter:
  enabled: true
  port: 8888
  notebook_dir: /home/dba/notebooks
  kernels:
    - python3
    - ir

Backup Configuration

File: /etc/piglet/backup.yml

backup:
  enabled: true
  schedule: "0 2 * * *"
  retention: 7

  database:
    type: full
    compress: true

  files:
    enabled: true
    paths:
      - /home/dba
      - /etc/piglet

Network Configuration

File: /etc/piglet/network.yml

network:
  # Domain settings
  domain: localhost

  # SSL settings
  ssl:
    enabled: false
    cert: /etc/piglet/ssl/cert.pem
    key: /etc/piglet/ssl/key.pem

  # Proxy settings
  proxy:
    enabled: false
    host: proxy.example.com
    port: 8080

Environment Variables

Override configuration with environment variables:

export PIG_DATABASE_PORT=5433
export PIG_SERVICES_VSCODE_ENABLED=false
export PIG_LOGGING_LEVEL=debug

See Also

3 - VS Code Server

VS Code Server configuration and details for Piglet Run.

Overview

Piglet Run includes a pre-configured VS Code Server (code-server) for browser-based development.

Access

Default URL: http://<ip>/code

Configuration

File: /etc/piglet/vscode.yml

vscode:
  enabled: true
  bind_addr: 127.0.0.1:8080
  auth: password
  password: ${VSCODE_PASSWORD}
  cert: false

  # User data directory
  user_data_dir: /home/dba/.local/share/code-server

  # Extensions directory
  extensions_dir: /home/dba/.local/share/code-server/extensions

Pre-installed Extensions

Extension Description
ms-python.python Python language support
ms-toolsai.jupyter Jupyter notebook support
rust-lang.rust-analyzer Rust language support
golang.go Go language support
dbaeumer.vscode-eslint JavaScript linting
esbenp.prettier-vscode Code formatter
mtxr.sqltools SQL tools

Installing Extensions

Via CLI 

code-server --install-extension ms-python.python

Via Settings

  1. Open VS Code in browser
  2. Go to Extensions (Ctrl+Shift+X)
  3. Search and install extensions

Settings

Default settings location: /home/dba/.local/share/code-server/User/settings.json

{
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,
  "terminal.integrated.defaultProfile.linux": "bash",
  "python.defaultInterpreterPath": "/usr/bin/python3",
  "files.autoSave": "afterDelay"
}

Service Management 

# Start VS Code server
pig start vscode

# Stop VS Code server
pig stop vscode

# Restart VS Code server
pig restart vscode

# View logs
pig logs vscode

Keyboard Shortcuts

Shortcut Action
Ctrl+Shift+P Command palette
Ctrl+P Quick open file
Ctrl+Shift+E Explorer
Ctrl+Shift+F Search
Ctrl+`` Terminal
Ctrl+Shift+G Git

Troubleshooting

Connection Issues 

# Check service status
systemctl status code-server

# Check port binding
ss -tlnp | grep 8080

# View logs
journalctl -u code-server -f

Extension Issues 

# List installed extensions
code-server --list-extensions

# Reinstall extension
code-server --uninstall-extension EXTENSION_ID
code-server --install-extension EXTENSION_ID

See Also

4 - Nginx

Nginx web server configuration for Piglet Run.

Overview

Piglet Run uses Nginx as a reverse proxy and web server for all services.

Configuration

Main config: /etc/nginx/nginx.conf

Site configs: /etc/nginx/conf.d/

Default Configuration

File: /etc/nginx/conf.d/piglet.conf

# Piglet Run Nginx Configuration

upstream vscode {
    server 127.0.0.1:8080;
}

upstream jupyter {
    server 127.0.0.1:8888;
}

upstream grafana {
    server 127.0.0.1:3000;
}

server {
    listen 80;
    server_name _;

    # Homepage
    location / {
        root /www/piglet;
        index index.html;
    }

    # VS Code Server
    location /code {
        proxy_pass http://vscode;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # JupyterLab
    location /jupyter {
        proxy_pass http://jupyter;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }

    # Grafana
    location /ui {
        proxy_pass http://grafana;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

SSL Configuration

File: /etc/nginx/conf.d/piglet-ssl.conf

server {
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate /etc/piglet/ssl/cert.pem;
    ssl_certificate_key /etc/piglet/ssl/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # ... location blocks ...
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name example.com;
    return 301 https://$server_name$request_uri;
}

Service Management 

# Start Nginx
pig start nginx

# Stop Nginx
pig stop nginx

# Restart Nginx
pig restart nginx

# Reload configuration
pig reload nginx

# Test configuration
nginx -t

Custom Site Configuration

Create custom site config:

cat > /etc/nginx/conf.d/mysite.conf << 'EOF'
server {
    listen 80;
    server_name mysite.example.com;

    root /www/mysite;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}
EOF

nginx -t && systemctl reload nginx

Proxy Configuration

WebSocket Support 

location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
}

Node.js Application 

location /app {
    proxy_pass http://127.0.0.1:3001;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Logging

Access log: /var/log/nginx/access.log

Error log: /var/log/nginx/error.log

log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for"';

access_log /var/log/nginx/access.log main;

Rate Limiting 

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

location /api {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://backend;
}

Troubleshooting 

# Test configuration
nginx -t

# Check error log
tail -f /var/log/nginx/error.log

# Check access log
tail -f /var/log/nginx/access.log

# View connections
ss -tlnp | grep nginx

See Also

5 - REST API

REST API reference for Piglet Run.

Overview

Piglet Run provides a REST API for programmatic access to all features.

Base URL 

http://<ip>/api/v1

Authentication

API Key 

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost/api/v1/status

Generate API Key 

pig api key create --name mykey

Endpoints

System

Get Status 

GET /api/v1/status

Response:

{
  "status": "healthy",
  "version": "2.5.0",
  "uptime": 86400,
  "services": {
    "postgres": "running",
    "vscode": "running",
    "jupyter": "running"
  }
}

Get System Info 

GET /api/v1/system

Response:

{
  "hostname": "piglet",
  "os": "Ubuntu 22.04",
  "cpu": 4,
  "memory": "8GB",
  "disk": "100GB"
}

Databases

List Databases 

GET /api/v1/databases

Response:

{
  "databases": [
    {
      "name": "postgres",
      "owner": "dba",
      "size": "50MB"
    }
  ]
}

Create Database 

POST /api/v1/databases
Content-Type: application/json

{
  "name": "mydb",
  "owner": "dba"
}

Delete Database 

DELETE /api/v1/databases/{name}

Backups

List Backups 

GET /api/v1/backups

Response:

{
  "backups": [
    {
      "id": "backup-20240115",
      "type": "full",
      "size": "1.2GB",
      "created_at": "2024-01-15T02:00:00Z"
    }
  ]
}

Create Backup 

POST /api/v1/backups
Content-Type: application/json

{
  "type": "full",
  "databases": ["postgres"]
}

Restore Backup 

POST /api/v1/backups/{id}/restore
Content-Type: application/json

{
  "target_time": "2024-01-15T14:30:00Z"
}

Services

List Services 

GET /api/v1/services

Response:

{
  "services": [
    {
      "name": "postgres",
      "status": "running",
      "port": 5432
    },
    {
      "name": "vscode",
      "status": "running",
      "port": 8080
    }
  ]
}

Control Service 

POST /api/v1/services/{name}/{action}

Actions: start, stop, restart

Snapshots

List Snapshots 

GET /api/v1/snapshots

Create Snapshot 

POST /api/v1/snapshots
Content-Type: application/json

{
  "name": "snap-20240115",
  "description": "Before upgrade"
}

Restore Snapshot 

POST /api/v1/snapshots/{name}/restore

Users

List Users 

GET /api/v1/users

Create User 

POST /api/v1/users
Content-Type: application/json

{
  "username": "newuser",
  "password": "secure_password",
  "databases": ["mydb"]
}

Error Responses 

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Database not found",
    "details": {
      "database": "nonexistent"
    }
  }
}

Error Codes

Code HTTP Status Description
UNAUTHORIZED 401 Invalid or missing API key
FORBIDDEN 403 Insufficient permissions
NOT_FOUND 404 Resource not found
CONFLICT 409 Resource already exists
INTERNAL_ERROR 500 Server error

Rate Limiting

  • Default: 100 requests per minute
  • Burst: 20 requests

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

SDK Examples

Python 

import requests

api_key = "YOUR_API_KEY"
base_url = "http://localhost/api/v1"

headers = {"Authorization": f"Bearer {api_key}"}

# Get status
response = requests.get(f"{base_url}/status", headers=headers)
print(response.json())

# Create database
response = requests.post(
    f"{base_url}/databases",
    headers=headers,
    json={"name": "mydb", "owner": "dba"}
)

JavaScript 

const apiKey = "YOUR_API_KEY";
const baseUrl = "http://localhost/api/v1";

// Get status
fetch(`${baseUrl}/status`, {
  headers: { Authorization: `Bearer ${apiKey}` }
})
  .then(res => res.json())
  .then(data => console.log(data));

See Also