diff --git a/.gitignore b/.gitignore index 44ddfa8f..6861a62a 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,32 @@ -tutorial1/ \ No newline at end of file +tutorial1/ + +# Build artifacts +*.iso +*.img +*.squashfs +*.log +build.log +chroot/ +binary/ +.build/ +cache/ + +# Live-build internal dirs +iso/.build/ +iso/binary/ +iso/chroot/ +iso/cache/ +iso/.stage/ +iso/live-image-* +iso/chroot.* +iso/binary.modified_timestamps +iso/build.log + +# Offline artifact staging for Slice B/C builds +iso/config/includes.chroot_before_packages/live-artifacts/ + +# Scratch area (legacy scripts; may contain secrets) +scratch/ + +# Editor/OS junk +.DS_Store \ No newline at end of file diff --git a/B650I Lightning WiFi.pdf b/B650I Lightning WiFi.pdf new file mode 100644 index 00000000..46a70bef Binary files /dev/null and b/B650I Lightning WiFi.pdf differ diff --git a/README.md b/README.md index 720ed4e6..8969be4d 100644 --- a/README.md +++ b/README.md @@ -1,1218 +1,208 @@ # n-OS-tr -n-OS-tr is an attempt to create a nostr based operating system / distro. +**A privacy-preserving, ephemeral operating system whose identity and configuration live on [Nostr](https://nostr.com).** -We are starting with a base of debian live. +You boot n-OS-tr. It asks for a 12-word mnemonic (or generates one for you). From that mnemonic it deterministically derives every key the system needs — your personal identity, your relay keys, your blob-store keys, your mesh identity — using the standard [NIP-06](https://github.com/nostr-protocol/nips/blob/master/06.md) derivation scheme. Your preferences, dotfiles, bookmarks, and personal configuration are then loaded from Nostr relays, decrypted with your own key, and projected into your home directory on a RAM-backed filesystem. -Currently exploring different means to this end. +When you power off, **everything disappears**. There is no local trace that you were ever on this machine. -## Debian Live Build Setup and Tutorial 1 Implementation +The next time you boot — on the same machine, a different machine, a Pi in your pocket — you type the same 12 words and your environment materializes again. -This document covers the complete process of setting up live-build and implementing Tutorial 1 from the Debian Live Manual. +--- -### System Requirements +## Status -Tested on Pop!_OS 22.04 LTS (Ubuntu-based system). +- **Phase 2 Slice B+C: live.** Base ISO with [`fips`](https://github.com/) mesh daemon, [`c-relay`](https://github.com/) Nostr relay, [`ginxsom`](https://github.com/) Blossom blob server, nginx reverse proxy, first-boot provisioning, and smoke test are all green. See [`plans/slice_bc_fips_crelay.md`](plans/slice_bc_fips_crelay.md). +- **Phase 3 (identity + config): planned.** Mnemonic-driven identity subsystem and Nostr-as-home-directory are in design. See [`plans/identity_subsystem.md`](plans/identity_subsystem.md) and [`plans/nostr_config_projection.md`](plans/nostr_config_projection.md). +- **Phase 4 (Pi flavor and GUI): scoped.** Pi Zero 2 W live image and an optional amd64 GUI flavor come after the identity/config work stabilizes. -### Phase 1: Installing Dependencies +--- -The following packages are required for building Debian Live images: +## The core idea in three sentences -```bash -sudo apt update -sudo apt install debootstrap xorriso squashfs-tools syslinux-utils cpio gzip gettext +1. **One mnemonic = your whole identity.** A single BIP-39 seed phrase deterministically generates every key the OS and its apps need, via [NIP-06](https://github.com/nostr-protocol/nips/blob/master/06.md) (`m/44'/1237'/{index}'/0/0`). +2. **All config lives on Nostr.** Replaceable events signed by your main key hold your dotfiles, preferences, and per-app state, encrypted to yourself with [NIP-44](https://github.com/nostr-protocol/nips/blob/master/44.md). +3. **The OS is ephemeral.** Root filesystem is an overlay on tmpfs. Shutdown wipes memory. No persistent local state by default — not even `machine-id`, Wi-Fi credentials, or shell history. + +--- + +## The key tree + +Every key in the system is deterministically derived from your single 12-word mnemonic. Each role gets its own index on the NIP-06 derivation path: + +| Index | Role | Used by | +|-------|----------------------|------------------------------------------------------------| +| `0` | Main account | Your public Nostr identity (profile, posts, social graph) | +| `1` | Throwaway / test | Experimental account, scratch work, testing | +| `2` | c-relay admin | Admin key for your local [`c-relay`](includes/c-relay/) personal Nostr relay | +| `3` | ginxsom server | Server key for your local [`ginxsom`](includes/ginxsom/) Blossom blob store | +| `4` | fips node | Mesh node identity for the [`fips`](includes/fips/) daemon (also yields your fips IPv6) | +| `5`+ | Reserved future uses | New apps request an index from the identity agent at install time | + +An app never sees the mnemonic or the seed. It asks the local **identity agent** for "the key assigned to role X", and the agent derives and returns it (or signs on its behalf via [NIP-46](https://github.com/nostr-protocol/nips/blob/master/46.md)). Details in [`plans/identity_subsystem.md`](plans/identity_subsystem.md). + +The derivation method itself is not invented — it's standard NIP-06 and matches the reference implementation in [`/home/user/lt/client/www/tools.html`](../client/www/tools.html) (`nostr-tools.nip06.privateKeyFromSeedWords(mnemonic, "", index, 0, 0)`). + +**Crypto core.** All mnemonic handling, key derivation, event signing, NIP-44 encryption, and NIP-46 signer/bunker flows are implemented by the vendored [`includes/nostr_core_lib`](includes/nostr_core_lib/) library — a C implementation of the relevant NIPs already unit-tested in [`includes/nostr_core_lib/tests`](includes/nostr_core_lib/tests/). The identity agent and config projection services are thin wrappers around its API; n-OS-tr does not reimplement any Nostr crypto itself. + +**Language and toolchain.** Every n-OS-tr binary we ship (identity-agent, TUI, config-loader, config-writer, smoketest helpers) is **C99, statically linked against musl libc**, built inside Alpine Docker — the same pattern [`includes/nostr_core_lib`](includes/nostr_core_lib/), [`includes/ginxsom`](includes/ginxsom/), and [`includes/c-relay`](includes/c-relay/) already use. Output is self-contained static ELFs (`ldd` reports "not a dynamic executable"), identical toolchain across amd64 and arm64, no Python or Node.js at runtime. Details in [`plans/tui_login.md §0.1`](plans/tui_login.md#01-toolchain-alpine--musl-dev-built-in-docker). + +```mermaid +flowchart LR + M[12-word BIP-39 mnemonic
user enters or generates at boot] + M --> S[BIP-32 seed] + S --> D0[Index 0
main account] + S --> D1[Index 1
throwaway] + S --> D2[Index 2
c-relay admin] + S --> D3[Index 3
ginxsom] + S --> D4[Index 4
fips node] + S --> DN[Index 5..N
future roles] ``` -**Package purposes:** -- `debootstrap`: Creates minimal Debian base system -- `xorriso`: Creates ISO images -- `squashfs-tools`: Creates compressed filesystem -- `syslinux-utils`: Boot loader utilities -- `cpio`, `gzip`, `gettext`: Archive and localization utilities +--- -### Phase 2: Setting up Live-Build from Repository +## The privacy contract -Instead of installing live-build via system packages (which may be outdated), we use the repository directly for the most current version. +n-OS-tr makes a small number of hard promises to the user. These are non-negotiable; they're enforced by the image build and audited by the smoke test. The full list is in [`plans/threat_model.md`](plans/threat_model.md). -#### Creating the Wrapper Script +The short version: -Create `lb-wrapper.sh` for convenient access to live-build commands: +- **Your mnemonic never touches disk.** Not swap, not logs, not journal, not `~/.bash_history`, not crash dumps. +- **The root filesystem is ephemeral.** Every boot is a clean slate; shutdown leaves no recoverable trace on the boot media. +- **No cross-boot fingerprint.** `machine-id`, MAC address, hostname, and Wi-Fi credentials do not persist by default. +- **No on-disk logs.** systemd-journald runs in volatile mode. User app caches are tmpfs-backed. +- **Your config is encrypted on Nostr to yourself.** Relay operators see ciphertext and metadata only. Run your own [`c-relay`](includes/c-relay/) to keep even the metadata local. +- **Identity can be walked away from.** Power off, remove the USB/SD, destroy it if you want — the only recoverable identity is the one you carry in your head or on paper. -```bash -#!/bin/bash +--- -# Set the LIVE_BUILD environment variable to point to our repository -export LIVE_BUILD="$(dirname "$0")/live-build" +## Architecture at a glance -# Execute the live-build frontend with all arguments passed through -"$LIVE_BUILD/frontend/lb" "$@" +```mermaid +flowchart TB + subgraph boot[Boot sequence] + direction TB + B1[Kernel + initramfs] + B2[tmpfs overlay root
= ephemeral] + B3[privacy-hardener
MAC rand, swap off,
volatile journald,
fresh machine-id] + B4[identity-agent
prompt for 12 words
or generate new] + B5[network-bootstrap
Wi-Fi / Ethernet /
fips mesh] + B6[config-loader
Nostr replaceable events
projected to ~/] + B7[user shell or GUI] + B1 --> B2 --> B3 --> B4 --> B5 --> B6 --> B7 + end + + subgraph core[Core subsystems] + ID[identity-agent
NIP-06 derivation
NIP-46 signer] + CFG[config projection
NIP-44 encrypted] + HARD[privacy-hardener
+ shutdown-wiper] + end + + subgraph opt[Optional user services] + FIPS[fips mesh daemon] + CREL[c-relay personal relay] + GINX[ginxsom + nginx blob store] + end + + B4 --- ID + B6 --- CFG + B3 --- HARD + B7 -.optional.-> FIPS + B7 -.optional.-> CREL + B7 -.optional.-> GINX ``` -Make it executable: -```bash -chmod +x lb-wrapper.sh -``` +The "core subsystems" (identity, config, hardening) define the product. Everything else — fips, c-relay, ginxsom, nginx, the GUI, the Pi HAT drivers — is optional user-facing infrastructure layered on top. -**Usage:** Replace all `lb` commands with `./lb-wrapper.sh` to use the repository version. +--- -### Phase 3: Tutorial 1 - Default Image Creation +## Form factors -Following the Debian Live Manual Tutorial 1 to create a basic live system: +n-OS-tr is one product, delivered as multiple image flavors that all share the same core subsystems. + +| Flavor | Status | Use case | +|-------------------------------------|-----------------|------------------------------------------------------------------------------------------| +| **amd64 live ISO (text console)** | Live (Phase 2) | Boot any x86_64 laptop/desktop from USB, get a privacy-preserving session. | +| **amd64 live ISO with GUI** | Planned | Adds a minimal window manager for users who want graphical apps on the same session. | +| **Raspberry Pi Zero 2 W live image**| Planned | Pocket-sized hardware token + mesh node; Waveshare LCD HAT as the mnemonic-entry UI. | +| **Other Pi models (Pi 4, CM4)** | Possible later | Same stack, larger form factor with HDMI-GUI capable. | + +The design goal is that a user who knows their 12 words can sit down in front of any of these, boot, type their phrase, and have the same configuration materialize. See [`plans/iso_architecture.md`](plans/iso_architecture.md) for the amd64 build details today and the companion project [`raspberry_pi_zero_nostr`](../raspberry_pi_zero_nostr) for current Pi exploration work that will fold into the monorepo later. + +--- + +## Current service stack (Phase 2) + +The live Phase 2 Slice B+C ISO ships these services out of the box. They are *infrastructure for advanced users*, not the core product — the core product is identity + config, which is Phase 3. + +| Service | Role | +|--------------------------------------------------------------------------------|--------------------------------------------------------------------------| +| [`n-os-tr-firstboot`](iso/config/includes.chroot/usr/local/sbin/n-os-tr-firstboot) | Generates ephemeral service keypairs, issues self-signed TLS, configures fips interface | +| [`fips`](includes/fips/) | Nostr-addressed mesh networking daemon (virtual IPv6, mesh routing) | +| [`c-relay`](includes/c-relay/) | High-performance C Nostr relay running locally | +| [`ginxsom`](includes/ginxsom/) | Blossom blob server, served via nginx reverse proxy | +| [`nginx`](iso/config/includes.chroot/etc/nginx/sites-available/n-os-tr.conf) | TLS-terminating reverse proxy for relay and blob endpoints | +| [`n-os-tr-smoketest`](iso/config/includes.chroot/usr/local/bin/n-os-tr-smoketest) | End-to-end health check (21 checks, currently all green) | + +When Phase 3 lands, these services become **opt-in keys at NIP-06 indices 2, 3, 4** — they inherit deterministic identities from the user's mnemonic instead of generating fresh keys on first boot. + +--- + +## Planning documents + +Read these in order for the full picture: + +1. [`README.md`](README.md) — this file. Vision and structure. +2. [`plans/threat_model.md`](plans/threat_model.md) — the privacy contract. What we defend, what we don't, forbidden behaviors. +3. [`plans/identity_subsystem.md`](plans/identity_subsystem.md) — how the 12-word mnemonic becomes every key in the system. +4. [`plans/nostr_config_projection.md`](plans/nostr_config_projection.md) — how Nostr events become your home directory. +5. [`plans/iso_architecture.md`](plans/iso_architecture.md) — the current amd64 live-build architecture. +6. [`plans/slice_bc_fips_crelay.md`](plans/slice_bc_fips_crelay.md) — Phase 2 Slice B+C implementation notes (shipped). +7. [`plans/network_boot.md`](plans/network_boot.md) — research and notes on network-boot delivery options. + +--- + +## Running the current ISO + +For practical "how do I build and boot it" instructions see [`docs/RUNNING.md`](docs/RUNNING.md). + +TL;DR: ```bash -mkdir tutorial1 -cd tutorial1 -../lb-wrapper.sh config -``` - -This creates the basic configuration structure in the `config/` directory. - -### Phase 4: Building the Image - -**Important:** Due to keyring compatibility issues between Ubuntu/Pop!_OS and Debian, we need to bypass GPG verification for development builds. - -Build the image as root with security bypass: - -```bash -sudo ../lb-wrapper.sh config --apt-secure false --distribution stable -sudo ../lb-wrapper.sh build 2>&1 | tee build.log -``` - -### Keyring Issues and Troubleshooting - -**Problem:** Pop!_OS/Ubuntu keyrings are incompatible with both Debian testing and stable distributions, causing GPG verification failures. - -**Error examples:** -- Debian testing: `The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 78DBA3BC47EF2265` -- Debian stable: `The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 762F67A0B2C39DE4` - -**Solution:** Use `--apt-secure false` flag to bypass GPG verification for development purposes. - -**Production note:** For production builds, proper keyring setup should be implemented instead of disabling security checks. - -### Expected Results - -- Build time: Varies based on internet connection and system performance -- Output file: `live-image-amd64.hybrid.iso` (approximately 298MB) -- This ISO can be: - - Tested in virtual machines (QEMU, VirtualBox) - - Written to USB drives - - Burned to optical media - -### Command Summary - -Complete sequence for Tutorial 1: - -```bash -# 1. Install dependencies -sudo apt install debootstrap xorriso squashfs-tools syslinux-utils cpio gzip gettext - -# 2. Create wrapper script (if not exists) -# [Create lb-wrapper.sh as shown above] -chmod +x lb-wrapper.sh - -# 3. Create and configure tutorial -mkdir tutorial1 -cd tutorial1 -../lb-wrapper.sh config --apt-secure false --distribution stable - -# 4. Build image -sudo ../lb-wrapper.sh build 2>&1 | tee build.log - -# 5. Result: live-image-amd64.hybrid.iso ready for testing -``` - -### Notes - -- The `--distribution stable` ensures we use Debian stable instead of the default testing -- Build logs are automatically saved due to the wrapper script configuration -- The `--apt-secure false` flag is a workaround for keyring issues on Ubuntu-based systems -- For clean rebuilds, use `sudo ../lb-wrapper.sh clean` before building again - -# FAQ - -# Q: What are the auto, config, and local directories created by `lb config` for? - -**A:** When you run `lb config`, three directories are created: - -1. **auto/** - Created but empty by default - - Used for optional automation scripts that you create yourself - - You can add `auto/config`, `auto/build`, `auto/clean` scripts that run automatically before their respective `lb` commands - - Most basic builds (like Tutorial 1) don't need these files - - Useful for advanced scenarios where you want reproducible builds with version control - -2. **config/** - This is where the real configuration lives - - Contains all the subdirectories for customizing your live system - - Has the main config files (binary, bootstrap, chroot, common, source) with your build parameters - - This is where you add package lists, custom files, hooks, etc. - - Most important directory for customization - -3. **local/** - For local customizations - - Also typically empty unless you have custom executables or files to include - - Used for build-time scripts and tools, not files to include in the final system - -### Q: How do I add files to specific locations in the final live system? - -**A:** Several directories in the config structure map directly to the final system filesystem: - -**For files you want in the final live system:** - -1. **config/includes.chroot/** - Maps directly to the root filesystem (`/`) - - To put a file in `/usr/local/bin/myscript` in the final system - - Place it at `config/includes.chroot/usr/local/bin/myscript` - - Everything in this directory gets copied to `/` in the live system - -2. **config/includes.chroot_after_packages/** - Same mapping, but copied after packages are installed - - Use when you want to overwrite files that packages might have installed - - Same directory mapping as above - -3. **config/includes.chroot_before_packages/** - Copied before packages are installed - - Less commonly used, but available if needed - -**For files you want on the ISO/boot media itself (not in the live system):** - -4. **config/includes.binary/** - Files that go on the boot media - - These appear on the USB/CD itself, not inside the running live system - - Useful for documentation, additional tools, etc. - -**Example:** To put a custom script in `/usr/local/bin/hello` in your live system: -```bash -# 1. Create the directory structure -mkdir -p config/includes.chroot/usr/local/bin/ - -# 2. Put your script there -cp myscript config/includes.chroot/usr/local/bin/hello - -# 3. Make it executable -chmod +x config/includes.chroot/usr/local/bin/hello -``` - -The build process will automatically copy it to the correct location in the live system. - -### Q: How would I add a splash screen that would come up upon booting? - -**A:** There are several methods to add splash screens to your Debian Live system, depending on when and how you want the splash to appear: - -## Method 1: Boot Loader Splash (Easiest - SYSLINUX) - -For a simple graphical background during boot menu selection: - -**1. Prepare your splash image:** -```bash -# Create the bootloader directory -mkdir -p config/bootloaders/syslinux - -# Your image should be: -# - PNG or JPEG format -# - 640x480 resolution (for best compatibility) -# - Named something like splash.png -cp your-splash-image.png config/bootloaders/syslinux/splash.png -``` - -**2. Create custom syslinux configuration:** -```bash -# Copy the default syslinux config to customize -cp live-build/share/bootloaders/syslinux/* config/bootloaders/syslinux/ - -# Edit config/bootloaders/syslinux/syslinux.cfg -# Add this line after the first line: -# MENU BACKGROUND splash.png -``` - -## Method 2: Plymouth Boot Splash (Advanced - Animated) - -For professional animated boot screens like Ubuntu's spinning logo: - -**1. Add Plymouth to your package list:** -```bash -echo "plymouth plymouth-themes" >> config/package-lists/splash.list.chroot -``` - -**2. Configure Plymouth theme:** -```bash -# Create Plymouth configuration directory -mkdir -p config/includes.chroot/etc/plymouth - -# Set the default theme (example: solar theme) -echo "[Daemon]" > config/includes.chroot/etc/plymouth/plymouthd.conf -echo "Theme=solar" >> config/includes.chroot/etc/plymouth/plymouthd.conf -``` - -**3. Enable Plymouth in boot parameters:** -```bash -# When running lb config, add: -../lb-wrapper.sh config --bootappend-live "boot=live components splash quiet" -``` - -## Method 3: GRUB Graphical Splash (For EFI systems) - -For systems using GRUB (EFI boot): - -**1. Create GRUB bootloader directory:** -```bash -mkdir -p config/bootloaders/grub-pc -``` - -**2. Add custom GRUB background:** -```bash -# Copy your background image (PNG, JPG, or TGA format) -# Recommended size: 1024x768 or your target resolution -cp your-background.png config/includes.binary/boot/grub/background.png -``` - -**3. Create custom GRUB configuration:** -```bash -# Create config/bootloaders/grub-pc/grub.cfg with: -cat > config/bootloaders/grub-pc/grub.cfg << 'EOF' -if background_image /boot/grub/background.png; then - set color_normal=white/black - set color_highlight=black/light-gray -else - set menu_color_normal=cyan/blue - set menu_color_highlight=white/blue -fi -EOF -``` - -## Method 4: Desktop Splash Screen - -For splash screens that appear when the desktop environment starts: - -**1. Add to package list (example with LXDE):** -```bash -echo "lxsplash" >> config/package-lists/desktop.list.chroot -``` - -**2. Configure desktop splash:** -```bash -# Create desktop configuration directory -mkdir -p config/includes.chroot/etc/xdg/lxsession/LXDE - -# Configure lxsession to show splash -echo "lxsplash -s" > config/includes.chroot/etc/xdg/lxsession/LXDE/autostart -``` - -## Quick Start Recommendation - -**For beginners:** Start with Method 1 (SYSLINUX background) - it's simple and works reliably. - -**Example complete setup:** -```bash -# 1. Create bootloader directory and add image -mkdir -p config/bootloaders/syslinux -cp ~/my-logo.png config/bootloaders/syslinux/splash.png - -# 2. Copy default syslinux files to customize -cp -r live-build/share/bootloaders/syslinux/* config/bootloaders/syslinux/ - -# 3. Edit the main config file -sed -i '2i MENU BACKGROUND splash.png' config/bootloaders/syslinux/syslinux.cfg - -# 4. Build with your custom splash -sudo ../lb-wrapper.sh build -``` - -**Notes:** -- Image formats: PNG works best for syslinux, JPG for GRUB -- Keep images reasonably sized to avoid slowing boot time -- Test your splash screen in a virtual machine first -- For production systems, ensure images are properly licensed - -### Q: What are the main options for adding a GUI? How do I add them? - -**A:** Debian Live supports several GUI options, from lightweight window managers to full desktop environments. Here are the main options and how to implement them: - -## Lightweight Window Managers (Minimal Resource Usage) - -### 1. Openbox (Very Light) -```bash -echo "openbox obconf obmenu tint2 pcmanfm lxappearance" >> config/package-lists/gui.list.chroot -``` -**Features:** Basic window manager, highly customizable, ~50MB additional space -**Best for:** Minimal systems, older hardware, custom interfaces - -### 2. i3 (Tiling Window Manager) -```bash -echo "i3 i3status dmenu i3lock" >> config/package-lists/gui.list.chroot -``` -**Features:** Tiling window manager, keyboard-driven, very efficient -**Best for:** Power users, developers, keyboard-focused workflows - -### 3. Fluxbox -```bash -echo "fluxbox fbpanel pcmanfm" >> config/package-lists/gui.list.chroot -``` -**Features:** Fast, simple, tabbed windows -**Best for:** Minimal desktop needs, simple interfaces - -## Desktop Environments (Full-Featured) - -### 4. LXDE (Lightweight Desktop Environment) -```bash -echo "task-lxde-desktop" >> config/package-lists/gui.list.chroot -``` -**Features:** Complete desktop with panel, file manager, settings -**Size:** ~400MB additional -**Best for:** Beginner-friendly, low resource usage, complete desktop experience - -### 5. Xfce (Moderate Resource Usage) -```bash -echo "task-xfce-desktop" >> config/package-lists/gui.list.chroot -``` -**Features:** Full-featured, customizable, good performance -**Size:** ~600MB additional -**Best for:** Balance between features and performance - -### 6. GNOME (Full-Featured) -```bash -echo "task-gnome-desktop" >> config/package-lists/gui.list.chroot -``` -**Features:** Modern interface, many applications, polished experience -**Size:** ~1.5GB additional -**Best for:** Modern desktop experience, touch interfaces, latest features - -### 7. KDE Plasma (Full-Featured) -```bash -echo "task-kde-desktop" >> config/package-lists/gui.list.chroot -``` -**Features:** Highly customizable, many applications, modern interface -**Size:** ~1.2GB additional -**Best for:** Power users who want customization and modern features - -## Quick Setup Examples - -### Example 1: Minimal GUI System (LXDE + Firefox) -```bash -# Create tutorial directory -mkdir tutorial-gui -cd tutorial-gui - -# Configure with GUI -../lb-wrapper.sh config --apt-secure false --distribution stable - -# Add desktop and browser -echo "task-lxde-desktop firefox-esr" >> config/package-lists/desktop.list.chroot - -# Optional: Add useful applications -echo "synaptic gdebi leafpad galculator" >> config/package-lists/apps.list.chroot - # Build -sudo ../lb-wrapper.sh build +./build.sh --clean + +# Run locally in a VM (headless serial) +HEADLESS=1 ./scripts/run-iso.sh + +# Or flash to USB and boot real hardware +sudo dd if=iso/live-image-amd64.hybrid.iso of=/dev/sdX bs=4M status=progress ``` -### Example 2: Kiosk System (Single Application) -```bash -# Minimal X11 setup for single application -echo "xorg gdm3 openbox firefox-esr" >> config/package-lists/kiosk.list.chroot +Once booted, run [`n-os-tr-smoketest`](iso/config/includes.chroot/usr/local/bin/n-os-tr-smoketest) for an end-to-end health check. -# Auto-start Firefox in kiosk mode -mkdir -p config/includes.chroot/etc/skel -cat > config/includes.chroot/etc/skel/.xsession << 'EOF' -#!/bin/sh -openbox & -firefox --kiosk https://example.com -EOF -``` +--- -### Example 3: Developer Workstation -```bash -# Add Xfce desktop with development tools -echo "task-xfce-desktop" >> config/package-lists/desktop.list.chroot -echo "code git build-essential python3 nodejs npm" >> config/package-lists/dev.list.chroot -echo "terminator vim emacs" >> config/package-lists/editors.list.chroot -``` +## Developer notes -## GUI Components Explanation +- Historical Debian live-build reference material (tutorials, package discovery, GUI/splash options, minimization, persistence) has been moved to [`docs/debian_live_notes.md`](docs/debian_live_notes.md). Nothing in there is authoritative for the product — it's a cheatsheet we built up while bootstrapping the ISO. +- The amd64 live image is built with [`live-build`](live-build/) via [`build.sh`](build.sh). The ISO itself is produced at `iso/live-image-amd64.hybrid.iso`. +- Service artifacts staged into the ISO come from submodules under [`includes/`](includes/): [`fips`](includes/fips/) (mesh daemon), [`c-relay`](includes/c-relay/) (Nostr relay), [`ginxsom`](includes/ginxsom/) (Blossom server), and [`nostr_core_lib`](includes/nostr_core_lib/) (the C Nostr library used as the crypto core for identity and config projection). -### Essential X11 Components (Required for any GUI) -```bash -# Always needed for graphical interface -echo "xorg" >> config/package-lists/x11.list.chroot -``` +--- -### Display Managers (Login Screen) -```bash -# Lightweight -echo "lightdm" >> config/package-lists/dm.list.chroot +## Licensing and contributing -# GNOME/modern -echo "gdm3" >> config/package-lists/dm.list.chroot +TBD. The product principle is: **you should always be able to build and run this from source, verify it matches the shipped image, and run it on your own hardware with no external dependencies.** Anything that violates that principle does not belong in the product. -# Simple -echo "slim" >> config/package-lists/dm.list.chroot -``` +--- -### Common Applications by Category -```bash -# File managers -echo "pcmanfm nautilus thunar" >> config/package-lists/filemanagers.list.chroot +## Why this exists -# Text editors -echo "gedit mousepad kate" >> config/package-lists/editors.list.chroot +Operating systems today are identity sinks. They remember your SSIDs, your login history, your hostnames, your keys, your clipboard, your browsing state. When a machine changes hands — sold, seized, borrowed, stolen — those traces go with it. -# Web browsers -echo "firefox-esr chromium" >> config/package-lists/browsers.list.chroot +At the same time, Nostr gives us something new: **a place to keep identity and preferences that is not tied to any particular computer, account, server, or company**. Your keys are just math. Your preferences are just signed events. Any machine that can do elliptic-curve crypto can reconstitute your setup. -# Media players -echo "vlc mpv rhythmbox" >> config/package-lists/media.list.chroot +n-OS-tr puts those two facts together. The computer is disposable. The identity and configuration are portable. And the glue between them — the mnemonic, the derivation scheme, the config projection — is open, standard, and auditable. -# Graphics -echo "gimp inkscape" >> config/package-lists/graphics.list.chroot -``` - -## Resource Usage Comparison - -| Desktop Environment | RAM Usage | Disk Space | Boot Time | Complexity | -|-------------------|-----------|------------|-----------|------------| -| Openbox alone | ~100MB | ~50MB | Fast | Simple | -| LXDE | ~200MB | ~400MB | Fast | Easy | -| Xfce | ~300MB | ~600MB | Medium | Medium | -| GNOME | ~800MB | ~1.5GB | Slow | Complex | -| KDE Plasma | ~600MB | ~1.2GB | Medium | Complex | - -## Advanced GUI Configuration - -### Custom Desktop Theme -```bash -# Create theme directory -mkdir -p config/includes.chroot/usr/share/themes/MyTheme - -# Add custom wallpaper -mkdir -p config/includes.chroot/usr/share/pixmaps -cp my-wallpaper.jpg config/includes.chroot/usr/share/pixmaps/ - -# Set default wallpaper for LXDE -mkdir -p config/includes.chroot/etc/xdg/pcmanfm/LXDE -cat > config/includes.chroot/etc/xdg/pcmanfm/LXDE/desktop-items-0.conf << 'EOF' -[*] -wallpaper_mode=stretch -wallpaper_common=1 -wallpaper=/usr/share/pixmaps/my-wallpaper.jpg -EOF -``` - -### Auto-login Configuration -```bash -# For LXDE with automatic login -mkdir -p config/includes.chroot/etc/lightdm -cat > config/includes.chroot/etc/lightdm/lightdm.conf << 'EOF' -[Seat:*] -autologin-user=user -autologin-user-timeout=0 -EOF -``` - -## Recommendation Guide - -**For new users:** Start with LXDE (`task-lxde-desktop`) -- Easy to use -- Good performance -- Includes essential applications -- Well documented - -**For minimal systems:** Use Openbox + essential apps -- Very low resource usage -- Fast boot times -- Customizable - -**For modern experience:** Choose Xfce or GNOME -- Modern interface -- Good hardware support -- Regular updates - -**For specific use cases:** Custom combinations -- Kiosk systems: Openbox + single application -- Developer workstations: Xfce + development tools -- Media centers: Minimal WM + media applications - -# FAQ: How do I look up applications on my current system to get package names for config/package-lists? - -**Q: I want to include applications I currently use in my live system. How do I find the exact package names to add to my config/package-lists files?** - -**A:** There are several methods to discover package names from installed applications. Here are the most effective approaches: - -## Method 1: List All Installed Packages - -### Using dpkg (Debian Package Manager) -```bash -# List all installed packages with descriptions -dpkg -l | grep -i "search-term" - -# Examples: -dpkg -l | grep -i firefox # Find Firefox packages -dpkg -l | grep -i editor # Find text editors -dpkg -l | grep -i media # Find media applications -``` - -### Using apt -```bash -# List all manually installed packages -apt list --installed | grep -i "search-term" - -# Show only manually installed (not dependencies) -apt-mark showmanual | grep -i "search-term" - -# Examples: -apt list --installed | grep -i gimp -apt-mark showmanual | grep -i code -``` - -## Method 2: Find Package for Specific Application - -### Using which and dpkg -```bash -# Find which package provides a specific command -which firefox -dpkg -S $(which firefox) - -# Or in one command: -dpkg -S $(which firefox) | cut -d: -f1 - -# Examples: -dpkg -S $(which code) # Find VS Code package -dpkg -S $(which vlc) # Find VLC package -dpkg -S $(which gimp) # Find GIMP package -``` - -### Using apt-file (if installed) -```bash -# First install and update apt-file -sudo apt install apt-file -sudo apt-file update - -# Find package containing a file -apt-file search /usr/bin/firefox -apt-file search gimp - -# Find package containing any file with name -apt-file search -x '/usr/bin/.*firefox.*' -``` - -## Method 3: Application-Specific Discovery - -### Desktop Applications (.desktop files) -```bash -# List all desktop applications -ls /usr/share/applications/*.desktop | while read app; do - name=$(basename "$app" .desktop) - echo "Desktop entry: $name" - # Find which package provides this .desktop file - dpkg -S "$app" 2>/dev/null | cut -d: -f1 -done -``` - -### GUI Application Discovery -```bash -# Find packages by searching application menu names -dpkg -l | awk '/^ii/{print $2}' | while read pkg; do - if dpkg -L "$pkg" 2>/dev/null | grep -q "/usr/share/applications/"; then - echo "Package with GUI: $pkg" - fi -done -``` - -## Method 4: Category-Based Package Discovery - -### By Package Sections -```bash -# Find packages by category -dpkg-query -W -f='${Package} ${Section}\n' | grep -E "(graphics|video|audio|editors|web|games)" | sort - -# Specific categories: -dpkg-query -W -f='${Package} ${Section}\n' | grep graphics -dpkg-query -W -f='${Package} ${Section}\n' | grep editors -dpkg-query -W -f='${Package} ${Section}\n' | grep web -``` - -### By Description Content -```bash -# Search package descriptions for keywords -apt-cache search "text editor" | head -10 -apt-cache search "media player" | head -10 -apt-cache search "graphics" | head -10 -apt-cache search "development" | head -10 -``` - -## Method 5: Practical Examples - -### Common Applications and Their Package Names - -**Web Browsers:** -```bash -# What you see → Package name -Firefox → firefox-esr -Google Chrome → google-chrome-stable (requires external repository) -Chromium → chromium -``` - -**Text Editors:** -```bash -VS Code → code (requires external repository) -Sublime Text → sublime-text (requires external repository) -Vim → vim -Emacs → emacs -Nano → nano -Gedit → gedit -``` - -**Media Applications:** -```bash -VLC → vlc -GIMP → gimp -Inkscape → inkscape -Audacity → audacity -OBS Studio → obs-studio -``` - -**Development Tools:** -```bash -Git → git -Node.js → nodejs -Python → python3 -Docker → docker.io -``` - -## Method 6: Generate Package List from Current System - -### Create Complete Package List -```bash -# Generate a list of all manually installed packages -apt-mark showmanual > my-current-packages.txt - -# Clean up the list (remove system packages you don't want) -# Then use in your live-build: -cp my-current-packages.txt config/package-lists/current-system.list.chroot -``` - -### Create Filtered Package List -```bash -# Create list excluding system packages -apt-mark showmanual | grep -v -E "^(linux-|grub-|systemd|udev|apt|dpkg)" > config/package-lists/applications.list.chroot -``` - -## Method 7: Interactive Package Discovery - -### Using Synaptic Package Manager -```bash -# Install Synaptic for GUI package browsing -sudo apt install synaptic - -# Launch Synaptic, browse categories, note package names -# Then add them to your package lists -``` - -### Using aptitude (Text UI) -```bash -# Install aptitude for interactive package management -sudo apt install aptitude - -# Launch aptitude, browse packages interactively -aptitude -``` - -## Practical Workflow Example - -### Step-by-step: Adding Your Current Applications - -**1. Find your most used applications:** -```bash -# Check command history for frequently used applications -history | grep -E "^[0-9]+ (firefox|code|gimp|vlc)" | head -20 - -# Check recent application launches -ls -la ~/.local/share/recently-used.xbel 2>/dev/null -``` - -**2. Convert applications to package names:** -```bash -# Create a discovery script -cat > find-packages.sh << 'EOF' -#!/bin/bash -apps=("firefox" "code" "gimp" "vlc" "thunderbird") -for app in "${apps[@]}"; do - echo "=== $app ===" - which "$app" 2>/dev/null && dpkg -S $(which "$app") | cut -d: -f1 - echo -done -EOF - -chmod +x find-packages.sh -./find-packages.sh -``` - -**3. Create your package list:** -```bash -# Based on discoveries, create your package list -cat > config/package-lists/my-apps.list.chroot << 'EOF' -# Web and Communication -firefox-esr -thunderbird - -# Development -code -git -nodejs -python3 - -# Graphics and Media -gimp -vlc -inkscape - -# Utilities -vim -htop -tree -curl -EOF -``` - -## Tips and Best Practices - -**Package Name Variations:** -- Some applications have different names in Debian repositories -- Use `apt search application-name` to find alternatives -- Check both the main package and `-dev` packages if you need development files - -**Metapackages vs Individual Packages:** -- `task-*` packages install complete desktop environments -- Individual packages give more control over what's installed -- You can mix both approaches in different `.list.chroot` files - -**External Repositories:** -- Some applications (VS Code, Chrome) require external repositories -- Consider using alternative packages available in Debian repos (Chromium instead of Chrome) -- Document external repository requirements separately - -**Testing Package Lists:** -- Test your package lists in a virtual machine before final build -- Use `apt-cache policy package-name` to verify package availability -- Check package dependencies with `apt-cache depends package-name` - -# Q: This is live-build, so it runs in memory. Can you also install it to disk if you want? - -**A:** Yes! Debian Live systems are designed to run both ways - as temporary live systems in memory AND as permanent installations to disk. Here are your options: - -## Live vs Installed - The Difference - -**Live Mode (Default):** -- Runs entirely from USB/CD/DVD in RAM -- No changes are saved (unless using persistence - see below) -- Perfect for testing, troubleshooting, portable computing -- No installation required - boot and go - -**Installed Mode:** -- Permanently installed to hard disk like any other OS -- All changes saved normally -- Full desktop OS experience -- Can dual-boot with other operating systems - -## Installation Methods - -### Method 1: Include Debian Installer (Recommended) - -Add the installer to your live build configuration: - -```bash -# When configuring your build, enable the installer -../lb-wrapper.sh config --debian-installer live --apt-secure false --distribution stable - -# Add installer launcher to desktop -echo "debian-installer-launcher" >> config/package-lists/installer.list.chroot -``` - -**What this gives you:** -- A "Install Debian" icon on the desktop -- Full graphical installer interface -- Can install your customized system with all your packages -- Preserves all customizations during installation - -### Method 2: Text-based Installer - -For a more advanced installer interface: - -```bash -# Add text installer to config -../lb-wrapper.sh config --debian-installer true --apt-secure false --distribution stable -``` - -**Features:** -- Professional text-based installer (like server installs) -- More installation options and control -- Network-based installation capabilities -- Advanced partitioning options - -### Method 3: Live-Installer (Simpler) - -For a quick "clone live system to disk" approach: - -```bash -# Add live-installer package -echo "live-installer" >> config/package-lists/installer.list.chroot -``` - -**How it works:** -- Copies the current live system exactly to disk -- Simpler but less flexible than debian-installer -- Good for kiosk or specialized systems - -## Persistence (Hybrid Approach) - -You can also use **persistence** to save changes while staying in live mode: - -### Create Persistent USB - -```bash -# Create persistence partition on USB after writing ISO -# (This example assumes USB device is /dev/sdb - VERIFY YOUR DEVICE!) - -# 1. Write ISO to USB first -sudo dd if=live-image-amd64.hybrid.iso of=/dev/sdb bs=4M status=progress - -# 2. Create additional partition for persistence -sudo fdisk /dev/sdb -# Create new partition using remaining space - -# 3. Format persistence partition -sudo mkfs.ext4 -L persistence /dev/sdb2 - -# 4. Mount and create persistence.conf -sudo mkdir -p /mnt/persistence -sudo mount /dev/sdb2 /mnt/persistence -echo "/ union" | sudo tee /mnt/persistence/persistence.conf -sudo umount /mnt/persistence -``` - -### Enable Persistence at Boot - -Boot with persistence enabled: -```bash -# Add to boot parameters -boot=live components persistence -``` - -## Complete Installation Example - -Here's how to create a live system that can be easily installed: - -```bash -mkdir installable-system -cd installable-system - -# Configure with installer included -../lb-wrapper.sh config \ - --debian-installer live \ - --apt-secure false \ - --distribution stable \ - --bootappend-live "boot=live components" - -# Add your desktop environment -echo "task-lxde-desktop" >> config/package-lists/desktop.list.chroot - -# Add installer launcher for easy desktop installation -echo "debian-installer-launcher" >> config/package-lists/installer.list.chroot - -# Add your applications -echo "firefox-esr vlc gimp git" >> config/package-lists/apps.list.chroot - -# Build -sudo ../lb-wrapper.sh build -``` - -## Installation Process (User Experience) - -**Live Mode:** -1. Boot from USB/DVD -2. System runs in memory -3. Desktop appears with all your customizations -4. "Install Debian" icon appears on desktop (if debian-installer-launcher included) - -**Installing to Disk:** -1. Click "Install Debian" icon or run installer from menu -2. Graphical installer launches -3. Choose installation target (disk/partition) -4. All your custom packages and configurations are installed -5. Reboot to permanent system with all your customizations - -## Use Cases - -**Live-only scenarios:** -- Public computers/internet cafes -- System rescue and repair -- Software demonstration -- Portable personal desktop -- Security-focused computing (no traces left) - -**Install-to-disk scenarios:** -- Custom corporate desktop rollouts -- Specialized workstations -- Personal daily-use systems -- Educational lab systems -- Development environments - -## Key Benefits of This Approach - -1. **Try Before Install:** Test your custom system thoroughly before committing to disk -2. **Portable Development:** Same environment everywhere - USB stick becomes your entire desktop -3. **Easy Deployment:** Build once, deploy to multiple machines via installation -4. **Recovery System:** Always have a bootable rescue system with your tools -5. **Customization Preservation:** All your tweaks, themes, and applications carry over to installed system - -The beauty of Debian Live is this flexibility - you get both the convenience of a live system for testing/portability AND the option to install it permanently when you're ready! - -## FAQ: System Minimization - How Small Can You Go? - -**Q: When I ran my minimal install, and I got into the system, I see that there were apps installed such as 'ls'. Is it optional to remove those? How small an install can you go?** - -**A:** System minimization in Debian Live is possible, but there are important limitations. Core utilities like `ls` are part of essential packages that cannot be safely removed. Here's a comprehensive guide to minimization: - -### Understanding Essential vs Optional Packages - -**Essential Packages (Cannot Remove):** -- **coreutils** (includes `ls`, `cp`, `mv`, `cat`, `mkdir`, etc.) -- **bash** (shell interpreter) -- **init systems** (systemd or equivalent) -- **libc6** (core C library) -- **dpkg** (package manager) - -**Why `ls` Cannot Be Removed:** -```bash -# Check if ls is part of an essential package -dpkg -S $(which ls) -# Output: coreutils: /bin/ls - -# Check if coreutils is essential -dpkg -s coreutils | grep Essential -# Output: Essential: yes -``` - -Essential packages are marked as such because removing them would break the system fundamentally. - -### Minimization Strategies - -#### Strategy 1: Minimal Debootstrap (Recommended) - -Use the most minimal bootstrap variant: - -```bash -# Ultra-minimal configuration -../lb-wrapper.sh config \ - --apt-secure false \ - --distribution stable \ - --debootstrap-options "--variant=minbase" \ - --apt-recommends false \ - --apt-indices false \ - --firmware-chroot false \ - --memtest none \ - --binary-image hdd - -# Re-add only absolutely necessary packages -echo "user-setup sudo" > config/package-lists/essential.list.chroot - -# For network access (if needed) -echo "ifupdown isc-dhcp-client" >> config/package-lists/essential.list.chroot -``` - -**Results:** ~298MB system (compared to ~380MB default) - -#### Strategy 2: Remove Non-Essential Recommended Packages - -```bash -# Disable automatic installation of recommended packages -../lb-wrapper.sh config --apt-recommends false - -# Then manually add back only what you actually need -echo "live-tools eject" > config/package-lists/minimal-live.list.chroot -``` - -#### Strategy 3: Custom Package Exclusions - -Create hooks to remove specific non-essential packages: - -```bash -# Create removal hook -mkdir -p config/hooks/normal -cat > config/hooks/normal/0010-remove-optional.hook.chroot << 'EOF' -#!/bin/bash - -# Remove documentation to save space -rm -rf /usr/share/doc/* -rm -rf /usr/share/man/* -rm -rf /usr/share/info/* - -# Remove locale data except for English -find /usr/share/locale -mindepth 1 -maxdepth 1 -type d ! -name 'en*' -exec rm -rf {} \; - -# Remove cached package files -apt-get clean -EOF -``` - -**Warning:** This violates package integrity and may cause issues. - -### What Can Actually Be Removed - -#### Safe to Remove (Non-Essential): -```bash -# Example of packages you can safely remove/avoid -echo "# Avoid these in minimal builds" > config/package-lists/avoid.list.chroot -echo "# nano # text editor (use vi instead)" >> config/package-lists/avoid.list.chroot -echo "# wget # download utility (use curl)" >> config/package-lists/avoid.list.chroot -echo "# less # pager (use more)" >> config/package-lists/avoid.list.chroot -echo "# info # info documentation system" >> config/package-lists/avoid.list.chroot -``` - -#### Never Remove (System Will Break): -- **coreutils** (`ls`, `cp`, `mv`, `cat`, `chmod`, etc.) -- **bash** or another shell -- **init** system (systemd, sysvinit) -- **mount** utilities -- **basic device drivers** -- **kernel** and modules - -### Practical Minimization Examples - -#### Ultra-Minimal Console System -```bash -mkdir minimal-console -cd minimal-console - -# Minimal console-only configuration -../lb-wrapper.sh config \ - --debootstrap-options "--variant=minbase" \ - --apt-recommends false \ - --apt-indices false \ - --firmware-chroot false \ - --memtest none \ - --bootappend-live "boot=live components noautologin" \ - --binary-image hdd - -# Add only essential packages -cat > config/package-lists/minimal.list.chroot << 'EOF' -user-setup -sudo -ifupdown -isc-dhcp-client -vim-tiny -EOF - -# Build ultra-minimal system -sudo ../lb-wrapper.sh build -``` - -**Expected size:** ~250-280MB - -#### Minimal GUI System -```bash -mkdir minimal-gui -cd minimal-gui - -# Minimal GUI configuration -../lb-wrapper.sh config \ - --debootstrap-options "--variant=minbase" \ - --apt-recommends false \ - --apt-indices false \ - --firmware-chroot false \ - --memtest none - -# Minimal X11 setup -cat > config/package-lists/minimal-gui.list.chroot << 'EOF' -user-setup -sudo -xorg -openbox -pcmanfm -lxterminal -firefox-esr -EOF - -# Network support -echo "ifupdown isc-dhcp-client wireless-tools wpasupplicant" >> config/package-lists/network.list.chroot -``` - -**Expected size:** ~400-500MB - -### Size Comparison Table - -| Configuration Type | Size | Boot Time | Functionality | -|-------------------|------|-----------|---------------| -| Default Tutorial 1 | ~380MB | Medium | Basic console + live tools | -| Minimal (minbase) | ~280MB | Fast | Essential console only | -| Ultra-minimal hook | ~250MB | Very fast | Bare minimum (risky) | -| Minimal GUI | ~450MB | Medium | Basic graphical interface | -| Full LXDE | ~800MB | Slow | Complete desktop | - -### Advanced Minimization Techniques - -#### Using Alternative Core Utilities - -Replace some utilities with smaller alternatives: - -```bash -# Use busybox for some utilities (saves space) -echo "busybox-static" >> config/package-lists/alternatives.list.chroot - -# Create hook to replace some standard utilities with busybox -cat > config/hooks/normal/0020-busybox-alternatives.hook.chroot << 'EOF' -#!/bin/bash -# Replace some utilities with busybox versions -# (Only do this if you understand the implications) -for util in vi less; do - if [ -f /bin/busybox ]; then - update-alternatives --install /usr/bin/$util $util /bin/busybox 50 - fi -done -EOF -``` - -#### Locale Minimization - -```bash -# Build with single locale only -../lb-wrapper.sh config --bootappend-live "boot=live components locales=en_US.UTF-8" - -# Remove extra locales via hook -cat > config/hooks/normal/0030-locale-cleanup.hook.chroot << 'EOF' -#!/bin/bash -# Keep only English locales -find /usr/share/locale -mindepth 1 -maxdepth 1 -type d ! -name 'en*' -delete -find /usr/share/i18n/locales -mindepth 1 -maxdepth 1 -type f ! -name 'en_*' -delete -EOF -``` - -### The Bottom Line: Practical Limits - -**Theoretical minimum:** ~180-200MB (unstable, breaks functionality) -**Practical minimum:** ~250-280MB (stable, console-only) -**Recommended minimum:** ~350-400MB (includes basic GUI capability) - -### Why You Can't Remove Core Utilities - -**System Dependencies:** -```bash -# Check what depends on coreutils -apt-cache rdepends coreutils | head -20 -# Shows hundreds of packages depend on basic utilities - -# Check essential status -dpkg-query -Wf='${Package} ${Essential}\n' | grep yes -# Shows all essential packages that cannot be removed -``` - -**Package Manager Protection:** -- APT/dpkg prevents removal of essential packages -- Essential packages are hardcoded in Debian Policy -- Removing them requires `--force-depends` (dangerous) - -### Best Practices for Minimization - -1. **Start with `--debootstrap-options "--variant=minbase"`** - safest reduction -2. **Disable recommendations** with `--apt-recommends false` -3. **Remove documentation/locales** via hooks if space is critical -4. **Test thoroughly** - minimal systems may lack expected tools -5. **Document what you removed** for troubleshooting -6. **Consider alternatives** like Alpine Linux for truly minimal containers - -**Remember:** Core utilities like `ls`, `cp`, `mv` are fundamental to Unix-like systems. They're in essential packages for a reason - removing them will break your system. Focus on removing optional packages, documentation, and recommended packages instead of core system utilities. - -The goal should be "minimal but functional" rather than "absolutely smallest possible" for any system you plan to actually use. +That's the product. diff --git a/build.sh b/build.sh new file mode 100755 index 00000000..a8b869aa --- /dev/null +++ b/build.sh @@ -0,0 +1,149 @@ +#!/bin/bash +# build.sh — build the n-OS-tr live ISO +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +WORKSPACE_ISO_DIR="$REPO_ROOT/iso" +WORKSPACE_ISO="$WORKSPACE_ISO_DIR/live-image-amd64.hybrid.iso" +BUILD_LOG="$WORKSPACE_ISO_DIR/build.log" +ARTIFACTS_DIR="$WORKSPACE_ISO_DIR/config/includes.chroot_before_packages/live-artifacts" +CRELAY_SOURCE="$REPO_ROOT/includes/c_relay_static_x86_64" +NOSTR_ID_TUI_SOURCE_DIR="$REPO_ROOT/stack/nostr-id-tui" +NOSTR_ID_TUI_BINARY="$NOSTR_ID_TUI_SOURCE_DIR/build/nostr-id-tui_static_x86_64" + +CLEAN_REQUESTED=0 +if [[ "${1:-}" == "--clean" ]]; then + CLEAN_REQUESTED=1 + shift +fi + +if [[ "$#" -ne 0 ]]; then + echo "[build.sh] unsupported arguments: $*" >&2 + echo "[build.sh] usage: ./build.sh [--clean]" >&2 + exit 2 +fi + +home_opts="$(findmnt -n -o OPTIONS /home 2>/dev/null || true)" +if [[ "$home_opts" == *nodev* ]]; then + NEED_BIND=1 +else + NEED_BIND=0 +fi + +cleanup_artifacts() { + echo "[build.sh] cleaning prior build artifacts in $WORKSPACE_ISO_DIR" + sudo rm -rf \ + "$WORKSPACE_ISO_DIR/.build" \ + "$WORKSPACE_ISO_DIR/cache" \ + "$WORKSPACE_ISO_DIR/chroot" \ + "$WORKSPACE_ISO_DIR/binary" + + sudo rm -f \ + "$WORKSPACE_ISO_DIR"/live-image-* \ + "$WORKSPACE_ISO_DIR"/chroot.* \ + "$WORKSPACE_ISO_DIR"/binary.modified_timestamps \ + "$WORKSPACE_ISO_DIR"/build.log +} + +stage_slice_bc_artifacts() { + echo "[build.sh] staging Slice B/C artifacts in $ARTIFACTS_DIR" + mkdir -p "$ARTIFACTS_DIR" + + if [[ ! -f "$CRELAY_SOURCE" ]]; then + echo "[build.sh] ERROR: missing c-relay binary at $CRELAY_SOURCE" >&2 + exit 1 + fi + cp "$CRELAY_SOURCE" "$ARTIFACTS_DIR/c_relay_x86" + chmod 0755 "$ARTIFACTS_DIR/c_relay_x86" + echo "[build.sh] staged c-relay binary" + + if ! command -v cargo-deb >/dev/null 2>&1; then + echo "[build.sh] ERROR: cargo-deb not installed. Run: cargo install cargo-deb" >&2 + exit 1 + fi + + echo "[build.sh] building fips .deb" + ( + cd "$REPO_ROOT/includes/fips" + ./packaging/debian/build-deb.sh + ) + + FIPS_DEB="$(ls -1t "$REPO_ROOT"/includes/fips/deploy/fips_*_amd64.deb 2>/dev/null | head -1 || true)" + if [[ -z "$FIPS_DEB" || ! -f "$FIPS_DEB" ]]; then + echo "[build.sh] ERROR: no fips_*_amd64.deb produced in includes/fips/deploy" >&2 + exit 1 + fi + + rm -f "$ARTIFACTS_DIR"/fips_*_amd64.deb + cp "$FIPS_DEB" "$ARTIFACTS_DIR/" + echo "[build.sh] staged $(basename "$FIPS_DEB")" + echo "[build.sh] building nostr-id-tui static musl binary" + ( + cd "$NOSTR_ID_TUI_SOURCE_DIR" + ./build_static.sh + ) + + if [[ ! -f "$NOSTR_ID_TUI_BINARY" ]]; then + echo "[build.sh] ERROR: nostr-id-tui static build produced no binary at $NOSTR_ID_TUI_BINARY" >&2 + exit 1 + fi + + cp "$NOSTR_ID_TUI_BINARY" "$ARTIFACTS_DIR/nostr-id-tui_x86_64" + chmod 0755 "$ARTIFACTS_DIR/nostr-id-tui_x86_64" + echo "[build.sh] staged nostr-id-tui static binary" +} + +if [[ "$CLEAN_REQUESTED" -eq 1 ]]; then + cleanup_artifacts +fi + +SCRATCH="" +BUILD_DIR="" +CLEANUP() { + if [[ -n "$SCRATCH" ]]; then + if mountpoint -q "$SCRATCH"; then + sudo umount -R "$SCRATCH" 2>/dev/null || sudo umount -l "$SCRATCH" || true + fi + rmdir "$SCRATCH" 2>/dev/null || true + fi +} +trap CLEANUP EXIT + +if [[ "$NEED_BIND" -eq 1 ]]; then + echo "[build.sh] /home has nodev mount option; building via bind-mounted scratch workspace" + SCRATCH="/var/tmp/n-os-tr-build-$$-$(date +%s)" + mkdir -p "$SCRATCH" + sudo mount --bind "$REPO_ROOT" "$SCRATCH" + echo "[build.sh] remounting scratch bind with dev to allow chroot /dev/null usage" + sudo mount -o remount,bind,dev "$SCRATCH" + + scratch_opts="$(findmnt -n -o OPTIONS "$SCRATCH" 2>/dev/null || true)" + if [[ "$scratch_opts" == *nodev* ]]; then + echo "[build.sh] ERROR: scratch bind still has nodev after remount: $scratch_opts" >&2 + echo "[build.sh] cannot safely run live-build chroot on a nodev mount" >&2 + exit 1 + fi + + BUILD_DIR="$SCRATCH/iso" +else + echo "[build.sh] /home is not nodev; building directly in workspace" + BUILD_DIR="$WORKSPACE_ISO_DIR" +fi + +if [[ ! -d "$BUILD_DIR" ]]; then + echo "[build.sh] build directory missing: $BUILD_DIR" >&2 + exit 1 +fi + +stage_slice_bc_artifacts + +cd "$BUILD_DIR" +sudo "$REPO_ROOT/lb-wrapper.sh" config +sudo "$REPO_ROOT/lb-wrapper.sh" build 2>&1 | tee "$BUILD_LOG" + +if [[ ! -f "$WORKSPACE_ISO" ]]; then + echo "[build.sh] build produced no ISO at $WORKSPACE_ISO; see $BUILD_LOG" >&2 + exit 1 +fi + +ls -lh "$WORKSPACE_ISO" diff --git a/docs/RUNNING.md b/docs/RUNNING.md new file mode 100644 index 00000000..ac2f79ca --- /dev/null +++ b/docs/RUNNING.md @@ -0,0 +1,42 @@ +# Running n-OS-tr ISO (Phase 2 Slice B+C) + +This slice boots a live system with these services enabled: + +- `n-os-tr-firstboot.service` (oneshot): generates a per-boot ginxsom identity and self-signed TLS cert. +- `ginxsom.service`: Blossom FastCGI server on `/run/ginxsom/ginxsom-fcgi.sock`. +- `nginx.service`: TLS front-end on `https://localhost/`. +- `fips.service` + `fips-dns.service`: mesh transport and DNS responder. +- `c-relay.service`: Nostr relay behind nginx. + +## Endpoints + +- Landing page: `https://localhost/` +- Relay websocket: `wss://localhost/relay` +- Relay admin/API: `https://localhost/admin/` + +## Retrieve generated identity + +- Ginxsom pubkey and key hints are shown in `/etc/motd`. +- Provisioning logs: `journalctl -u n-os-tr-firstboot.service` +- Ginxsom nsec: `cat /var/lib/n-os-tr/keys/ginxsom.nsec` +- fips node identity (npub): `fipsctl identity` +- c-relay admin key from first boot logs: `journalctl -u c-relay.service | grep 'Admin Private Key:'` + +## Smoke test + +Run [`n-os-tr-smoketest`](iso/config/includes.chroot/usr/local/bin/n-os-tr-smoketest) for a one-line-per-check health summary across core + blossom + fips + relay services, with output shaped like `[PASS|FAIL|SKIP]