sesterce-cli/docs/DEBIAN_SETUP.md

A powerful command-line interface tool for managing Sesterce Cloud services. Sesterce CLI provides easy access to GPU cloud instances, AI inference services, container registries, and SSH key management directly from your terminal.

# Complete Sesterce CLI Setup Guide

This comprehensive guide covers everything you need to set up Debian package distribution with automatic version management, GPG signing, and APT repository publishing.

## 📋 Table of Contents

1. [Overview](#-overview)
2. [Prerequisites](#-prerequisites)
3. [GPG Key Generation](#-gpg-key-generation)
4. [GitHub Secrets Setup](#-github-secrets-setup)
5. [Local Testing](#-local-testing)
6. [Release Process](#-release-process)
7. [Troubleshooting](#-troubleshooting)
8. [User Installation](#-user-installation)

## 🎯 Overview

Your setup includes:

- ✅ **Automatic version management** with semantic-release
- ✅ **Debian package building** and distribution
- ✅ **APT repository** on GitHub Pages
- ✅ **GPG package signing** for security
- ✅ **Multi-platform distribution** (npm + Debian)
- ✅ **GitHub Actions automation**

## 📋 Prerequisites

### System Requirements

**On Ubuntu/Debian:**

```bash
sudo apt-get update
sudo apt-get install build-essential devscripts debhelper gnupg2
```

**On macOS:**

```bash
brew install dpkg gnupg
```

**On CentOS/RHEL:**

```bash
sudo yum install build-essential devscripts debhelper gnupg2
```

### Required Accounts

- GitHub repository with Actions enabled
- npm account with publish permissions

## 🔑 GPG Key Generation

### Method 1: Interactive Generation (Recommended)

```bash
# Generate GPG key interactively
gpg --full-generate-key

# Follow the prompts:
# 1. Choose option 1 (RSA and RSA)
# 2. Choose 4096 bits
# 3. Choose 0 (no expiration)
# 4. Enter your name: "Sesterce Team"
# 5. Enter your email: "support@sesterce.com"
# 6. Enter a comment (optional)
# 7. Enter a secure passphrase
```

### Method 2: Batch Generation

```bash
# Create configuration file
cat > gpg-config << 'EOF'
%echo Generating GPG key for Sesterce CLI
Key-Type: RSA
Key-Length: 4096
Subkey-Type: RSA
Subkey-Length: 4096
Name-Real: Sesterce Team
Name-Email: support@sesterce.com
Expire-Date: 0
Passphrase: your-secure-passphrase-here
%commit
%echo GPG key generation complete
EOF

# Generate the key
gpg --batch --generate-key gpg-config
```

### Export Keys

```bash
# Get your email from the key
EMAIL="support@sesterce.com"

# Export public key
gpg --armor --export "$EMAIL" > sesterce-cli-public.gpg

# Export private key (you'll be prompted for passphrase)
gpg --armor --export-secret-key "$EMAIL" > sesterce-cli-private.gpg

# Verify keys were created
ls -la sesterce-cli-*.gpg
```

### Verify Your Key

```bash
# List your keys
gpg --list-secret-keys

# Check key details
gpg --list-secret-keys --keyid-format LONG
```

## 🔐 GitHub Secrets Setup

Go to your GitHub repository → Settings → Secrets and variables → Actions

### Required Secrets

1. **`NPM_AUTH_TOKEN`**
   - Get from: https://www.npmjs.com/settings/tokens
   - Scope: Read and Publish
   - Value: Your npm authentication token

2. **`GPG_PRIVATE_KEY`**
   - Value: Copy the entire contents of `sesterce-cli-private.gpg`
   - Format: ASCII armored GPG private key

3. **`GPG_PASSPHRASE`**
   - Value: The passphrase you used when creating the GPG key

### Optional Secrets

- `GITHUB_TOKEN` - Automatically provided by GitHub

## 🧪 Local Testing

### Test GPG Key

```bash
# Test GPG key functionality
echo "test" | gpg --clearsign
gpg --verify test.asc
rm test.asc
```

### Test Debian Package Build

```bash
# Build the package locally
./scripts/build-deb.sh

# Test the package
./scripts/test-deb.sh

# Verify version synchronization
./scripts/verify-version.sh
```

### Test Package Installation

```bash
# Install locally (for testing)
sudo dpkg -i ../sesterce-cli_*.deb
sudo apt-get install -f  # Install dependencies if needed

# Test the binary
sesterce --version

# Uninstall
sudo dpkg -r sesterce-cli
```

## 🚀 Release Process

### Automatic Release (Recommended)

The workflow is **fully automated**:

1. **Push to main branch** with conventional commit
2. **semantic-release analyzes** commit message
3. **Automatic process**:
   - Publishes to npm with new version
   - Builds Debian package with matching version
   - Creates APT repository on GitHub Pages
   - Creates GitHub release with all installation methods

### Commit Message Convention

Use conventional commit messages for automatic versioning:

```bash
# Patch release (1.0.1 -> 1.0.2)
git commit -m "fix: resolve authentication issue"

# Minor release (1.0.0 -> 1.1.0)
git commit -m "feat: add new GPU instance type"

# Major release (1.0.0 -> 2.0.0)
git commit -m "feat!: breaking change in API"

# No release (documentation only)
git commit -m "docs: update README"
```

### Manual Release

```bash
# Trigger workflow manually
# Go to GitHub Actions → Release → Run workflow
```

### Version Management

The system automatically:

- Analyzes commit messages
- Determines new version
- Updates `package.json`
- Synchronizes Debian package version
- Creates Git tags
- Publishes to all platforms

## 📦 Package Distribution

Once released, users can install your CLI using multiple methods:

### Method 1: Direct Download

```bash
# Download and install
wget https://github.com/sesterce-app/sesterce-cli/releases/download/v1.0.2/sesterce-cli_1.0.2_all.deb
sudo dpkg -i sesterce-cli_1.0.2_all.deb
sudo apt-get install -f
```

### Method 2: APT Repository

```bash
# Add the repository
curl -fsSL https://sesterce-app.github.io/sesterce-cli/gpg | sudo gpg --dearmor -o /usr/share/keyrings/sesterce-cli-archive-keyring.gpg

echo "deb [arch=all signed-by=/usr/share/keyrings/sesterce-cli-archive-keyring.gpg] https://sesterce-app.github.io/sesterce-cli/ stable main" | sudo tee /etc/apt/sources.list.d/sesterce-cli.list

# Update and install
sudo apt update
sudo apt install sesterce-cli
```

### Method 3: npm (Cross-platform)

```bash
npm install -g sesterce-cli@1.0.2
```

## 🐛 Troubleshooting

### Common Issues

1. **GPG key generation fails**:

   ```bash
   # Check GPG installation
   gpg --version

   # Try interactive mode
   gpg --full-generate-key
   ```

2. **Build fails with "command not found"**:

   ```bash
   sudo apt-get install build-essential devscripts debhelper
   ```

3. **Package installs but binary doesn't work**:

   ```bash
   sudo chmod +x /usr/bin/sesterce
   ```

4. **Missing dependencies**:

   ```bash
   sudo apt-get install -f
   ```

5. **GitHub Actions fails**:
   - Check all secrets are configured
   - Verify Node.js version compatibility
   - Check build logs for specific errors

6. **semantic-release doesn't create new version**:
   - Check commit message format
   - Verify `.releaserc.json` configuration
   - Check if changes are significant enough

7. **Version mismatch error**:

   ```bash
   # Run verification script
   ./scripts/verify-version.sh

   # Check versions manually
   node -p "require('./package.json').version"
   head -1 debian/changelog
   ```

### Debugging Commands

```bash
# Check current versions
echo "npm: $(node -p "require('./package.json').version")"
echo "debian: $(head -1 debian/changelog | sed -n 's/.*(\([^)]*\)).*/\1/p')"

# Verify synchronization
./scripts/verify-version.sh

# Check semantic-release configuration
npx semantic-release --dry-run

# Check package contents
dpkg -c package.deb

# Check package info
dpkg -I package.deb

# Test installation
dpkg-deb -R package.deb /tmp/test
```

## 📋 Testing Checklist

Before releasing:

- [ ] GPG key generated and exported
- [ ] GitHub secrets configured
- [ ] Build package locally: `./scripts/build-deb.sh`
- [ ] Test package: `./scripts/test-deb.sh`
- [ ] Verify version synchronization: `./scripts/verify-version.sh`
- [ ] Install and test functionality
- [ ] Verify all files are included
- [ ] Check dependencies are correct
- [ ] Test uninstallation
- [ ] Verify semantic-release configuration

## 🔧 File Structure

```
sesterce-cli/
├── debian/                    # Debian package configuration
│   ├── control               # Package metadata and dependencies
│   ├── changelog             # Version history
│   ├── rules                 # Build instructions
│   ├── compat                # Debhelper compatibility
│   ├── sesterce-cli.install  # File installation mapping
│   └── sesterce-cli.dirs     # Directory structure
├── scripts/                   # Build and test scripts
│   ├── build-deb.sh          # Automated build script
│   ├── test-deb.sh           # Package testing script
│   └── verify-version.sh     # Version verification script
├── .github/workflows/         # GitHub Actions workflows
│   └── release.yml           # Complete release workflow
├── .releaserc.json           # semantic-release configuration
├── sesterce-cli-public.gpg   # Public GPG key (upload to repo)
├── sesterce-cli-private.gpg  # Private GPG key (add to secrets)
└── COMPLETE_SETUP_GUIDE.md   # This file
```

## 🎯 Success Metrics

Your setup is complete when:

- ✅ GPG key generated and configured
- ✅ GitHub secrets properly set
- ✅ semantic-release automatically creates new versions
- ✅ Debian package builds successfully with matching version
- ✅ GitHub Actions workflow runs without errors
- ✅ Users can install the package on Debian/Ubuntu systems
- ✅ APT repository is accessible on GitHub Pages
- ✅ Package integrates with system package management
- ✅ All platforms have synchronized versions

## 📚 Additional Resources

- [Debian Packaging Guide](https://www.debian.org/doc/manuals/maint-guide/)
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [semantic-release Documentation](https://semantic-release.gitbook.io/semantic-release/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [GPG Documentation](https://gnupg.org/documentation/)

## 🆘 Need Help?

1. Check the troubleshooting section above
2. Review GitHub Actions logs for specific errors
3. Verify all secrets are configured correctly
4. Test locally first before pushing to production
5. Check commit message format for automatic versioning
6. Ensure GPG key is properly exported and configured

---

**🎉 Congratulations!** You now have a complete, automated Debian package distribution system with GPG signing, APT repository, and semantic version management.