installer

Documentation

Overview

Package installer provides automated installation of Ollama and related local-LLM infrastructure for nSelf Block A (Zero-Config AI).

Index

• Constants
• Variables
• func DownloadAndVerify(ctx context.Context, url, expectedSHA string) (string, error)
• func ExpectedOllamaInstallChecksum() string
• func MemAvailableMB() (int, error)
• func RecommendForHost() (TierKey, []ModelRec)
• type InstallOptions
• type InstallResult
  • func Install(ctx context.Context, opts InstallOptions) (*InstallResult, error)
  • func ReadLocalState() (*InstallResult, error)
• type InstallerError
  • func (e *InstallerError) Error() string
• type ModelRec
• type TierKey
  • func TierForRAM(mb int) TierKey

Constants

const (
	ErrOllamaInstallFailed  = "OLLAMA_INSTALL_FAILED"
	ErrSystemdUnavailable   = "SYSTEMD_UNAVAILABLE"
	ErrIptablesNoPermission = "IPTABLES_NO_PERMISSION"
	ErrPortBindConflict     = "PORT_BIND_CONFLICT"
	ErrRAMInsufficient      = "RAM_INSUFFICIENT"
	ErrUnsupportedOS        = "UNSUPPORTED_OS"
)

Error codes (per spec §3.2.1).

const DefaultChecksumVersion = "1.0.3"

DefaultChecksumVersion is the CLI version whose pinned checksum we use.

const LocalStateFile = ".nself/ai/local-state.json"

LocalStateFile is where the installer records its run.

Variables

var PinnedOllamaInstallSHA256 = map[string]string{

	"1.0.3": "25f64b810b947145095956533e1bdf56eacea2673c55a7e586be4515fc882c9f",
}

PinnedOllamaInstallSHA256 is the SHA256 checksum of the official https://ollama.com/install.sh script, pinned to the version validated for nSelf CLI v1.0.3 LTS. When Ollama ships a new installer, update this table and the DefaultChecksumVersion constant.

The checksum is verified after download in OllamaInstaller.Install() before the script is executed. If it does not match, installation aborts with OLLAMA_INSTALL_FAILED.

var RecommendationMatrix = map[string]map[TierKey][]ModelRec{
	"1.0.3": {
		TierNone: {},
		TierTiny: {
			{Name: "gemma2:2b", Tasks: []string{"chat", "classify"}},
			{Name: "nomic-embed-text", Tasks: []string{"embed"}},
		},
		TierSmall: {
			{Name: "phi3:mini", Tasks: []string{"chat", "classify"}},
			{Name: "nomic-embed-text", Tasks: []string{"embed"}},
		},
		TierBalanced: {
			{Name: "qwen2.5:3b", Tasks: []string{"chat"}},
			{Name: "nomic-embed-text", Tasks: []string{"embed"}},
			{Name: "gemma2:2b", Tasks: []string{"classify"}},
		},
		TierMedium: {
			{Name: "llama3.2:3b", Tasks: []string{"chat"}},
			{Name: "nomic-embed-text", Tasks: []string{"embed"}},
			{Name: "gemma2:2b", Tasks: []string{"classify"}},
		},
		TierLarge: {
			{Name: "qwen2.5:7b", Tasks: []string{"chat"}},
			{Name: "nomic-embed-text", Tasks: []string{"embed"}},
			{Name: "gemma2:2b", Tasks: []string{"classify"}},
		},
		TierXL: {
			{Name: "llama3.1:8b", Tasks: []string{"chat"}},
			{Name: "bge-large", Tasks: []string{"embed"}},
			{Name: "gemma2:2b", Tasks: []string{"classify"}},
		},
		TierXXL: {
			{Name: "qwen2.5:14b", Tasks: []string{"chat"}},
			{Name: "bge-large", Tasks: []string{"embed"}},
			{Name: "gemma2:2b", Tasks: []string{"classify"}},
		},
	},
}

