mirror of https://github.com/bohanyang/debi
Brent, Yang Bohan
4 months ago
parent
1f735da114
commit
804b2e05a1
5 changed files with 161 additions and 25 deletions
@ -0,0 +1,100 @@ |
||||
# CLAUDE.md |
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
||||
|
||||
## Project Overview |
||||
|
||||
Debi is a Debian Network Reinstall Script that allows reinstalling any VPS or physical machine to minimal Debian via network boot. It's a single POSIX-compliant shell script that automates the entire Debian installation process. |
||||
|
||||
## Commands |
||||
|
||||
### Running the Script |
||||
```bash |
||||
# Basic execution (requires root) |
||||
sudo ./debi.sh |
||||
|
||||
# With options |
||||
sudo ./debi.sh --user debian --timezone UTC --cloudflare |
||||
|
||||
# Dry run (generate config without installing) |
||||
sudo ./debi.sh --dry-run |
||||
|
||||
# With cloud-init configuration |
||||
sudo ./debi.sh --cidata ./cidata-example/ |
||||
``` |
||||
|
||||
### Testing Changes |
||||
```bash |
||||
# Check shell script syntax |
||||
sh -n debi.sh |
||||
|
||||
# Run shellcheck for linting (if available) |
||||
shellcheck debi.sh |
||||
|
||||
# Test in a VM environment (recommended) |
||||
# No automated test suite exists - manual testing required |
||||
``` |
||||
|
||||
## Architecture |
||||
|
||||
The script operates in distinct phases: |
||||
|
||||
1. **Configuration Phase**: Parses command-line arguments and validates environment |
||||
2. **Download Phase**: Fetches Debian installer components to `/boot/debian-$VERSION/` |
||||
3. **Preseed Generation**: Creates automated installation configuration |
||||
4. **GRUB Modification**: Adds installer entry to bootloader menu |
||||
5. **Initramfs Injection**: Embeds preseed and network configuration into installer |
||||
6. **Execution**: Updates GRUB and prepares for reboot |
||||
|
||||
Key architectural decisions: |
||||
- Single-file design for easy distribution |
||||
- POSIX compliance for maximum compatibility |
||||
- No external dependencies beyond standard Linux utilities |
||||
- Modular function design with clear separation of concerns |
||||
- Extensive error handling with rollback capabilities |
||||
|
||||
## Key Functions and Their Purposes |
||||
|
||||
- `download()`: Handles file downloads with proxy support and multiple backend options (wget/curl/busybox) |
||||
- `set_debian_version()` / `set_suite()`: Manages Debian version selection and mirror URLs |
||||
- `configure_sshd()`: Sets up SSH access during installation for remote monitoring |
||||
- `in_target()`: Executes commands within the target installation environment |
||||
- `prompt_password()`: Securely handles password input with validation |
||||
|
||||
## Important Configuration Variables |
||||
|
||||
The script uses 80+ configuration options. Key ones include: |
||||
- `$suite`: Debian version (bookworm, bullseye, etc.) |
||||
- `$mirror_protocol` / `$mirror_host`: APT repository configuration |
||||
- `$disk`: Target installation disk |
||||
- `$authorized_keys_url`: SSH key provisioning |
||||
- `$cidata`: Cloud-init configuration directory |
||||
|
||||
## Development Guidelines |
||||
|
||||
1. **Maintain POSIX compliance** - Script must work with dash/sh, not just bash |
||||
2. **Test on real systems** - No test suite exists; changes require VM or physical testing |
||||
3. **Preserve backward compatibility** - Many users rely on specific option behaviors |
||||
4. **Document all options** - Update README.md for any new configuration options |
||||
5. **Handle errors gracefully** - Always provide rollback paths for critical operations |
||||
|
||||
## Common Development Tasks |
||||
|
||||
### Adding New Configuration Options |
||||
1. Add option to the case statement in the argument parsing section |
||||
2. Define corresponding variable with sensible default |
||||
3. Implement logic in appropriate phase function |
||||
4. Update README.md documentation |
||||
|
||||
### Debugging Installation Issues |
||||
1. Use `--dry-run` to generate and inspect preseed configuration |
||||
2. Enable network console with `--ssh` for remote debugging |
||||
3. Check `/boot/debian-$VERSION/` for downloaded components |
||||
4. Review GRUB configuration changes in `/boot/grub/grub.cfg` |
||||
|
||||
### Testing Platform Compatibility |
||||
Focus areas for testing: |
||||
- Network configuration (static IP vs DHCP) |
||||
- Disk detection and partitioning |
||||
- GRUB installation and boot entries |
||||
- Architecture-specific installer components |
||||
Loading…
Reference in new issue