nip/docs/NIPPELS_EXAMPLES.md

# Nippels Usage Examples

**Practical examples for common Nippel use cases**

---

## Table of Contents

1. [Basic Examples](#basic-examples)
2. [Profile-Specific Examples](#profile-specific-examples)
3. [Advanced Use Cases](#advanced-use-cases)
4. [Integration Examples](#integration-examples)
5. [Workflow Examples](#workflow-examples)

---

## Basic Examples

### Example 1: Simple Browser Isolation

**Goal:** Isolate Firefox for general browsing

```bash
# Create Nippel
nip cell create firefox-general --profile=workstation

# Install Firefox
nip install --cell=firefox-general firefox

# Activate and use
nip cell activate firefox-general
firefox

# When done
nip cell deactivate
```

**Result:**
- Firefox runs in isolated environment
- Separate cookies, cache, history
- System themes and fonts work
- < 50ms activation overhead


### Example 2: Work vs Personal Browsers

**Goal:** Completely separate work and personal browsing

```bash
# Create work browser
nip cell create work-browser --profile=workstation
nip install --cell=work-browser firefox

# Create personal browser
nip cell create personal-browser --profile=workstation
nip install --cell=personal-browser firefox

# Use work browser
nip cell activate work-browser
firefox &  # Opens with work profile

# Switch to personal browser
nip cell deactivate
nip cell activate personal-browser
firefox &  # Opens with personal profile
```

**Result:**
- Complete separation of browsing data
- Different bookmarks, extensions, settings
- Easy to backup each separately
- No data leakage between profiles

### Example 3: Quick Nippel Creation

**Goal:** Create and use a Nippel in one command

```bash
# Create, install, and activate in one go
nip cell create-and-use my-app --profile=workstation --install=firefox

# Equivalent to:
# nip cell create my-app --profile=workstation
# nip install --cell=my-app firefox
# nip cell activate my-app
```

### Example 4: Listing and Managing Nippels

**Goal:** View and manage existing Nippels

```bash
# List all Nippels
nip cell list

# List with details
nip cell list --verbose

# List only active Nippels
nip cell list --active

# Show specific Nippel
nip cell show firefox-general

# Remove Nippel (keep data)
nip cell remove old-app

# Remove with data
nip cell remove old-app --purge
```

## Profile-Specific Examples

### Workstation Profile Examples

**Profile:** Balanced security and usability

#### Example 1: Development Environment

```bash
# Create development Nippel
nip cell create dev-env --profile=workstation

# Install development tools
nip install --cell=dev-env \
  gcc gdb valgrind \
  python poetry pytest \
  nodejs npm yarn

# Activate for development
nip cell activate dev-env

# Now all dev tools are available
gcc --version
python --version
node --version

# Deactivate when done
nip cell deactivate
```

#### Example 2: Media Editing

```bash
# Create media editing environment
nip cell create media-edit --profile=workstation

# Install media tools
nip install --cell=media-edit \
  gimp inkscape blender \
  audacity kdenlive

# Activate and edit
nip cell activate media-edit
gimp &
blender &
```

### Homestation Profile Examples

**Profile:** Maximum convenience for home use

#### Example 1: Gaming Setup

```bash
# Create gaming environment
nip cell create gaming --profile=homestation

# Install gaming tools
nip install --cell=gaming \
  steam lutris wine \
  discord obs-studio

# Activate for gaming
nip cell activate gaming
steam &
discord &

# Backup gaming environment
nip cell export gaming --output=gaming-backup.tar.zst
```

#### Example 2: Home Media Center

```bash
# Create media center
nip cell create media-center --profile=homestation

# Install media apps
nip install --cell=media-center \
  vlc mpv kodi \
  spotify-client

# Activate and enjoy
nip cell activate media-center
kodi
```

### Satellite Profile Examples

**Profile:** Maximum portability and isolation

#### Example 1: Banking and Finance

```bash
# Create strict banking environment
nip cell create banking --profile=satellite --isolation=strict

# Install browser
nip install --cell=banking firefox

# Activate for banking (strict isolation)
nip cell activate banking
firefox https://mybank.com

# Deactivate immediately after
nip cell deactivate

# Verify integrity
nip cell verify banking
```

#### Example 2: Portable Work Environment

```bash
# Create portable work environment
nip cell create portable-work --profile=satellite

# Install work tools
nip install --cell=portable-work \
  libreoffice thunderbird \
  firefox vscode

# Export for use on other machines
nip cell export portable-work --output=work-env.nippel.tar.zst

# On another machine:
nip cell import work-env.nippel.tar.zst
nip cell activate portable-work
```

### NetworkIOT Profile Examples

**Profile:** Network-focused, minimal resources

#### Example 1: Network Monitoring

```bash
# Create network monitoring Nippel
nip cell create netmon --profile=networkiot

# Install monitoring tools
nip install --cell=netmon \
  wireshark tcpdump nmap \
  iperf3 mtr

# Activate and monitor
nip cell activate netmon
wireshark &
```

#### Example 2: IoT Gateway

```bash
# Create IoT gateway
nip cell create iot-gateway --profile=networkiot

# Install IoT tools
nip install --cell=iot-gateway \
  mosquitto node-red \
  influxdb grafana

# Activate gateway
nip cell activate iot-gateway
# Services start automatically
```

### Server Profile Examples

**Profile:** Server applications, no desktop

#### Example 1: Web Server

```bash
# Create web server Nippel
nip cell create web-server --profile=server

# Install web stack
nip install --cell=web-server \
  nginx postgresql redis

# Activate and start services
nip cell activate web-server
nip svc enable --cell=web-server nginx
nip svc enable --cell=web-server postgresql
```

#### Example 2: Database Server

```bash
# Create database server
nip cell create db-server --profile=server

# Install database
nip install --cell=db-server postgresql

# Activate and configure
nip cell activate db-server
nip svc enable --cell=db-server postgresql
```

## Advanced Use Cases

### Example 1: Multiple Python Versions

**Goal:** Run different Python versions in isolation

```bash
# Python 3.9 environment
nip cell create python39 --profile=workstation
nip install --cell=python39 python@3.9 poetry pytest

# Python 3.11 environment
nip cell create python311 --profile=workstation
nip install --cell=python311 python@3.11 poetry pytest

# Python 3.12 environment
nip cell create python312 --profile=workstation
nip install --cell=python312 python@3.12 poetry pytest

# Use Python 3.9
nip cell activate python39
python --version  # 3.9.x

# Switch to Python 3.11
nip cell deactivate
nip cell activate python311
python --version  # 3.11.x
```

### Example 2: Testing Untrusted Software

**Goal:** Safely test suspicious software

```bash
# Create quantum-isolated environment
nip cell create untrusted \
  --profile=satellite \
  --isolation=quantum \
  --network=none \
  --filesystem=none

# Activate (complete isolation)
nip cell activate untrusted

# Run untrusted binary
./suspicious-binary
# Cannot access network
# Cannot access filesystem
# Cannot escape isolation

# Deactivate and verify
nip cell deactivate
nip cell verify untrusted

# If compromised, just remove
nip cell remove untrusted --purge
```

### Example 3: Reproducible Development Environment

**Goal:** Create reproducible dev environment

```bash
# Create development environment
nip cell create project-dev --profile=workstation

# Install specific versions
nip install --cell=project-dev \
  nodejs@18.17.0 \
  python@3.11.4 \
  gcc@13.2.0

# Lock the environment
nip cell lock project-dev --output=project-dev.lock

# Share lockfile with team
# Team members can reproduce:
nip cell create project-dev --from-lock=project-dev.lock

# Verify reproducibility
nip cell verify project-dev
```

### Example 4: Multi-Browser Testing

**Goal:** Test web app in multiple browsers

```bash
# Create Firefox testing environment
nip cell create test-firefox --profile=workstation
nip install --cell=test-firefox firefox

# Create Chrome testing environment
nip cell create test-chrome --profile=workstation
nip install --cell=test-chrome chromium

# Create Safari (via Wine) testing environment
nip cell create test-safari --profile=workstation
nip install --cell=test-safari wine safari

# Test in Firefox
nip cell activate test-firefox
firefox http://localhost:3000 &

# Test in Chrome
nip cell activate test-chrome
chromium http://localhost:3000 &

# Test in Safari
nip cell activate test-safari
wine safari http://localhost:3000 &
```


## Integration Examples

### Example 1: Systemd Integration

**Goal:** Run services in Nippels with systemd

```bash
# Create service Nippel
nip cell create my-service --profile=server

# Install service
nip install --cell=my-service nginx

# Enable systemd integration
nip cell customize my-service --systemd=true

# Start service
nip svc enable --cell=my-service nginx
nip svc start --cell=my-service nginx

# Check status
nip svc status --cell=my-service nginx

# View logs
journalctl -u nippel-my-service-nginx
```

### Example 2: Docker Integration

**Goal:** Run Docker containers in Nippels

```bash
# Create Docker environment
nip cell create docker-env --profile=workstation

# Install Docker
nip install --cell=docker-env docker docker-compose

# Activate and use Docker
nip cell activate docker-env
docker run hello-world
docker-compose up -d
```

### Example 3: CI/CD Integration

**Goal:** Use Nippels in CI/CD pipelines

```yaml
# .gitlab-ci.yml
test:
  script:
    - nip cell create ci-test --profile=workstation
    - nip install --cell=ci-test nodejs npm
    - nip cell activate ci-test
    - npm install
    - npm test
    - nip cell deactivate
    - nip cell remove ci-test --purge
```

### Example 4: Backup Integration

**Goal:** Automated Nippel backups

```bash
# Create backup script
cat > backup-nippels.sh <<'EOF'
#!/bin/bash
BACKUP_DIR="/backups/nippels"
DATE=$(date +%Y%m%d)

# Backup all Nippels
for cell in $(nip cell list --format=names); do
  echo "Backing up $cell..."
  nip cell export "$cell" \
    --output="$BACKUP_DIR/${cell}-${DATE}.nippel.tar.zst"
done

# Clean old backups (keep 7 days)
find "$BACKUP_DIR" -name "*.nippel.tar.zst" -mtime +7 -delete
EOF

chmod +x backup-nippels.sh

# Add to cron
crontab -e
# Add: 0 2 * * * /path/to/backup-nippels.sh
```

## Workflow Examples

### Workflow 1: Daily Development

**Morning:**
```bash
# Start work
nip cell activate work-dev
code ~/projects/my-app

# Check emails
nip cell activate work-browser
firefox &
```

**Afternoon:**
```bash
# Switch to different project
nip cell deactivate
nip cell activate other-project-dev
code ~/projects/other-app
```

**Evening:**
```bash
# Personal time
nip cell deactivate
nip cell activate personal-browser
firefox &

# Gaming
nip cell activate gaming
steam &
```

### Workflow 2: Security-Conscious User

**Banking:**
```bash
# Strict isolation for banking
nip cell activate banking
firefox https://mybank.com
# Do banking
nip cell deactivate

# Verify integrity after
nip cell verify banking
```

**General Browsing:**
```bash
# Standard isolation for browsing
nip cell activate personal-browser
firefox
```

**Work:**
```bash
# Work browser with company policies
nip cell activate work-browser
firefox
```

### Workflow 3: Software Testing

**Setup:**
```bash
# Create test environments
nip cell create test-stable --profile=workstation
nip cell create test-beta --profile=workstation
nip cell create test-dev --profile=workstation

# Install different versions
nip install --cell=test-stable myapp@1.0.0
nip install --cell=test-beta myapp@1.1.0-beta
nip install --cell=test-dev myapp@main
```

**Testing:**
```bash
# Test stable version
nip cell activate test-stable
myapp --run-tests

# Test beta version
nip cell activate test-beta
myapp --run-tests

# Test dev version
nip cell activate test-dev
myapp --run-tests
```

### Workflow 4: Team Collaboration

**Team Lead:**
```bash
# Create team development environment
nip cell create team-dev --profile=workstation

# Install team tools
nip install --cell=team-dev \
  nodejs@18.17.0 \
  python@3.11.4 \
  docker docker-compose

# Lock environment
nip cell lock team-dev --output=team-dev.lock

# Share lockfile with team
git add team-dev.lock
git commit -m "Add team development environment"
git push
```

**Team Members:**
```bash
# Clone repository
git clone https://github.com/team/project.git
cd project

# Create environment from lockfile
nip cell create team-dev --from-lock=team-dev.lock

# Activate and develop
nip cell activate team-dev
npm install
npm run dev
```

### Workflow 5: Multi-Environment Development

**Goal:** Develop for multiple platforms

```bash
# Linux development
nip cell create dev-linux --profile=workstation
nip install --cell=dev-linux gcc make cmake

# Windows development (via Wine)
nip cell create dev-windows --profile=workstation
nip install --cell=dev-windows wine mingw-w64

# macOS development (via cross-compiler)
nip cell create dev-macos --profile=workstation
nip install --cell=dev-macos osxcross

# Build for all platforms
nip cell activate dev-linux
make linux

nip cell activate dev-windows
make windows

nip cell activate dev-macos
make macos
```

## Real-World Scenarios

### Scenario 1: Freelance Developer

**Requirements:**
- Multiple client projects
- Different tech stacks
- Strict client data separation

**Solution:**
```bash
# Client A (Python/Django)
nip cell create client-a --profile=workstation
nip install --cell=client-a python poetry postgresql

# Client B (Node.js/React)
nip cell create client-b --profile=workstation
nip install --cell=client-b nodejs npm mongodb

# Client C (Ruby/Rails)
nip cell create client-c --profile=workstation
nip install --cell=client-c ruby bundler postgresql

# Work on Client A
nip cell activate client-a
cd ~/projects/client-a
code .

# Switch to Client B
nip cell deactivate
nip cell activate client-b
cd ~/projects/client-b
code .
```

### Scenario 2: Security Researcher

**Requirements:**
- Analyze malware safely
- Test exploits in isolation
- No risk to host system

**Solution:**
```bash
# Create analysis environment
nip cell create malware-analysis \
  --profile=satellite \
  --isolation=quantum \
  --network=none \
  --filesystem=none

# Activate (complete isolation)
nip cell activate malware-analysis

# Analyze malware
./suspicious-malware
# Cannot escape, cannot access network, cannot access files

# Deactivate and verify
nip cell deactivate
nip cell verify malware-analysis

# If compromised, just remove
nip cell remove malware-analysis --purge
```

### Scenario 3: System Administrator

**Requirements:**
- Test system changes safely
- Multiple server configurations
- Easy rollback

**Solution:**
```bash
# Production-like environment
nip cell create prod-test --profile=server
nip install --cell=prod-test nginx postgresql redis

# Staging environment
nip cell create staging --profile=server
nip install --cell=staging nginx postgresql redis

# Development environment
nip cell create dev-server --profile=server
nip install --cell=dev-server nginx postgresql redis

# Test changes in dev
nip cell activate dev-server
# Make changes
nip svc restart --cell=dev-server nginx

# If good, promote to staging
nip cell export dev-server --output=dev-config.nippel.tar.zst
nip cell import dev-config.nippel.tar.zst --name=staging

# If good, promote to prod-test
nip cell export staging --output=staging-config.nippel.tar.zst
nip cell import staging-config.nippel.tar.zst --name=prod-test
```

---

## See Also

- [Nippels User Guide](./NIPPELS_USER_GUIDE.md) - Complete user guide
- [Nippels Developer Guide](./NIPPELS_DEVELOPER_GUIDE.md) - Developer documentation
- [Nippels Troubleshooting](./NIPPELS_TROUBLESHOOTING.md) - Troubleshooting guide
- [Nippels vs Flatpak](./NIPPELS_VS_FLATPAK.md) - Comparison with Flatpak
- [Nippels vs Packages](./NIPPELS_VS_PACKAGES.md) - When to use Nippels

---

**Version:** 1.0
**Last Updated:** November 19, 2025
**Status:** Usage Examples
**Target Audience:** Users learning Nippels through examples