Skip to content

SETUP.md

Latest commit

 

History

History
243 lines (180 loc) · 5.57 KB

SETUP.md

File metadata and controls

243 lines (180 loc) · 5.57 KB
Raw

Setup Guide

Complete installation and configuration guide for Server Scripts CLI.

Prerequisites

Required

  • Bash 4.0+: Check version with bash --version
  • yq v4+: YAML processor by mikefarah

Optional

  • systemd: For service status and log querying
  • Git: For automatic repository root detection

Installing yq

Snap (Recommended):

sudo snap install yq

Binary Download:

VERSION=v4.40.5
BINARY=yq_linux_amd64
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O yq
chmod +x yq
sudo mv yq /usr/local/bin/

Verify:

yq --version
# Expected: yq (https://github.com/mikefarah/yq/) version v4.40.5

Installation Methods

Method 1: Local Repository (Recommended)

# Clone repository
git clone https://github.com/fidpa/server-scripts-cli
cd server-scripts-cli

# Make scripts executable
chmod +x ssc.sh generate-manifest.sh

# Create alias in ~/.bashrc
echo "alias ssc='$(pwd)/ssc.sh'" >> ~/.bashrc
source ~/.bashrc

# Test
ssc --version

Method 2: System-Wide Installation

# Install to /usr/local/bin
sudo cp ssc.sh /usr/local/bin/ssc
sudo cp generate-manifest.sh /usr/local/bin/
sudo chmod +x /usr/local/bin/{ssc,generate-manifest.sh}

# Test
ssc --version

Method 3: User-Local Symlink

# Create ~/.local/bin if it doesn't exist
mkdir -p ~/.local/bin

# Symlink
ln -s $(pwd)/ssc.sh ~/.local/bin/ssc

# Ensure ~/.local/bin is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Test
ssc --version

Repository Structure

Your repository should follow this structure:

your-repo/
├── scripts/
│   ├── operations/
│   │   └── backup.sh         # Your scripts here
│   ├── monitoring/
│   │   └── health-check.sh
│   └── setup/
│       └── install.sh
├── ssc.sh                      # CLI tool
├── generate-manifest.sh        # Manifest generator
└── manifest.yaml               # Auto-generated (DO NOT EDIT)

Generating Your First Manifest

  1. Add YAML front-matter to your scripts:
#!/bin/bash
# ---
# deployment: manual
# service: none
# status: active
# type: cli-tool
# requires_root: false
# ---
#
# Your script content
  1. Run generator:
./generate-manifest.sh
  1. Verify:
ssc list
ssc validate

Configuration

ssc runs without configuration. Seven environment variables change its behaviour, all optional, all with a default that matches what ssc does when you set nothing:

Variable Default Effect
SSC_MANIFEST_FILE manifest.yaml in the repository root Read the manifest from somewhere else
SSC_REPO_ROOT git rev-parse --show-toplevel, else the directory of ssc.sh Resolve script paths against this directory
SSC_LOG_LEVEL info debug, info, warning or error; filters the status messages of ssc itself
SSC_COLOR auto auto colors when stdout is a terminal, always and never decide for it
SSC_SYSTEMD_ENABLED true false makes ssc status and ssc logs return without calling systemctl or journalctl
SSC_EXEC_TIMEOUT 0 Seconds after which ssc run kills the script, via timeout; 0 disables it
SSC_STRICT_VALIDATION false true makes ssc validate check every field against MANIFEST_SCHEMA.md

The tables that list, info and status print are data, not messages: SSC_LOG_LEVEL=error silences the commentary around them and leaves the table itself alone, which is what you want in a pipe. debug goes the other way and prints the resolved repository root, the resolved manifest and the exact command behind ssc run to stderr.

Configuration File

export SSC_LOG_LEVEL="debug"
export SSC_COLOR="never"

works for a single shell. For something permanent, copy the template:

mkdir -p ~/.config/ssc
cp config/ssc.env.example ~/.config/ssc/ssc.env
chmod 600 ~/.config/ssc/ssc.env

ssc sources ~/.config/ssc/ssc.env itself at startup, so there is nothing to add to ~/.bashrc. A variable already set in your environment wins over the file. Sourcing a file executes it, so ssc skips the file and says so when it is not owned by you or when group or others can write it; that is what the chmod 600 above is for.

systemd Integration (Optional)

Service Status Queries

If your scripts have associated systemd services, use:

# Show all service statuses
ssc status

# Show specific service
ssc status -s backup-example

# Include logs
ssc status -s backup-example -l -n 50

Timer Overview

# Show systemd timer schedule
ssc status --timers

Log Queries

# Show logs for script's service
ssc logs backup-example

# With options (passed to journalctl)
ssc logs backup-example -n 100 --since "1 hour ago"

Updating Scripts

  1. Edit your scripts (add/modify YAML front-matter)
  2. Regenerate manifest: 
    ./generate-manifest.sh
  3. Validate: 
    ssc validate

Tab Completion (Optional)

Bash completion support:

# Install completion (if available in repo)
sudo cp completions/ssc.bash /etc/bash_completion.d/
source /etc/bash_completion.d/ssc.bash

Troubleshooting

See TROUBLESHOOTING.md for common issues.

Next Steps