RecommendationMatrix is keyed by nSelf CLI version. Only the current version entry is authoritative at runtime; older entries are kept for historical reproducibility.

Functions

func DownloadAndVerify

func DownloadAndVerify(ctx context.Context, url, expectedSHA string) (string, error)

DownloadAndVerify downloads the resource at url into a private temporary directory (0700 owner-only permissions), computes the SHA-256 of the downloaded content, and compares it against expectedSHA.

On success it returns the path to the verified script file inside the temporary directory. The caller is responsible for removing the entire directory with os.RemoveAll when done — the returned path's parent is the directory to remove.

Using an owner-only 0700 parent directory (instead of the shared system $TMPDIR) closes the TOCTOU window between file close and script execution: a same-uid process cannot replace the file at the returned path because the containing directory is not world-writable.

Verification is unconditional: expectedSHA must be a non-empty hex string. Pass the value from ExpectedOllamaInstallChecksum().

Body reads are capped at 2 MiB via io.LimitReader. A body that exceeds this cap produces a checksum mismatch (the truncated bytes do not match the full-file hash) and DownloadAndVerify returns an error. See Supply-Chain.md for documentation of this behaviour.

func ExpectedOllamaInstallChecksum

func ExpectedOllamaInstallChecksum() string

ExpectedOllamaInstallChecksum returns the pinned SHA256 for the current CLI version. The returned value is always non-empty; verification is mandatory.

func MemAvailableMB

func MemAvailableMB() (int, error)

MemAvailableMB reads /proc/meminfo on Linux and returns the MemAvailable value in MB. Returns 0 and an error on non-Linux or read failure.

func RecommendForHost

func RecommendForHost() (TierKey, []ModelRec)

RecommendForHost returns the recommended model list for the current host. If MemAvailable cannot be read, returns TierNone recommendations.

Types

type InstallOptions

type InstallOptions struct {
	SkipModels bool
	Model      string // optional single model to pull (overrides matrix)
	Bind       string // host:port, default 0.0.0.0:11434
	Yes        bool   // non-interactive
	JSON       bool
	LogFn      func(level, msg string, kv map[string]any)
}

InstallOptions controls the installer flow.

type InstallResult

type InstallResult struct {
	AlreadyInstalled bool      `json:"already_installed"`
	OllamaVersion    string    `json:"ollama_version,omitempty"`
	Bind             string    `json:"bind"`
	Tier             TierKey   `json:"ram_tier"`
	ModelsPulled     []string  `json:"models_pulled"`
	CompletedAt      time.Time `json:"completed_at"`
}

InstallResult summarises an install run.

func Install

func Install(ctx context.Context, opts InstallOptions) (*InstallResult, error)

Install performs the full install flow. Returns an *InstallerError on failure.

func ReadLocalState

func ReadLocalState() (*InstallResult, error)

ReadLocalState returns the persisted install state if present.

type InstallerError

type InstallerError struct {
	Code string
	Msg  string
	Err  error
}

InstallerError wraps a coded installer error.

func (*InstallerError) Error

func (e *InstallerError) Error() string

type ModelRec

type ModelRec struct {
	Name  string   // ollama model tag, e.g. "gemma2:2b"
	Tasks []string // chat, embed, classify
}

ModelRec is a single recommendation entry.

type TierKey

type TierKey string

TierKey identifies a RAM tier.

const (
	TierNone     TierKey = "none"     // <4 GB
	TierTiny     TierKey = "tiny"     // 4-6 GB
	TierSmall    TierKey = "small"    // 6-8 GB
	TierBalanced TierKey = "balanced" // 8-12 GB
	TierMedium   TierKey = "medium"   // 12-16 GB
	TierLarge    TierKey = "large"    // 16-24 GB
	TierXL       TierKey = "xl"       // 24-32 GB
	TierXXL      TierKey = "xxl"      // >32 GB
)

func TierForRAM

func TierForRAM(mb int) TierKey

TierForRAM returns the TierKey for a given MB.