Concept

• 1: Overview
• 2: Architecture
• 3: Storage
• 4: Snapshot
• 5: Clone
• 6: Monitoring
• 7: Security

1 - Overview

What is Piglet Run?

Piglet Run is a lightweight runtime environment from Pigsty, designed as a cloud coding sandbox for AI Web Coding. It integrates PostgreSQL database, JuiceFS distributed storage, VS Code, JupyterLab, and more into a unified environment.

Why Piglet Run?

In the age of AI-assisted development, developers need:

• Instant development environments that just work
• Powerful databases with all extensions available
• Safe experimentation with easy rollback
• Seamless collaboration between humans and AI agents

Piglet Run provides all of this in a single package.

Key Features

Who is it for?

• Solo developers who want a powerful dev environment
• Teams that need shared development infrastructure
• AI developers using Claude Code or similar tools
• Data scientists working with PostgreSQL and Jupyter
• Learners exploring PostgreSQL and web development

How it works

┌─────────────────────────────────────────────────────────────┐
│                      Piglet Run                             │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│  │ VS Code │  │ Jupyter │  │ Claude  │  │  Nginx  │       │
│  │ Server  │  │   Lab   │  │  Code   │  │ Proxy   │       │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘       │
│       │            │            │            │             │
│       └────────────┴────────────┴────────────┘             │
│                         │                                   │
│  ┌──────────────────────┴──────────────────────┐           │
│  │              JuiceFS (Shared Storage)       │           │
│  └──────────────────────┬──────────────────────┘           │
│                         │                                   │
│  ┌──────────────────────┴──────────────────────┐           │
│  │         PostgreSQL 18 + 400+ Extensions     │           │
│  └─────────────────────────────────────────────┘           │
│                                                             │
│  ┌─────────────────────────────────────────────┐           │
│  │      VictoriaMetrics + Grafana (Monitoring) │           │
│  └─────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────┘

Next Steps

• Install Piglet Run to get started
• Learn about the Architecture
• Explore the Storage system

2 - Architecture

System Architecture

Piglet Run is built on top of Pigsty, providing a streamlined development environment.

Components

Network Architecture

Internet
    │
    ▼
┌─────────┐
│  Nginx  │ :80, :443
└────┬────┘
     │
     ├──────────────┬──────────────┬──────────────┐
     │              │              │              │
     ▼              ▼              ▼              ▼
┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│ VS Code │   │ Jupyter │   │ Grafana │   │   App   │
│ /code   │   │/jupyter │   │  /ui    │   │   /*    │
└─────────┘   └─────────┘   └─────────┘   └─────────┘

Storage Architecture

All development work is stored in PostgreSQL via JuiceFS:

┌─────────────────────────────────────┐
│          Working Directory          │
│         ~/workspace                 │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│            JuiceFS                  │
│     (POSIX-compatible FS)           │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│          PostgreSQL                 │
│     (Metadata + Data Chunks)        │
└─────────────────────────────────────┘

Next Steps

• Learn about Storage
• Understand Snapshots

3 - Storage

JuiceFS Shared Storage

Piglet Run uses JuiceFS to provide a distributed filesystem backed by PostgreSQL.

Why JuiceFS?

• POSIX Compatible: Works like a normal filesystem
• Database-Backed: Data stored in PostgreSQL
• Snapshots: Point-in-time recovery support
• Multi-User: Share workspace across sessions

How It Works

┌────────────────────────────────────────────┐
│              Application Layer             │
│   (VS Code, Jupyter, Claude Code, etc.)    │
└──────────────────┬─────────────────────────┘
                   │ POSIX API
                   ▼
┌────────────────────────────────────────────┐
│               JuiceFS FUSE                 │
│         (Filesystem in Userspace)          │
└──────────────────┬─────────────────────────┘
                   │
        ┌──────────┴──────────┐
        │                     │
        ▼                     ▼
┌───────────────┐    ┌───────────────┐
│   Metadata    │    │  Data Chunks  │
│  (PostgreSQL) │    │  (PostgreSQL) │
└───────────────┘    └───────────────┘

Features

Next Steps

• Learn about Snapshots
• Understand Cloning

4 - Snapshot

Time Machine

Piglet Run provides point-in-time recovery for both database and filesystem.

Database PITR

PostgreSQL’s built-in PITR (Point-in-Time Recovery) allows you to restore the database to any point in time. Managed by pgBackRest.

# Show backup information
pig pb info

# List all backups
pig pb ls

# Create a full backup
pig pb backup full

# Restore to latest backup
pig pb restore

# Restore to specific time
pig pb restore -t "2025-01-29 10:00:00"

Filesystem Snapshots

JuiceFS snapshots preserve the state of your workspace:

# Create a snapshot (using juicefs CLI)
juicefs snapshot create /jfs/data snapshot-before-experiment

# List snapshots
juicefs snapshot list /jfs/data

# Restore from snapshot
juicefs snapshot restore /jfs/data snapshot-before-experiment

Use Cases

Backup Management

# View backup status
pig pb info

# View backup logs
pig pb log tail

# Create incremental backup
pig pb backup incr

# Create differential backup
pig pb backup diff

Next Steps

• Learn about Cloning
• See Restore Task
• See Backup Task

5 - Clone

Instant Cloning

Piglet Run supports Copy-on-Write (CoW) cloning for rapid database forking.

How It Works

Copy-on-Write means:

• Zero copy at clone time
• Only changed blocks consume storage
• TB-scale databases clone in milliseconds

Original Database
┌─────────────────────┐
│ Block A │ Block B │ Block C │
└────┬────┴────┬────┴────┬────┘
     │         │         │
     ▼         ▼         ▼
┌────────────────────────────┐
│      Shared Storage        │
└────────────────────────────┘
     ▲         ▲         ▲
     │         │         │
┌────┴────┬────┴────┬────┴────┐
│ Block A │ Block B │ Block C │ (shared)
│         │ Block B'│         │ (changed in clone)
└─────────┴─────────┴─────────┘
Cloned Database

Use Cases

Database Cloning

Using PostgreSQL utilities:

# Create database from template
pig pg psql -c "CREATE DATABASE dev TEMPLATE prod"

# Or using pg_dump/pg_restore for cross-server clone
pg_dump -Fc prod > prod.dump
pg_restore -d dev prod.dump

Using pgBackRest for Cloning

# Restore to a new cluster as a clone
pig pb restore --target-pgdata=/data/pg-clone

# Or restore to specific time point
pig pb restore -t "2025-01-29 10:00:00" --target-pgdata=/data/pg-clone

Filesystem Cloning with JuiceFS

# Clone directory using JuiceFS snapshot
juicefs snapshot create /jfs/workspace ws-snapshot
juicefs snapshot restore /jfs/workspace-clone ws-snapshot

Next Steps

• See Clone Task
• Learn about Snapshots

6 - Monitoring

Full Observability

Piglet Run includes a complete monitoring stack based on VictoriaMetrics and Grafana.

Components

Dashboards

Access Grafana at http://<ip>/ui

Available dashboards:

• Claude Code: AI agent monitoring
• PostgreSQL: Database performance
• System: Host metrics
• JuiceFS: Filesystem statistics

Metrics

Over 3000+ metrics collected:

• Database queries, connections, locks
• System CPU, memory, disk, network
• Application-specific metrics

Alerts

Configure alerts for:

• High CPU/memory usage
• Database connection limits
• Disk space warnings
• Query performance issues

Next Steps

• See Monitor Task
• Learn about Grafana Reference

7 - Security

Security Model

Piglet Run provides multiple layers of security for your development environment.

Access Control

Authentication

Default authentication methods:

• VS Code: Password or token
• Jupyter: Token-based
• Grafana: Username/password
• PostgreSQL: Role-based access

Encryption

Best Practices

1. Change default passwords immediately
2. Enable SSL for all services
3. Restrict network access
4. Regular security updates

Next Steps

• Configure SSL
• Set up Domain