nip/docs/container-builds.md

# Container Builds

## Overview

NIP supports building packages in isolated containers using Podman, Docker, or containerd. This provides a clean, reproducible build environment without installing build tools on your host system.

## Why Use Container Builds?

**Advantages:**
- ✅ No build tools needed on host system
- ✅ Complete isolation from host
- ✅ Reproducible builds
- ✅ Rootless with Podman (no root required)
- ✅ Clean host system
- ✅ Easy cleanup

**Perfect for:**
- Arch Linux users wanting Gentoo builds
- Testing packages before committing
- CI/CD pipelines
- Multi-user systems
- Security-conscious users

## Quick Start

### 1. Install Container Runtime

```bash
# Arch Linux (Podman recommended)
sudo pacman -S podman

# Debian/Ubuntu
sudo apt install podman

# Gentoo
sudo emerge app-containers/podman

# Fedora
sudo dnf install podman
```

### 2. Build in Container

```bash
# NIP automatically uses containers when build tools aren't available
nip build vim +python --source=gentoo

# Or explicitly request container build
nip build vim +python --source=gentoo --container
```

## Automatic Container Selection

When you try to build from source, NIP automatically offers container builds:

```bash
$ nip build vim +python --source=gentoo

⚠️  gentoo not found

NIP can help you set up gentoo builds:

1. 🚀 Install minimal tools via NIP (recommended)
   • Lightweight standalone emerge binary
   • Minimal portage snapshot
   • ~50MB download, ~100MB installed

2. 📦 Use containerized environment
   • podman 5.6.2 (rootless) detected
   • Isolated builds, no host installation
   • ~200MB download (first time)

3. 🔧 Install full gentoo manually
   • Follow: https://wiki.gentoo.org/wiki/Portage

4. 🔄 Try a different source
   • nip build vim --source=nix

Choose option (1-4) or 'q' to quit: 2

✅ Container runtime available: podman 5.6.2 (rootless)

📦 Container builds for gentoo are ready to use

Usage:
  nip build <package> --source=gentoo --container

The build will run in an isolated container automatically.
```

## Container Runtimes

### Podman (Recommended)

**Why Podman:**
- ✅ Rootless by default (no root required)
- ✅ Daemonless (no background service)
- ✅ Drop-in Docker replacement
- ✅ Better security
- ✅ OCI compliant

**Install:**
```bash
# Arch Linux
sudo pacman -S podman

# Debian/Ubuntu
sudo apt install podman

# Gentoo
sudo emerge app-containers/podman
```

**Verify:**
```bash
podman --version
nip container info
```

### Docker

**Why Docker:**
- ✅ Widely supported
- ✅ Large ecosystem
- ✅ Well documented

**Install:**
```bash
# Arch Linux
sudo pacman -S docker
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

# Debian/Ubuntu
sudo apt install docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
```

**Verify:**
```bash
docker --version
nip container info
```

### containerd (via nerdctl)

**Why containerd:**
- ✅ Lightweight
- ✅ Kubernetes-native
- ✅ Fast

**Install:**
```bash
# Arch Linux
sudo pacman -S containerd nerdctl

# Verify
nerdctl --version
nip container info
```

## Container Commands

### Check Container Support

```bash
# Show container runtime info
nip container info

# Detect all available runtimes
nip container detect

# List available build images
nip container list
```

### Manage Images

```bash
# Pull build image
nip container pull gentoo
nip container pull nix

# List images
nip container list

# Remove image
nip container remove gentoo/stage3:latest
```

### Build in Container

```bash
# Basic container build
nip build vim --source=gentoo --container

# With USE flags
nip build vim +python+ruby --source=gentoo --container

# With optimizations
nip build ffmpeg +vaapi+lto --source=gentoo --container

# Specify container runtime
nip build vim --container-runtime=podman --source=gentoo
```

### Cleanup

