Skip to content

MANUAL_BUILD.md

Latest commit

 

History

History
127 lines (97 loc) · 2.84 KB

MANUAL_BUILD.md

File metadata and controls

127 lines (97 loc) · 2.84 KB
Raw

Manual Build Instructions

Prerequisites

System Requirements

  • OS: Ubuntu 22.04 or newer
  • RAM: At least 4GB (8GB recommended)
  • Disk Space: At least 20GB free
  • CPU: x86_64 or ARM64 architecture
  • Privileges: Root/sudo access

Required Packages

The build script will install dependencies automatically, but you can pre-install:

sudo apt-get update
sudo apt-get install -y qemu-utils kpartx parted guestfs-tools

Repository Structure

postgres-vm-images/
├── build.sh                 # Main build script
└── common/
    ├── setup_base.sh        # PostgreSQL repos & base packages
    ├── setup_packages.sh    # WAL-G & pguint compilation
    ├── setup_monitoring.sh  # Prometheus stack
    ├── setup_cleanup.sh     # Final cleanup
    └── assets/              # Package lists & service files

Running the Build

Basic Usage

# Build with 12GB disk
sudo ./build.sh 12

Parameters

Parameter Default Description
size_gb 12 Final image size in GB

Build Process

The build uses a direct mount + chroot approach for native-speed execution:

  1. Download Ubuntu 22.04 cloud image
  2. Resize image using virt-resize (only libguestfs operation)
  3. Mount image via loop device + kpartx
  4. Chroot into mounted filesystem
  5. Execute setup scripts at native CPU speed:
    • setup_base.sh - PostgreSQL APT repo, base packages
    • setup_packages.sh - Build WAL-G and pguint from source
    • setup_monitoring.sh - Prometheus, node_exporter, postgres_exporter
    • setup_cleanup.sh - Clean apt cache, logs
  6. Cleanup - Zero-fill, unmount, detach loop device

Build Time

Architecture Typical Time
x86_64 ~12-15 minutes
ARM64 ~18-22 minutes

WAL-G compilation is the longest step (~5-8 minutes).

Output

After successful build:

postgres-x64-image.raw    # x86_64 build
postgres-arm64-image.raw  # ARM64 build

Troubleshooting

Permission Denied on /boot/vmlinuz*

sudo chmod 0644 /boot/vmlinuz*

Loop Device Issues

# List active loop devices
losetup -a

# Clean up stale mappings
sudo kpartx -d /dev/loopX
sudo losetup -d /dev/loopX

Build Fails Mid-Way

# Clean up mounts
sudo umount -R /mnt/image 2>/dev/null
sudo kpartx -d /dev/loop* 2>/dev/null
sudo losetup -D

# Remove partial files
rm -f cloud.img cloud.raw resized.img

Testing Locally

# Run with QEMU
qemu-system-x86_64 \
  -enable-kvm \
  -m 4096 \
  -drive file=postgres-x64-image.raw,format=raw \
  -nographic

Converting to Other Formats

# To QCOW2 (smaller file size)
qemu-img convert -f raw -O qcow2 image.raw image.qcow2

# To VHD (Azure/Hyper-V)
qemu-img convert -f raw -O vpc image.raw image.vhd