Initial commit
This commit is contained in:
humocs-man
@@ -0,0 +1,240 @@
|
||||
# ujust - User-facing Just Commands
|
||||
|
||||
This directory contains Just recipe files that will be installed into your custom image and made available to end users via the `ujust` command.
|
||||
|
||||
## What is ujust?
|
||||
|
||||
`ujust` is a command that allows users to run predefined tasks on their system. It's built on top of [just](https://github.com/casey/just), a command runner similar to `make` but designed for commands rather than builds.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **During Build**: All `.just` files in this directory are consolidated and copied to `/usr/share/ublue-os/just/60-custom.just` in the image
|
||||
2. **After Installation**: Users run `ujust` to see available commands
|
||||
3. **User Experience**: Simple command interface for system tasks
|
||||
|
||||
## File Structure
|
||||
|
||||
Create `.just` files in this directory with your custom commands:
|
||||
|
||||
```
|
||||
custom/ujust/
|
||||
├── README.md # This file
|
||||
├── custom-apps.just # Application installation commands
|
||||
└── custom-system.just # System configuration commands
|
||||
```
|
||||
|
||||
**Example Files in this directory:**
|
||||
- [`custom-apps.just`](custom-apps.just) - Application installation commands (Brewfiles, Flatpaks, JetBrains Toolbox)
|
||||
- [`custom-system.just`](custom-system.just) - System configuration commands (benchmarks, dev groups, maintenance)
|
||||
|
||||
## Example Commands
|
||||
|
||||
### Basic Command
|
||||
```just
|
||||
# Run a system maintenance task
|
||||
run-maintenance:
|
||||
echo "Running maintenance..."
|
||||
sudo systemctl restart some-service
|
||||
```
|
||||
|
||||
### Interactive Command with gum
|
||||
```just
|
||||
# Configure system setting
|
||||
configure-thing:
|
||||
#!/usr/bin/bash
|
||||
source /usr/lib/ujust/ujust.sh
|
||||
echo "Configure thing?"
|
||||
OPTION=$(Choose "Enable" "Disable")
|
||||
if [[ "${OPTION,,}" =~ ^enable ]]; then
|
||||
echo "Enabling..."
|
||||
# your enable logic
|
||||
else
|
||||
echo "Disabling..."
|
||||
# your disable logic
|
||||
fi
|
||||
```
|
||||
|
||||
### Command with Group
|
||||
```just
|
||||
# Groups organize commands in ujust help
|
||||
[group('Apps')]
|
||||
install-brewfile:
|
||||
brew bundle --file /usr/share/ublue-os/homebrew/development.Brewfile
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Naming Conventions
|
||||
- Use lowercase with hyphens: `install-something`
|
||||
- Use verb prefixes for clarity:
|
||||
- `install-` - Install something
|
||||
- `configure-` - Configure something pre-installed
|
||||
- `setup-` - Install + configure
|
||||
- `toggle-` - Enable/disable a feature
|
||||
- `fix-` - Apply a fix or workaround
|
||||
|
||||
### Command Structure
|
||||
```just
|
||||
# Brief description of what the command does
|
||||
[group('Category')]
|
||||
command-name:
|
||||
#!/usr/bin/bash
|
||||
# Use bash shebang for multi-line scripts
|
||||
# Commands go here
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
```just
|
||||
install-something:
|
||||
#!/usr/bin/bash
|
||||
set -euo pipefail # Exit on error, undefined vars, pipe failures
|
||||
# Your commands
|
||||
```
|
||||
|
||||
### User Prompts
|
||||
Use `gum` for interactive prompts (included in Universal Blue images):
|
||||
```just
|
||||
interactive-command:
|
||||
#!/usr/bin/bash
|
||||
source /usr/lib/ujust/ujust.sh # Provides Choose() and other helpers
|
||||
OPTION=$(Choose "Option 1" "Option 2" "Cancel")
|
||||
echo "You chose: $OPTION"
|
||||
```
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Installing Software via Brewfiles
|
||||
```just
|
||||
[group('Apps')]
|
||||
install-dev-tools:
|
||||
brew bundle --file /usr/share/ublue-os/homebrew/development.Brewfile
|
||||
```
|
||||
|
||||
**See examples in [`custom-apps.just`](custom-apps.just)** for Brewfile shortcuts.
|
||||
|
||||
### 2. System Configuration
|
||||
```just
|
||||
[group('System')]
|
||||
configure-firewall:
|
||||
#!/usr/bin/bash
|
||||
sudo firewall-cmd --permanent --add-service=ssh
|
||||
sudo firewall-cmd --reload
|
||||
```
|
||||
|
||||
**See examples in [`custom-system.just`](custom-system.just)** for system configuration.
|
||||
|
||||
### 3. Development Environment Setup
|
||||
```just
|
||||
[group('Development')]
|
||||
setup-nodejs:
|
||||
#!/usr/bin/bash
|
||||
curl -fsSL https://fnm.vercel.app/install | bash
|
||||
source ~/.bashrc
|
||||
fnm install --lts
|
||||
```
|
||||
|
||||
### 4. Maintenance Tasks
|
||||
```just
|
||||
[group('Maintenance')]
|
||||
clean-containers:
|
||||
podman system prune -af
|
||||
podman volume prune -f
|
||||
```
|
||||
|
||||
**See examples in [`custom-system.just`](custom-system.just)** for maintenance tasks.
|
||||
|
||||
## Important: Package Installation
|
||||
|
||||
**Do not install packages via dnf5/rpm in ujust commands.** Bootc images are immutable and package installation should happen at build time in [`build/10-build.sh`](../../build/10-build.sh).
|
||||
|
||||
For runtime package installation, use:
|
||||
- **Brewfiles** - Create shortcuts to Brewfiles in [`custom/brew/`](../brew/)
|
||||
- **Flatpak** - Install Flatpaks for GUI applications
|
||||
- **Containers** - Use toolbox/distrobox for development environments
|
||||
|
||||
Example Brewfile shortcut (from [`custom-apps.just`](custom-apps.just)):
|
||||
```just
|
||||
[group('Apps')]
|
||||
install-fonts:
|
||||
brew bundle --file /usr/share/ublue-os/homebrew/fonts.Brewfile
|
||||
```
|
||||
|
||||
## Available Helpers
|
||||
|
||||
Universal Blue images include helpers in `/usr/lib/ujust/ujust.sh`:
|
||||
|
||||
- `Choose()` - Present multiple choice menu
|
||||
- `Confirm()` - Yes/no prompt
|
||||
- Color variables: `${bold}`, `${normal}`, etc.
|
||||
|
||||
## Testing Your Commands
|
||||
|
||||
Test locally before committing:
|
||||
|
||||
1. Build your image: `just build` (see [`Justfile`](../../Justfile))
|
||||
2. If on a bootc system: `sudo bootc switch --target localhost/finpilot:stable`
|
||||
3. Reboot and test: `ujust your-command`
|
||||
|
||||
Or test the just files directly:
|
||||
```bash
|
||||
just --justfile custom/ujust/custom-apps.just --list
|
||||
just --justfile custom/ujust/custom-apps.just install-something
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
**Start by editing the example files:**
|
||||
- **[`custom-apps.just`](custom-apps.just)** - Add your application installation commands
|
||||
- **[`custom-system.just`](custom-system.just)** - Add your system configuration commands
|
||||
|
||||
**Create new files** for different categories:
|
||||
- `custom-gaming.just` - Gaming-related commands
|
||||
- `custom-media.just` - Media editing workflows
|
||||
- `custom-dev.just` - Development environment setups
|
||||
|
||||
All `.just` files in this directory are automatically included. See [`build/10-build.sh`](../../build/10-build.sh) for the consolidation logic.
|
||||
|
||||
## Groups for Organization
|
||||
|
||||
Use groups to categorize commands:
|
||||
|
||||
```just
|
||||
[group('Apps')]
|
||||
install-app:
|
||||
echo "Installing app..."
|
||||
|
||||
[group('System')]
|
||||
configure-system:
|
||||
echo "Configuring system..."
|
||||
|
||||
[group('Development')]
|
||||
setup-dev:
|
||||
echo "Setting up dev environment..."
|
||||
```
|
||||
|
||||
## Examples from Bluefin
|
||||
|
||||
The included files provide starting examples:
|
||||
- **[`custom-apps.just`](custom-apps.just)** - Application installation commands
|
||||
- **[`custom-system.just`](custom-system.just)** - System configuration commands
|
||||
|
||||
These files show how to:
|
||||
- Create shortcuts to Brewfiles in [`custom/brew/`](../brew/)
|
||||
- Install Flatpaks interactively
|
||||
- Configure system settings
|
||||
- Run maintenance tasks
|
||||
|
||||
## Resources
|
||||
|
||||
- [Just Manual](https://just.systems/man/en/)
|
||||
- [Universal Blue Just Documentation](https://universal-blue.org/guide/just/)
|
||||
- [Bluefin ujust Commands](https://docs.projectbluefin.io/administration)
|
||||
- [gum Documentation](https://github.com/charmbracelet/gum)
|
||||
|
||||
## Notes
|
||||
|
||||
- Commands run with user privileges by default
|
||||
- Use `sudo` or `pkexec` when root access needed
|
||||
- Consider providing both install and uninstall options
|
||||
- Test on a clean system before distributing
|
||||
- Document any prerequisites or dependencies
|
||||
@@ -0,0 +1,80 @@
|
||||
# vim: set ft=make :
|
||||
####################
|
||||
### custom-apps.just
|
||||
####################
|
||||
## Example application installation commands
|
||||
## These are simplified examples adapted from Bluefin
|
||||
|
||||
# Install default applications via Homebrew
|
||||
[group('Apps')]
|
||||
install-default-apps:
|
||||
#!/usr/bin/env bash
|
||||
echo "Installing default applications via Homebrew..."
|
||||
brew bundle --file /usr/share/ublue-os/homebrew/default.Brewfile
|
||||
|
||||
# Install development tools via Homebrew
|
||||
[group('Apps')]
|
||||
install-dev-tools:
|
||||
#!/usr/bin/env bash
|
||||
echo "Installing development tools via Homebrew..."
|
||||
brew bundle --file /usr/share/ublue-os/homebrew/development.Brewfile
|
||||
|
||||
# Install fonts via Homebrew
|
||||
[group('Apps')]
|
||||
install-fonts:
|
||||
#!/usr/bin/env bash
|
||||
echo "Installing fonts via Homebrew..."
|
||||
brew bundle --file /usr/share/ublue-os/homebrew/fonts.Brewfile
|
||||
|
||||
# Install all Brewfiles at once
|
||||
[group('Apps')]
|
||||
install-all-brew:
|
||||
#!/usr/bin/env bash
|
||||
echo "Installing all applications from Brewfiles..."
|
||||
brew bundle --file /usr/share/ublue-os/homebrew/default.Brewfile
|
||||
brew bundle --file /usr/share/ublue-os/homebrew/development.Brewfile
|
||||
brew bundle --file /usr/share/ublue-os/homebrew/fonts.Brewfile
|
||||
|
||||
# Install JetBrains Toolbox for managing JetBrains IDEs
|
||||
[group('Apps')]
|
||||
install-jetbrains-toolbox:
|
||||
#!/usr/bin/env bash
|
||||
echo "Installing JetBrains Toolbox..."
|
||||
pushd "$(mktemp -d)"
|
||||
echo "Fetching latest version..."
|
||||
curl -sSfL -o releases.json "https://data.services.jetbrains.com/products/releases?code=TBA&latest=true&type=release"
|
||||
BUILD_VERSION=$(jq -r '.TBA[0].build' ./releases.json)
|
||||
DOWNLOAD_LINK=$(jq -r '.TBA[0].downloads.linux.link' ./releases.json)
|
||||
CHECKSUM_LINK=$(jq -r '.TBA[0].downloads.linux.checksumLink' ./releases.json)
|
||||
echo "Installing JetBrains Toolbox ${BUILD_VERSION}"
|
||||
curl -sSfL -O "${DOWNLOAD_LINK}"
|
||||
curl -sSfL "${CHECKSUM_LINK}" | sha256sum -c
|
||||
tar zxf jetbrains-toolbox-"${BUILD_VERSION}".tar.gz
|
||||
mkdir -p $HOME/.local/share/JetBrains/ToolboxApp/
|
||||
mv jetbrains-toolbox-"${BUILD_VERSION}"/* $HOME/.local/share/JetBrains/ToolboxApp/
|
||||
popd
|
||||
echo "Launching JetBrains Toolbox..."
|
||||
$HOME/.local/share/JetBrains/ToolboxApp/bin/jetbrains-toolbox
|
||||
|
||||
# Shortcut for install-jetbrains-toolbox
|
||||
[group('Apps')]
|
||||
jetbrains-toolbox:
|
||||
@ujust install-jetbrains-toolbox
|
||||
|
||||
# Install a Flatpak application from Flathub
|
||||
[group('Apps')]
|
||||
install-flatpak APP_ID:
|
||||
#!/usr/bin/bash
|
||||
echo "Installing {{ APP_ID }} from Flathub..."
|
||||
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
|
||||
flatpak install -y flathub {{ APP_ID }}
|
||||
|
||||
# Example: Install VSCode via Flatpak
|
||||
[group('Apps')]
|
||||
install-vscode:
|
||||
ujust install-flatpak com.visualstudio.code
|
||||
|
||||
# Example: Install GIMP via Flatpak
|
||||
[group('Apps')]
|
||||
install-gimp:
|
||||
ujust install-flatpak org.gimp.GIMP
|
||||
@@ -0,0 +1,92 @@
|
||||
# vim: set ft=make :
|
||||
#######################
|
||||
### custom-system.just
|
||||
#######################
|
||||
## Example system configuration commands
|
||||
## These are simplified examples adapted from Bluefin
|
||||
|
||||
# Run a system benchmark (requires stress-ng from Homebrew)
|
||||
[group('System')]
|
||||
benchmark:
|
||||
#!/usr/bin/env bash
|
||||
source /usr/lib/ujust/ujust.sh
|
||||
if ! type -P "stress-ng" &>/dev/null ; then
|
||||
echo "stress-ng is not installed."
|
||||
if command -v brew &>/dev/null; then
|
||||
if gum confirm "Install stress-ng via Homebrew?" ; then
|
||||
brew install stress-ng
|
||||
brew link stress-ng
|
||||
else
|
||||
exit 0
|
||||
fi
|
||||
else
|
||||
echo "Please install stress-ng to run benchmarks."
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
echo 'Running a 1 minute benchmark...'
|
||||
pushd $(mktemp -d) > /dev/null
|
||||
stress-ng --matrix 0 -t 1m --times
|
||||
popd > /dev/null
|
||||
|
||||
# Configure docker and libvirt groups for development
|
||||
[group('System')]
|
||||
configure-dev-groups:
|
||||
#!/usr/bin/pkexec bash
|
||||
CURRENT_USER="{{ `id -un` }}"
|
||||
echo "Adding $CURRENT_USER to docker and libvirt groups..."
|
||||
|
||||
# Ensure groups exist in /etc/group
|
||||
for group in docker libvirt; do
|
||||
if ! grep -q "^$group:" /etc/group; then
|
||||
echo "Adding $group to /etc/group"
|
||||
grep "^$group:" /usr/lib/group | tee -a /etc/group > /dev/null
|
||||
fi
|
||||
usermod -aG $group $CURRENT_USER
|
||||
done
|
||||
|
||||
echo "Groups configured. Log out and back in for changes to take effect."
|
||||
|
||||
# Example toggle command with user choice
|
||||
[group('System')]
|
||||
toggle-example-feature:
|
||||
#!/usr/bin/bash
|
||||
source /usr/lib/ujust/ujust.sh
|
||||
echo "This is an example toggle command."
|
||||
echo "Current status: [check your status here]"
|
||||
OPTION=$(Choose "Enable" "Disable" "Cancel")
|
||||
case "$OPTION" in
|
||||
"Enable")
|
||||
echo "Enabling feature..."
|
||||
# Add your enable logic here
|
||||
;;
|
||||
"Disable")
|
||||
echo "Disabling feature..."
|
||||
# Add your disable logic here
|
||||
;;
|
||||
"Cancel")
|
||||
echo "No changes made."
|
||||
;;
|
||||
esac
|
||||
|
||||
# Clean up container images and volumes
|
||||
[group('Maintenance')]
|
||||
clean-containers:
|
||||
#!/usr/bin/bash
|
||||
echo "Cleaning up Podman containers, images, and volumes..."
|
||||
podman system prune -af
|
||||
podman volume prune -f
|
||||
echo "Cleanup complete!"
|
||||
|
||||
# Update system and reboot if needed
|
||||
[group('Maintenance')]
|
||||
update-and-reboot:
|
||||
#!/usr/bin/bash
|
||||
source /usr/lib/ujust/ujust.sh
|
||||
echo "Updating system..."
|
||||
sudo bootc upgrade
|
||||
if gum confirm "Reboot now to apply updates?"; then
|
||||
systemctl reboot
|
||||
else
|
||||
echo "Reboot later to apply updates."
|
||||
fi
|
||||
Reference in New Issue
Block a user