Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

README.md

shimkit documentation

The repo root has the short version. This directory has the long version.

Getting started

  • Installation — uv, pipx, pip, Homebrew, the curl one-liner, and how shimkit self-update works.
  • Configuration — the JSON config layer, where files live, override precedence, the schema.

Tools

shimkit is a collection. Each tool gets its own page:

  • shimkit java — OpenJDK version manager. Install / list / switch / upgrade / uninstall / remove-oracle.
  • shimkit shell — Cross-PM shell upgrader for bash / zsh / fish / ksh.
  • shimkit dns — macOS DNS resolver recovery. Diagnose, flush, fix (6-step escalation), test, rollback.
  • shimkit adguard — AdGuard Home port-conflict fixer (Linux). API-first, ruamel.yaml fallback.
  • shimkit docker-clean — Docker resource cleanup (Linux + macOS + WSL). docker-py SDK + buildx-aware prune.
  • shimkit ports — TCP/UDP port owner lookup + kill. lsof on macOS, ss on Linux.
  • shimkit hosts — /etc/hosts editor with atomic write + timestamped backups.
  • shimkit ssh — SSH key + agent + known_hosts
    • perms hygiene.
  • shimkit env — .env viewer + scaffolder with default-deny secret redaction.
  • shimkit gpg — GPG key + git-signing hygiene.
  • shimkit logs — System log tail / grep (macOS log show, Linux journalctl). Read-only.
  • shimkit cron — User-crontab editor. Atomic write + backup-on-mutate; only touches shimkit-marker-tagged entries.

Server-class tools (Docker-first; opt-in to host install)

  • shimkit db — Container-first databases (mysql/mariadb/postgres/mongo/phpmyadmin). --on-host mode for mysql/mariadb/postgres manages existing host installs.
  • shimkit stack lemp — Three-container LEMP recipe (db + php-fpm + nginx). Bind-mounts $cwd at /srv/app.
  • shimkit web nginx vhost — Hardened nginx vhost generator. File-only by default; apply and remove are SEVERE-tier.
  • shimkit tls — TLS cert lifecycle via container-first certbot. request / list / status / renew / revoke (SEVERE) / cron-install.

Framework recipes

  • shimkit framework laravel — Laravel helpers: perms, .env scaffold, scheduler cron-install, artisan passthrough (host or LEMP container).
  • shimkit framework symfony — Symfony helpers: perms (var/), .env.local scaffold with APP_SECRET, cache-clear, bin/console passthrough.
  • shimkit framework django — Django helpers: perms (media/ + staticfiles/), .env scaffold with SECRET_KEY + django-environ-style DATABASE_URL, migrate, manage.py passthrough.

Top-level utilities (not tools):

  • shimkit config — inspect, edit, validate user configuration. Documented in Configuration.
  • shimkit doctor — system diagnostics for bug reports. No dedicated page; run it and the output is self-documenting.
  • shimkit self-update — keep shimkit current. Documented in Installation.

Development

  • Architecture — how the core/tools split works, the load-bearing rules, how to add a new tool.
  • Onboarding — practical walkthrough for getting productive: setup, the 5 rules with grep recipes, the canonical recipe for adding a new tool, common dev tasks, debugging guide.
  • Release process — cutting a new version, the CI pipeline, what each release job does.
  • Shipping checklist — every step from "code ready" to "users can install", in dependency order. Tracks what's done vs what still needs your action.
  • Validation scope — what's in scope for automated + manual gates, what's deliberately out of scope, and how to expand the envelope.
  • Known issues + pending items — checks that exist in our scope but can't be automated (and why), coverage deferrals, and aspirational follow-ups without owners.
  • Future additions — naturally- extensible surface (more TLS DNS-01 providers, more framework recipes, more db engines) with concrete patterns but no current user demand. Move items out when someone asks.
  • Shipping audit (2026-05-16) — comprehensive shipped-vs-pending walk through every plan, design spec, and doc. Captures the two user-side actions still outstanding (PyPI trusted-publisher + branch protection), documents permanent skips, and cross-references everything else.

Release notes

Per-version, user-facing summaries (newest first):

  • v0.19.0 — plans-tree audit. Two new plans docs: future-additions.md (no-demand items) + shipping-audit.md (comprehensive shipped-vs-pending walk).
  • v0.18.0 — doc-sync pass. README + architecture + onboarding + cron tool doc + JSON schema brought current with v0.17.0 reality.
  • v0.17.0 — shimkit tls --method dns-route53 for AWS Route53 DNS-01.
  • v0.16.0 — shimkit framework django third framework recipe.
  • v0.15.0 — shimkit db redis sixth engine. Engine.up_command() for argv-passed config.
  • v0.14.0 — shimkit framework symfony sibling recipe under the framework parent.
  • v0.13.0 — shimkit tls --method dns-cloudflare for DNS-01 + wildcard certs.
  • v0.12.0 — stale-doc cleanup + codecov upload + gh attestation verify smoke. No code changes.
  • v0.11.0 — docs consolidation + PyPI workflow restored. No code changes.
  • v0.10.0 — coverage push 74% → 85% (+397 tests). No code changes.
  • v0.9.0 — shimkit db --on-host for mysql/mariadb/postgres. Manages existing host installs; refuses to install packages (the audit-completion bit).
  • v0.8.0 — shimkit tls (certbot container-first cert lifecycle). State at ~/.shimkit/data/tls/; webroot ACME; daily renewal cron.
  • v0.7.1 — version-drift recovery for v0.7.0.
  • v0.7.0 — shimkit framework laravel (perms / env / cron-install / artisan). First framework recipe under the new framework parent.
  • v0.6.0 — shimkit cron (generic user-crontab editor). Atomic write + backup-on-mutate.
  • v0.5.0 — ubuntu/ migration: three new sub-trees (db/stack/web), two new core primitives (core/docker, core/version), 152 new tests. Five Critical audit flags dissolved by Docker-first design.
  • v0.2.0 — three new tools (dns, adguard, docker-clean); uniform CLI surface across all new subcommands; argv-list PM templates; container hardening + SBOM
    • attestation.

External references:

For shimkit-specific release operations, see release.md. For the wider org-level reference on publishing to PyPI / npm / Docker registries, ask the team — that guide lives outside this repo.