```bash
# Clean up stopped containers
nip container clean

# Remove unused images
nip container prune
```

## Build Environments

### Gentoo Builds

```bash
# Pull Gentoo image
nip container pull gentoo

# Build with USE flags
nip build vim +python+ruby --source=gentoo --container

# Build with custom CFLAGS
nip build ffmpeg +vaapi --source=gentoo --container \
  --cflags="-O3 -march=native"
```

**Image:** `gentoo/stage3:latest`
**Size:** ~200MB
**Features:** Full Portage, USE flags, custom CFLAGS

### Nix Builds

```bash
# Pull Nix image
nip container pull nix

# Build from Nix
nip build firefox --source=nix --container
```

**Image:** `nixos/nix:latest`
**Size:** ~150MB
**Features:** Reproducible builds, binary cache

### PKGSRC Builds

```bash
# Pull PKGSRC image
nip container pull pkgsrc

# Build from PKGSRC
nip build vim --source=pkgsrc --container
```

**Image:** Custom PKGSRC image
**Size:** ~180MB
**Features:** BSD-style builds, portable

## Configuration

### User Configuration

Edit `~/.nip/config`:

```
# Container preferences
container-runtime = "podman"  # podman, docker, containerd
container-auto-pull = true
container-keep-after-build = false

# Build preferences
prefer-container-builds = false
container-build-timeout = 3600  # seconds
```

### Command-Line Options

```bash
# Force container build
nip build vim --container

# Specify runtime
nip build vim --container-runtime=podman

# Keep container after build
nip build vim --container --keep-container

# Custom image
nip build vim --container-image=gentoo/stage3:systemd
```

## Advanced Usage

### Custom Images

```bash
# Use custom Gentoo image
nip build vim --container-image=gentoo/stage3:systemd

# Use specific tag
nip build vim --container-image=gentoo/stage3:latest
```

### Mount Directories

```bash
# Mount custom directory
nip build vim --container \
  --mount=/path/to/source:/build/source

# Mount multiple directories
nip build vim --container \
  --mount=/path/1:/build/1 \
  --mount=/path/2:/build/2
```

### Environment Variables

```bash
# Set environment variables
nip build vim --container \
  --env=USE="python ruby" \
  --env=MAKEOPTS="-j8"
```

### Resource Limits

```bash
# Limit CPU
nip build vim --container --cpus=4

# Limit memory
nip build vim --container --memory=4g

# Both
nip build vim --container --cpus=4 --memory=4g
```

## Workflows

### Arch Linux: Gentoo Builds in Containers

```bash
# Install Podman
sudo pacman -S podman

# Build optimized packages without installing Gentoo
nip build vim +python+ruby+lto --source=gentoo --container
nip build ffmpeg +vaapi+cpu-native --source=gentoo --container

# Packages are installed to /Programs/ as usual
# No Gentoo tools on your system!
```

### Gentoo: Nix Packages in Containers

```bash
# Install Podman
sudo emerge app-containers/podman

# Get Nix packages without installing Nix
nip install firefox --source=nix --container
nip install vscode --source=nix --container

# Fast binary installations, no compilation
```

### CI/CD Pipeline

```bash
# In your CI script
nip container pull gentoo
nip build myapp +production --source=gentoo --container
nip test myapp
nip package myapp
```

## Troubleshooting

###Container Runtime Not Found

```bash
# Check if installed
podman --version
docker --version

# Check NIP detection
nip container detect

# Install if needed
sudo pacman -S podman
```

### Permission Denied

```bash
# For Docker, add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# For Podman, no special permissions needed (rootless)
```

### Image Pull Fails

```bash
# Check network
ping registry.hub.docker.com

# Try different registry
nip container pull --registry=docker.io gentoo/stage3

# Manual pull
podman pull gentoo/stage3:latest
```

### Build Fails in Container

