albert/shepherd-launcher
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update documentation to reflect setup scripts

Browse source
This commit is contained in:
Albert Armea 2026-01-01 13:50:48 -05:00
parent fc0c1ce51d
commit 9c14fe5ccd
4 changed files with 342 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
CONTRIBUTING.md
View file

@ -4,7 +4,8 @@
### tl;dr ### 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 ### Requirements
@ -15,15 +16,41 @@ You need a Wayland-capable Linux system, Rust, and a small set of system depende
2. **System dependencies** 2. **System dependencies**
* Platform-specific packages are required. * Platform-specific packages are required for building and running.
* For Ubuntu, see the [`SYSTEM_DEPS` section in the CI configuration](./.github/workflows/ci.yml). * 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
`shepherd-launcher` provides a unified script system for managing dependencies, building, and running:
```sh ```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | 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 ### Running in development
Start a development instance: Start a development instance:

49
README.md
View file

@ -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 > [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 ## Core concepts
* **Launcher-first**: only one foreground activity at a time * **Launcher-first**: only one foreground activity at a time
@ -113,16 +90,12 @@ such as:
## Installation ## Installation
`shepherd-launcher` is pre-alpha and in active development. As such, end-user `shepherd-launcher` is pre-alpha and in active development. The helper at
binaries and installation instructions are not yet available. `./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. Check out this repository and run `./scripts/shepherd --help` or see
[INSTALL.md](./docs/INSTALL.md) for more.
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))
## Example configuration ## 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 daily_quota_seconds = 3600 # 1 hour per day
cooldown_seconds = 600 # 10 minute cooldown cooldown_seconds = 600 # 10 minute cooldown
[[entries.warnings]]
seconds_before = 600
severity = "info"
message = "10 minutes left - start wrapping up!"
[[entries.warnings]] [[entries.warnings]]
seconds_before = 120 seconds_before = 120
severity = "warn" severity = "warn"
@ -178,7 +146,12 @@ See [config.example.toml](./config.example.toml) for more.
## Development ## 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 ## Written in 2025, responsibly

66
docs/INSTALL.md Normal file
View 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
View 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