infocyph/tools repository overview

⁠🛠️ Docker Tools Container

A lightweight, multi-tool Docker image for:

• ✅ SSL automation (mkcert + certify)
• ✅ Interactive vhost generation (mkhost) + templates
• ✅ Cleanup vhosts (delhost)
• ✅ SOPS/Age encrypted env workflow (senv)
• ✅ Host notifications pipeline (notifierd + notify + host docknotify)
• ✅ Docker ops + TUI (docker-cli + compose + lazydocker)
• ✅ Network diagnostics (netx, dig, mtr, traceroute, nmap, etc.)
• ✅ Daily dev/ops utilities (git, jq, yq, rg, fd, sqlite, shellcheck, nano, etc.)

⁠🚀 Features (what’s included)

⁠1) SSL + local CA automation

• mkcert bundled
• certify scans vhosts under /etc/share/vhosts/** and generates:
  • Apache server/client certs
  • Nginx server/proxy/client certs (includes .p12 for Nginx client)
• Wildcards are auto-added from filenames (example.com.conf → example.com + *.example.com)
• Always includes: localhost, 127.0.0.1, ::1
• Stable CA root via CAROOT=/etc/share/rootCA

⁠2) Interactive vhost generator + templates

• mkhost generates Nginx/Apache vhost configs using predefined templates
• Uses runtime-versions DB baked during build:
  • /etc/share/runtime-versions.json (override via RUNTIME_VERSIONS_DB)
• Supports helper flags to query/reset internal “active” selections (ACTIVE_PHP_PROFILE, ACTIVE_NODE_PROFILE, APACHE_ACTIVE)

⁠3) SOPS/Age encrypted env workflow

• age + sops installed
• senv provides a clean workflow around .env ↔ .env.enc
• Supports:
  • repo-local config ./.sops.yaml (highest priority)
  • global fallback config/key under /etc/share/sops (mountable)
  • multi-project keys (per-repo) + “shared encrypted env repo” input mount

⁠4) Host notifications pipeline

• notifierd listens on TCP (default 9901) and emits a stable single-line event to stdout using a prefix (default __HOST_NOTIFY__)
• notify sends events into notifierd (inside container)
• Host can watch formatted events and show popups
• Optional host-side sender docknotify can push events to the container from the host

⁠5) Docker debugging + TUI

• docker-cli + compose
• lazydocker bundled (mount the docker socket)

⁠6) Network & diagnostics toolbox

• netx (Toolset wrapper)
• curl, wget, ping, nc
• dig/nslookup (bind-tools)
• iproute2, traceroute, mtr
• nmap

⁠7) Daily dev/ops utilities

• git + gitx (Toolset)
• jq, yq
• ripgrep (rg), fd
• sqlite + sqlitex (Toolset)
• shellcheck
• zip, unzip, tree, ncdu
• Default editor UX:
  • nano is default EDITOR and VISUAL
  • /etc/nanorc is configured to load syntax rules when available
• chromacat, figlet, show-banner shell hook

⁠🧰 Included commands

⁠📂 Directory layout (recommended)

This repo is designed so you can keep all generated + persistent artifacts in a single configuration/ folder, and mount them into the container.

⁠✅ Suggested structure

.
├─ configuration/
│  ├─ apache/               # Generated/managed Apache vhosts (*.conf)
│  ├─ nginx/                # Generated/managed Nginx vhosts (*.conf)
│  ├─ ssl/                  # Generated certificates (.pem, .p12, keys)
│  ├─ rootCA/               # mkcert CA store (persist across rebuilds)
│  └─ sops/                 # Global SOPS Model B (persisted)
│     ├─ age.keys           # Global Age key (fallback)
│     ├─ .sops.yaml         # Global fallback config (created by senv init if writable)
│     ├─ keys/              # Per-project keys
│     │  ├─ projectA.age.keys
│     │  └─ projectB.age.keys
│     └─ config/            # Optional per-project configs
│        ├─ projectA.sops.yaml
│        └─ projectB.sops.yaml
│
├─ secrets-repo/            # Optional shared encrypted env store (usually RO mount)
│  ├─ projectA/
│  │  └─ .env.enc
│  └─ projectB/
│     └─ prod/.env.enc
│
└─ docker-compose.yml

⁠🔗 Container mount mapping

⁠📦 Docker Compose example

services:
  tools:
    image: infocyph/tools:latest
    container_name: docker-tools
    volumes:
      - ./configuration/apache:/etc/share/vhosts/apache
      - ./configuration/nginx:/etc/share/vhosts/nginx

      - ./configuration/ssl:/etc/mkcert
      - ./configuration/rootCA:/etc/share/rootCA

      - ./configuration/sops:/etc/share/sops
      - ./secrets-repo:/etc/share/vhosts/sops:ro

      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=Asia/Dhaka
      # - NOTIFY_TCP_PORT=9901
      # - NOTIFY_PREFIX=__HOST_NOTIFY__
      # - NOTIFY_TOKEN=

Use as:

• one-shot cert generator: docker run --rm ... infocyph/tools certify
• long-lived utility box: default CMD runs notifierd

⁠▶️ Manual run

docker run --rm -it \
  -v "$(pwd)/configuration/apache:/etc/share/vhosts/apache" \
  -v "$(pwd)/configuration/nginx:/etc/share/vhosts/nginx" \
  -v "$(pwd)/configuration/ssl:/etc/mkcert" \
  -v "$(pwd)/configuration/rootCA:/etc/share/rootCA" \
  -v "$(pwd)/configuration/sops:/etc/share/sops" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  infocyph/tools:latest

⁠🔧 Certificate automation (certify)

On container startup, the entrypoint runs certify (best-effort). It:

1. Scans all *.conf under /etc/share/vhosts/**
2. Extracts domains from filenames (basename without .conf)
3. Adds wildcard variants automatically (*.domain)
4. Always includes: localhost, 127.0.0.1, ::1
5. Generates server and client certificates using mkcert

⁠📁 Domain detection by filename

⁠🔐 Generated cert files

All certs are written to /etc/mkcert.

⁠🧩 mkhost (interactive vhost generator)

mkhost is your “domain setup wizard”. It generates:

• Nginx vhost: /etc/share/vhosts/nginx/<domain>.conf
• Apache vhost (only if you choose Apache): /etc/share/vhosts/apache/<domain>.conf
• Node service yaml (only if you choose Node): /etc/share/vhosts/node/<token>.yaml

Run it:

docker exec -it docker-tools mkhost

⁠What it asks (flow)

It runs a guided 9-step flow (slightly different for PHP vs Node):

• Domain name (validated)

• App type: PHP or Node

• Server type (PHP only): Nginx or Apache

  • Node always uses Nginx proxy mode

• HTTP / HTTPS mode (keep HTTP, redirect, or HTTPS)

• Document root (/app/<path>)

• Client body size

• Runtime version selection:

  • PHP: choose PHP version/profile
  • Node: choose Node version + optional run command

• If HTTPS: optional client certificate verification (mutual TLS)

⁠HTTPS + certificates

If you enable HTTPS, mkhost triggers certify automatically so the required certs exist.

⁠Helpful flags (used by devtainer)

mkhost stores the “active selections” into env (used by your server wrapper to enable compose profiles). You can query/reset these values:

mkhost --RESET
mkhost --ACTIVE_PHP_PROFILE
mkhost --ACTIVE_NODE_PROFILE
mkhost --APACHE_ACTIVE

• --RESET clears all active selections.
• --ACTIVE_PHP_PROFILE prints the chosen PHP profile (if PHP was selected).
• --ACTIVE_NODE_PROFILE prints the chosen Node profile (if Node was selected).
• --APACHE_ACTIVE prints apache when Apache mode was selected.

⁠🧹 delhost (remove vhost configs)

delhost deletes the generated files for a domain:

• /etc/share/vhosts/nginx/<domain>.conf
• /etc/share/vhosts/apache/<domain>.conf
• /etc/share/vhosts/node/<token>.yaml (token is a safe slug of the domain)

Run it:

docker exec -it docker-tools delhost example.com

Interactive mode (no args):

docker exec -it docker-tools delhost

Behavior:

• Validates the domain format before deleting
• Shows exactly what files it will remove
• Requires confirmation (y/N)
• If nothing exists for that domain, it exits with code 2 (useful for scripts)

⁠🔐 senv (SOPS/Age env workflow)

⁠Typical usage

Initialize (creates missing defaults only when writable/mounted):

senv init

Initialize repo-local config in current directory:

senv init --local

Local-only init (does not touch /etc/share/sops):

senv init --local-only

Status / info:

senv info

Encrypt / decrypt (defaults):

senv enc          # .env -> .env.enc
senv dec          # .env.enc -> .env
senv edit         # edit .env.enc using sops editor mode

Explicit input/output:

senv enc --in=./.env --out=./.env.enc
senv dec --in=./.env.enc --out=./.env

Use “shared encrypted env repo” as input source:

# reads from /etc/share/vhosts/sops/demo.env.enc
# writes to ./demo.env (unless --out is set)
senv dec --in=demo.env.enc

# nested path inside the shared repo
senv dec --in=projectA/prod/.env.enc --out=./.env

Push/Pull sugar (shared encrypted repo):

# pull /etc/share/vhosts/sops/<project>/.env.enc -> ./.env
senv pull --project projectA

# push ./.env -> /etc/share/vhosts/sops/<project>/.env.enc
senv push --project projectA

⁠🔔 Notifications

⁠Server: notifierd

notifierd listens on TCP (default 9901) and emits a single-line event to stdout with a fixed prefix (default __HOST_NOTIFY__).

⁠Client: notify (inside the tools container)

notify "Build done" "All services are healthy ✅"

⁠🖥️ Host sender: docknotify

A host-side companion that sends notifications to the tools notifierd service using a stable one-line TCP protocol.

Protocol (tab-separated): token timeout urgency source title body

⁠Install on host

sudo curl -fsSL \
  "https://raw.githubusercontent.com/infocyph/Scriptomatic/refs/heads/main/bash/docknotify.sh" \
  -o /usr/local/bin/docknotify \
  && sudo chmod +x /usr/local/bin/docknotify

⁠Usage

docknotify "Build done" "All services are healthy ✅"

⁠📟 Tail docker logs (formatted watcher)

docker logs -f docker-tools 2>/dev/null | awk -v p="__HOST_NOTIFY__" '
  index($0, p) == 1 {
    line = $0
    sub("^" p "[ \t]*", "", line)

    n = split(line, a, "\t")
    if (n >= 6) {
      urgency = a[3]
      source = a[4]
      title = a[5]

      body = a[6]
      for (i = 7; i <= n; i++) body = body "\t" a[i]

      printf("[%-8s][%s] %s — %s\n", urgency, source, title, body)
    } else {
      print line
    }
    fflush()
  }
'

⁠🌍 Environment variables (tools container)

⁠🐳 Lazydocker

docker exec -it docker-tools lazydocker

Make sure /var/run/docker.sock is mounted.

⁠📝 License

Licensed under the MIT License⁠ © infocyph