```bash
# Check logs
nip build vim --container --verbose

# Keep container for debugging
nip build vim --container --keep-container

# Inspect container
podman ps -a
podman logs <container-id>
```

### Out of Disk Space

```bash
# Clean up containers
nip container clean

# Remove unused images
podman image prune

# Check disk usage
podman system df
```

## Performance Tips

### Use Binary Cache

```bash
# Enable binary cache for Nix
nip config set nix-binary-cache true

# Use Gentoo binpkgs
nip config set gentoo-binpkgs true
```

### Parallel Builds

```bash
# Set MAKEOPTS
nip build vim --container --env=MAKEOPTS="-j$(nproc)"
```

### Reuse Images

```bash
# Pull images once
nip container pull gentoo
nip container pull nix

# Builds will reuse cached images
nip build vim --container
nip build emacs --container
```

### Layer Caching

Container runtimes cache layers automatically:
- First build: ~5-10 minutes
- Subsequent builds: ~1-2 minutes

## Security

### Rootless Containers

```bash
# Podman runs rootless by default
podman info | grep rootless

# Check in NIP
nip container info
```

### Isolation

```bash
# Containers are isolated from host
# No access to host filesystem except mounted directories
# Network isolation available

# Run with network isolation
nip build vim --container --network=none
```

### Image Verification

```bash
# NIP verifies image checksums
# Container runtimes verify signatures

# Check image
podman image inspect gentoo/stage3:latest
```

## Comparison: Native vs Container

| Feature | Native Build | Container Build |
|---------|--------------|-----------------|
| Setup | Install tools | Install runtime |
| Isolation | System-wide | Complete |
| Speed | Faster | Slightly slower |
| Disk Usage | Lower | Higher |
| Cleanup | Manual | Automatic |
| Security | Lower | Higher |
| Reproducibility | Medium | High |

**Recommendation:**
- Use native builds for frequent development
- Use container builds for testing and CI/CD
- Use containers on Arch for Gentoo builds

## Best Practices

### 1. Use Podman for Rootless

```bash
sudo pacman -S podman
nip config set container-runtime podman
```

### 2. Pull Images in Advance

```bash
nip container pull gentoo
nip container pull nix
```

### 3. Clean Up Regularly

```bash
nip container clean
podman system prune
```

### 4. Use Binary Cache

```bash
nip config set binary-cache true
```

### 5. Limit Resources

```bash
nip build --container --cpus=4 --memory=4g
```

## Examples

### Development Environment

```bash
# Install Podman
sudo pacman -S podman

# Build development tools in containers
nip build vim +python+ruby --source=gentoo --container
nip build emacs +gtk --source=gentoo --container
```

### Testing Packages

```bash
# Test package in container before installing
nip build myapp --source=gentoo --container --keep-container

# If good, install normally
nip build myapp --source=gentoo
```

### CI/CD

```yaml
# .gitlab-ci.yml
build:
  script:
    - nip container pull gentoo
    - nip build myapp --source=gentoo --container
    - nip test myapp
```

## Getting Help

### Documentation

- [Bootstrap Guide](bootstrap-guide.md)
- [Source Build Guide](source-build-guide.md)
- [Container Commands](../README.md#container-commands)

### Commands

```bash
nip container --help
nip build --help
```

### Support

- Issues: https://git.maiwald.work/Nexus/NexusToolKit/issues
- Wiki: https://git.maiwald.work/Nexus/NexusToolKit/wiki

## Summary

Container builds provide:

✅ **Clean host system** - No build tools needed
✅ **Complete isolation** - Secure, reproducible builds
✅ **Rootless operation** - No root required with Podman
✅ **Easy cleanup** - Automatic container removal
✅ **Cross-platform** - Build Gentoo on Arch, Nix on Gentoo
✅ **CI/CD ready** - Perfect for automation

**Get started:**
```bash
sudo pacman -S podman
nip build vim +python --source=gentoo --container
```

That's it! NIP handles everything else automatically.