Update documentation to reflect setup scripts
This commit is contained in:
Albert Armea
parent
fc0c1ce51d
commit
9c14fe5ccd
4 changed files with 342 additions and 45 deletions
|
|
@ -4,7 +4,8 @@
|
|||
|
||||
### tl;dr
|
||||
|
||||
You need a Wayland-capable Linux system, Rust, and a small set of system dependencies. Once installed, `./run-dev` will start a development instance.
|
||||
You need a Wayland-capable Linux system, Rust, and a small set of system
|
||||
dependencies. Once installed, `./run-dev` will start a development instance.
|
||||
|
||||
### Requirements
|
||||
|
||||
|
|
@ -15,14 +16,40 @@ You need a Wayland-capable Linux system, Rust, and a small set of system depende
|
|||
|
||||
2. **System dependencies**
|
||||
|
||||
* Platform-specific packages are required.
|
||||
* For Ubuntu, see the [`SYSTEM_DEPS` section in the CI configuration](./.github/workflows/ci.yml).
|
||||
* Platform-specific packages are required for building and running.
|
||||
* View packages with: `./scripts/shepherd deps print dev`
|
||||
* Install all dev dependencies: `./scripts/shepherd deps install dev`
|
||||
* **Note**: Rust is automatically installed via rustup when installing build or dev dependencies.
|
||||
|
||||
3. **Rust toolchain**
|
||||
### Unified script system
|
||||
|
||||
```sh
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
`shepherd-launcher` provides a unified script system for managing dependencies, building, and running:
|
||||
|
||||
```sh
|
||||
# View and install dependencies
|
||||
./scripts/shepherd deps print dev # List all dev dependencies
|
||||
./scripts/shepherd deps install dev # Install all dev dependencies
|
||||
|
||||
# Build binaries
|
||||
./scripts/shepherd build # Debug build
|
||||
./scripts/shepherd build --release # Release build
|
||||
|
||||
# Development
|
||||
./scripts/shepherd dev run # Build and run in nested Sway
|
||||
```
|
||||
|
||||
For CI/build-only environments:
|
||||
```sh
|
||||
./scripts/shepherd deps install build # Build dependencies only
|
||||
./scripts/shepherd build --release # Production build
|
||||
```
|
||||
|
||||
For runtime-only systems:
|
||||
```sh
|
||||
./scripts/shepherd deps install run # Runtime dependencies only
|
||||
```
|
||||
|
||||
See `./scripts/shepherd --help` for all available commands.
|
||||
|
||||
### Running in development
|
||||
|
||||
|
|
|
|||
49
README.md
49
README.md
|
|
@ -74,29 +74,6 @@ If it can run on Linux in *any way, shape, or form*, it can be supervised by
|
|||
|
||||
> [A Short Hike](https://ashorthike.com/) running via Steam
|
||||
|
||||
Contributions are welcome for improvements and not yet implemented backends,
|
||||
such as:
|
||||
* Content-aware media player with supervised libraries
|
||||
([#3](https://github.com/aarmea/shepherd-launcher/issues/3))
|
||||
* Pre-booted Steam to improve launch time
|
||||
([#4](https://github.com/aarmea/shepherd-launcher/issues/4))
|
||||
* Android apps via Waydroid, including pre-booting Android if necessary
|
||||
([#5](https://github.com/aarmea/shepherd-launcher/issues/5))
|
||||
* Legacy Win9x via DOSBox, QEMU, or PCem, including scripts to create a boot-to-app image
|
||||
([#6](https://github.com/aarmea/shepherd-launcher/issues/6))
|
||||
* Chrome
|
||||
([#7](https://github.com/aarmea/shepherd-launcher/issues/7)),
|
||||
including strict sandboxing and support for firewall rules
|
||||
([#8](https://github.com/aarmea/shepherd-launcher/issues/8))
|
||||
* Awareness of whether an Internet connection is available, and an availability
|
||||
rule that gates activities based on this
|
||||
([#9](https://github.com/aarmea/shepherd-launcher/issues/9))
|
||||
* Porting to other *host* platforms, such as a Microsoft Windows shell
|
||||
replacement or macOS kiosk via MDM. `shepherd-launcher` is architected such
|
||||
that `shepherdd`, the core enforcement service, does not render any UI and
|
||||
performs platform-specific functions like process management in
|
||||
platform-specific crates.
|
||||
|
||||
## Core concepts
|
||||
|
||||
* **Launcher-first**: only one foreground activity at a time
|
||||
|
|
@ -113,16 +90,12 @@ such as:
|
|||
|
||||
## Installation
|
||||
|
||||
`shepherd-launcher` is pre-alpha and in active development. As such, end-user
|
||||
binaries and installation instructions are not yet available.
|
||||
`shepherd-launcher` is pre-alpha and in active development. The helper at
|
||||
`./scripts/shepherd` can be used to build and install a *fully functional*
|
||||
local kiosk setup from source:
|
||||
|
||||
See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to run in development.
|
||||
|
||||
Contributions are welcome for:
|
||||
* a CI step that generates production binaries
|
||||
([#1](https://github.com/aarmea/shepherd-launcher/issues/1))
|
||||
* an installation script
|
||||
([#2](https://github.com/aarmea/shepherd-launcher/issues/2))
|
||||
Check out this repository and run `./scripts/shepherd --help` or see
|
||||
[INSTALL.md](./docs/INSTALL.md) for more.
|
||||
|
||||
## Example configuration
|
||||
|
||||
|
|
@ -158,11 +131,6 @@ max_run_seconds = 1800 # 30 minutes (roughly 3 in-game days)
|
|||
daily_quota_seconds = 3600 # 1 hour per day
|
||||
cooldown_seconds = 600 # 10 minute cooldown
|
||||
|
||||
[[entries.warnings]]
|
||||
seconds_before = 600
|
||||
severity = "info"
|
||||
message = "10 minutes left - start wrapping up!"
|
||||
|
||||
[[entries.warnings]]
|
||||
seconds_before = 120
|
||||
severity = "warn"
|
||||
|
|
@ -178,7 +146,12 @@ See [config.example.toml](./config.example.toml) for more.
|
|||
|
||||
## Development
|
||||
|
||||
See [CONTRIBUTING.md](./CONTRIBUTING.md)
|
||||
Build instructions and contribution guidelines are described in
|
||||
[CONTRIBUTING.md](./CONTRIBUTING.md).
|
||||
|
||||
If you'd like to help out, look on
|
||||
[GitHub Issues](https://github.com/aarmea/shepherd-launcher/issues) for
|
||||
potential work items.
|
||||
|
||||
## Written in 2025, responsibly
|
||||
|
||||
|
|
|
|||
66
docs/INSTALL.md
Normal file
66
docs/INSTALL.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# Installation
|
||||
|
||||
`shepherd-launcher` can be installed on Linux with a modern Wayland compositor.
|
||||
It is currently developed and tested on Ubuntu 25.10.
|
||||
|
||||
`shepherd-launcher` currently must be built from source. `./scripts/shepherd`
|
||||
can help set up your build environment and manage your installation.
|
||||
|
||||
## Basic setup
|
||||
|
||||
```sh
|
||||
# 0. Install build dependencies
|
||||
sudo ./scripts/shepherd deps build run
|
||||
|
||||
# 1. Install runtime dependencies
|
||||
sudo ./scripts/shepherd deps install run
|
||||
|
||||
# 2. Build release binaries
|
||||
./scripts/shepherd build --release
|
||||
|
||||
# 3. Install everything for a kiosk user
|
||||
sudo ./scripts/shepherd install all --user kiosk
|
||||
```
|
||||
|
||||
This installs:
|
||||
- Binaries to `/usr/local/bin/`
|
||||
- System Sway configuration to `/etc/sway/shepherd.conf`
|
||||
- Display manager desktop entry ("Shepherd Kiosk" session)
|
||||
- System config template to `/etc/shepherd/config.toml`
|
||||
- User config to `~kiosk/.config/shepherd/config.toml`
|
||||
|
||||
For custom installation paths:
|
||||
```sh
|
||||
# Install to /usr instead of /usr/local
|
||||
sudo ./scripts/shepherd install all --user kiosk --prefix /usr
|
||||
```
|
||||
|
||||
Individual installation steps can be run separately:
|
||||
```sh
|
||||
sudo ./scripts/shepherd install bins --prefix /usr/local
|
||||
sudo ./scripts/shepherd install config --user kiosk
|
||||
```
|
||||
|
||||
## Kiosk hardening (optional)
|
||||
|
||||
Kiosk hardening is optional and intended for devices primarily used by
|
||||
children, not developer machines.
|
||||
|
||||
```sh
|
||||
sudo ./scripts/shepherd harden apply --user kiosk
|
||||
```
|
||||
|
||||
This restricts the user to only access the Shepherd session by:
|
||||
- Denying SSH access
|
||||
- Restricting console (TTY) login
|
||||
- Denying sudo access
|
||||
- Restricting shell to Sway sessions only
|
||||
|
||||
To revert (all changes are reversible):
|
||||
```sh
|
||||
sudo ./scripts/shepherd harden revert --user kiosk
|
||||
```
|
||||
|
||||
## Complete documentation
|
||||
|
||||
See the scripts' [README](../scripts/README.md) for more.
|
||||
231
docs/ai/history/2025-12-31 001 scripts.md
Normal file
231
docs/ai/history/2025-12-31 001 scripts.md
Normal file
|
|
@ -0,0 +1,231 @@
|
|||
This prompt created the setup script ecosystem, including CI setup, dev setup, and end-user installation and configuration. It was provided to Claude Opus 4.5 via VSCode Agent mode.
|
||||
|
||||
The first draft was written by ChatGPT after some back-and-forth [in this conversation](https://chatgpt.com/share/6955f5ee-46f4-800b-87bc-db0e3df16541).
|
||||
|
||||
The output was committed as fc0c1ce51d739aafcdce66f6958f008ef056a76a.
|
||||
|
||||
-----
|
||||
|
||||
# Task: Implement unified script system for dev, build, install, and user hardening
|
||||
|
||||
## Objective
|
||||
|
||||
Implement a **single, composable script system** that:
|
||||
|
||||
* Avoids duplication between CI, developer, and runtime workflows
|
||||
* Exposes clear, reversible primitives for build, install, and user hardening
|
||||
* Uses one authoritative entrypoint with subcommands
|
||||
* Allows CI, developers, and administrators to invoke the *same logic* with different scopes
|
||||
|
||||
The system must support:
|
||||
|
||||
* CI build-only environments
|
||||
* Runtime-only systems
|
||||
* Developer systems (union of build + runtime deps)
|
||||
* Production installation and kiosk-style user hardening
|
||||
|
||||
---
|
||||
|
||||
## High-level design constraints
|
||||
|
||||
* **One CLI entrypoint** (script-based), with subcommands
|
||||
* **Shared logic lives in libraries**, not duplicated scripts
|
||||
* **All tasks must be independently callable**
|
||||
* **All destructive actions must be reversible**
|
||||
* **Dependency sets must be defined once and derived programmatically**
|
||||
* Shell scripts are acceptable and preferred for system integration
|
||||
|
||||
---
|
||||
|
||||
## Required repository layout
|
||||
|
||||
```
|
||||
scripts/
|
||||
shepherd # main CLI dispatcher
|
||||
dev # thin wrapper → shepherd dev run
|
||||
admin # optional wrapper → shepherd admin ...
|
||||
|
||||
lib/
|
||||
common.sh # logging, error handling, sudo helpers
|
||||
deps.sh # dependency set logic
|
||||
build.sh # cargo build logic
|
||||
sway.sh # nested sway execution helpers
|
||||
install.sh # binary + config installation
|
||||
harden.sh # harden / unharden user logic
|
||||
|
||||
deps/
|
||||
build.pkgs # build-only system packages
|
||||
run.pkgs # runtime-only system packages
|
||||
dev.pkgs # optional dev-only extras
|
||||
```
|
||||
|
||||
No business logic should live in `Makefile` (if present).
|
||||
|
||||
---
|
||||
|
||||
## CLI interface (must be implemented)
|
||||
|
||||
### Dependency management
|
||||
|
||||
```
|
||||
shepherd deps print build|run|dev
|
||||
shepherd deps install build|run|dev
|
||||
```
|
||||
|
||||
Behavior:
|
||||
|
||||
* `build` = build.pkgs
|
||||
* `run` = run.pkgs
|
||||
* `dev` = union(build, run, dev.pkgs)
|
||||
* No duplicated lists anywhere
|
||||
|
||||
The build packages are currently listed in the CI definition (./.github/workflows/ci.yml). The CI definition should be updated to use this script for package management.
|
||||
You may leave a stub for the runtime packages that only includes `sway`.
|
||||
|
||||
You may assume Ubuntu 25.10 or higher. Warn but do not fail if the environment indicates otherwise.
|
||||
|
||||
---
|
||||
|
||||
### Build
|
||||
|
||||
```
|
||||
shepherd build # debug build
|
||||
shepherd build --release # production build
|
||||
```
|
||||
|
||||
Internals:
|
||||
|
||||
* Wrap `cargo build`
|
||||
* Centralize binary names and target paths
|
||||
* No logic duplication in dev/run/install paths
|
||||
|
||||
---
|
||||
|
||||
### Development run
|
||||
|
||||
```
|
||||
shepherd dev run
|
||||
```
|
||||
|
||||
This should be functionally equivalent to what is currently in `./run-dev` and will serve as its replacement.
|
||||
|
||||
Behavior:
|
||||
|
||||
* Builds (debug)
|
||||
* Launches **nested sway**
|
||||
* Executes built binaries with correct environment
|
||||
|
||||
This should reuse shared sway helpers (not inline logic).
|
||||
|
||||
---
|
||||
|
||||
### Installation (composable steps)
|
||||
|
||||
Each step must be callable independently.
|
||||
|
||||
```
|
||||
shepherd install bins [--prefix PREFIX]
|
||||
shepherd install config --user USER [--source CONFIG]
|
||||
shepherd install all --user USER [--prefix PREFIX]
|
||||
```
|
||||
|
||||
Requirements:
|
||||
|
||||
* Install release binaries to standard paths
|
||||
* Install our global Sway configuration to a standard path
|
||||
* Install desktop entry that tells the display manager to run shepherd-launcher via the Sway configuration (you will need to write this)
|
||||
* Support PREFIX and DESTDIR
|
||||
* Deploy example config to a specified user
|
||||
* Do not assume hardening is enabled
|
||||
|
||||
---
|
||||
|
||||
### User hardening (reversible)
|
||||
|
||||
```
|
||||
shepherd harden apply --user USER
|
||||
shepherd harden revert --user USER
|
||||
```
|
||||
|
||||
Requirements:
|
||||
|
||||
* Harden a user so it can only run shepherd-launcher
|
||||
* Support reverting to original system state
|
||||
* Persist rollback state under:
|
||||
|
||||
```
|
||||
/var/lib/shepherdd/hardening/<user>/
|
||||
```
|
||||
* Hardening and unharden must be idempotent
|
||||
|
||||
No assumptions about display manager; logic should be isolated.
|
||||
|
||||
---
|
||||
|
||||
## Shared library responsibilities
|
||||
|
||||
### `lib/common.sh`
|
||||
|
||||
* Logging (`info`, `warn`, `error`)
|
||||
* `require_root`, `maybe_sudo`
|
||||
* Safe command execution helpers
|
||||
|
||||
### `lib/deps.sh`
|
||||
|
||||
* Read package lists
|
||||
* Compute unions
|
||||
* Install or print packages
|
||||
|
||||
### `lib/build.sh`
|
||||
|
||||
* Cargo build abstraction
|
||||
* Debug vs release handling
|
||||
* Binary discovery
|
||||
|
||||
### `lib/sway.sh`
|
||||
|
||||
* Nested sway environment setup
|
||||
* Command execution inside sway
|
||||
* Shared by dev and production paths
|
||||
|
||||
### `lib/install.sh`
|
||||
|
||||
* Binary install logic
|
||||
* Config deployment logic
|
||||
|
||||
### `lib/harden.sh`
|
||||
|
||||
* Apply hardening
|
||||
* Revert hardening
|
||||
* Track system state changes
|
||||
|
||||
---
|
||||
|
||||
## Wrapper scripts
|
||||
|
||||
* `./run-dev` → `exec ./scripts/shepherd dev run`
|
||||
* Optional `Makefile` targets may call `shepherd`, but must contain no logic
|
||||
|
||||
---
|
||||
|
||||
## Non-goals
|
||||
|
||||
* No Docker/Nix/devcontainer required
|
||||
* No GUI tooling
|
||||
* No distro-specific packaging beyond apt-style package lists
|
||||
* No Rust rewrite of scripts unless strictly necessary
|
||||
|
||||
---
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
* CI can install **only build deps** and run `shepherd build`
|
||||
* Runtime system can install **only run deps**
|
||||
* Developer can install **dev deps** and run `./run-dev`
|
||||
* Admin can:
|
||||
|
||||
* install binaries
|
||||
* deploy config
|
||||
* harden and unharden a user safely
|
||||
* No duplicated dependency lists
|
||||
* No duplicated build or sway logic
|
||||
Loading…
Reference in a new issue