Tutorial

• 1: Installation
• 2: Quick Start
• 3: VS Code
• 4: Jupyter
• 5: Claude Code
• 6: Database
• 7: Application

1 - Installation

Install Piglet Run

This tutorial guides you through installing Piglet Run on a fresh server.

Prerequisites

• OS: Linux (Ubuntu 22.04+, Debian 12+, RHEL 8+, Rocky 8+)
• CPU: 2+ cores recommended
• RAM: 4GB minimum, 8GB+ recommended
• Disk: 40GB+ free space
• Network: Internet access for package download

Quick Install

1. Install Pig CLI

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

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

2. Setup Repositories

pig repo set          # Setup all required repositories

3. Install Pigsty with Piglet Profile

pig sty init          # Download Pigsty to ~/pigsty
cd ~/pigsty
./configure -m piglet # Configure with piglet preset
./install.yml         # Run installation playbook

Step-by-Step Installation

Download and Install Pig

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

Setup Repositories

pig repo set                          # One-step repo setup
pig repo add all --region china       # Use China mirrors if needed

Install PostgreSQL and Extensions

pig install pg17                      # Install PostgreSQL 17
pig install pg_duckdb vector -v 17    # Install extensions

Install Pigsty Distribution

pig sty init                          # Download Pigsty
pig sty boot                          # Install Ansible
pig sty conf -m piglet                # Generate piglet config
pig sty deploy                        # Run deployment

Verify Installation

After installation, check status:

pig status                            # Check pig environment
pig ext status                        # Check installed extensions
pig pg status                         # Check PostgreSQL status

Access the services:

Troubleshooting

Check Logs

pig pg log tail                       # PostgreSQL logs
pig pt log -f                         # Patroni logs (if HA enabled)

Common Issues

Next Steps

• Continue with Quick Start
• Learn about VS Code

2 - Quick Start

Your First 5 Minutes

This tutorial gets you productive with Piglet Run in 5 minutes.

Access Your Environment

After installation, access your environment:

Create Your First Project

1. Open VS Code

Navigate to http://<ip>/code in your browser.

2. Open Terminal

Press Ctrl+` to open the integrated terminal.

3. Create a Project

cd ~/workspace
mkdir my-first-project
cd my-first-project

4. Create a Simple App

Create app.py:

from http.server import HTTPServer, SimpleHTTPRequestHandler

print("Server running on http://localhost:8000")
HTTPServer(('', 8000), SimpleHTTPRequestHandler).serve_forever()

5. Run It

python app.py

Connect to PostgreSQL

psql postgres://postgres@localhost/postgres

Or in Python:

import psycopg
conn = psycopg.connect("postgres://postgres@localhost/postgres")

Next Steps

• Learn more about VS Code
• Explore Jupyter
• Try Claude Code

3 - VS Code

Web-based VS Code

Learn to use the web-based VS Code server in Piglet Run.

Access

Open your browser and navigate to:

http://<ip>/code

Features

The web VS Code includes:

• Full VS Code experience in browser
• Extensions support
• Integrated terminal
• Git integration
• Python, Go, Node.js support

Getting Started

1. Open a Folder

Click “Open Folder” and select /root/workspace.

2. Install Extensions

Recommended extensions:

• Python
• Pylance
• GitLens
• Database Client

3. Configure Settings

Press Ctrl+, to open settings.

Tips

• Use Ctrl+Shift+P for command palette
• `Ctrl+`` for integrated terminal
• Ctrl+B to toggle sidebar

Next Steps

• Try Jupyter
• Learn Claude Code

4 - Jupyter

JupyterLab Tutorial

Learn to use JupyterLab for data analysis in Piglet Run.

Access

Navigate to:

http://<ip>/jupyter

Features

• Interactive Python notebooks
• Rich output (charts, tables, images)
• PostgreSQL integration
• Multiple kernels (Python, SQL)

Getting Started

1. Create a Notebook

Click “Python 3” under Notebook.

2. Connect to PostgreSQL

import psycopg
import pandas as pd

conn = psycopg.connect("postgres://postgres@localhost/postgres")
df = pd.read_sql("SELECT * FROM pg_stat_activity", conn)
df.head()

3. Visualize Data

import matplotlib.pyplot as plt

df['state'].value_counts().plot(kind='bar')
plt.show()

Tips

• Use Shift+Enter to run cells
• Save notebooks to /root/workspace/notebooks

Next Steps

• Learn Claude Code
• Explore Database

5 - Claude Code

AI-Assisted Development

Learn to use Claude Code for AI-assisted development in Piglet Run.

Prerequisites

You need an Anthropic API key. Set it up:

export ANTHROPIC_API_KEY="your-api-key"

Getting Started

1. Launch Claude Code

In VS Code terminal:

claude

2. Give Instructions

Ask Claude to help with your project:

> Create a FastAPI app with PostgreSQL integration

3. Review and Accept

Claude will:

• Analyze your request
• Generate code
• Explain the changes
• Wait for your approval

Best Practices

Safety

Piglet Run makes AI coding safer:

• Snapshots: Restore any time
• Monitoring: Track AI activity
• Isolation: Sandboxed environment

Monitoring

View Claude Code activity at:

http://<ip>/ui/d/claude-code

Next Steps

• Explore Database
• Build an Application

6 - Database

PostgreSQL Basics

Learn to work with PostgreSQL in Piglet Run.

Connect

Using psql

psql postgres://postgres@localhost/postgres

Using Python

import psycopg

conn = psycopg.connect("postgres://postgres@localhost/postgres")

Create Database

CREATE DATABASE myapp;

Install Extensions

PostgreSQL 18 with 400+ extensions available:

-- Vector search
CREATE EXTENSION vector;

-- Time series
CREATE EXTENSION timescaledb;

-- Full text search (Chinese)
CREATE EXTENSION zhparser;

Basic Operations

-- Create table
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Insert data
INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');

-- Query
SELECT * FROM users;

Monitoring

View database performance at:

http://<ip>/ui/d/pgsql-overview

Next Steps

• Build an Application
• Learn about Backup

7 - Application

Build and Deploy

Learn to build and deploy a web application in Piglet Run.

Create a FastAPI App

1. Set Up Project

cd ~/workspace
mkdir myapp && cd myapp
python -m venv venv
source venv/bin/activate
pip install fastapi uvicorn psycopg[binary]

2. Create Application

Create main.py:

from fastapi import FastAPI
import psycopg

app = FastAPI()

@app.get("/")
def root():
    return {"message": "Hello from Piglet Run!"}

@app.get("/users")
def get_users():
    conn = psycopg.connect("postgres://postgres@localhost/postgres")
    cur = conn.execute("SELECT * FROM users")
    return cur.fetchall()

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

3. Run Locally

python main.py

4. Deploy with Nginx

See Deploy Task for production deployment.

Next Steps

• Learn to Deploy
• Set up SSL