Files
dashcaddy/ops/shipdeck-bridge/gh_install.py
T
DashCaddy Polish Loop 0dd8493f98 [grade=A] Shipdeck fleet module and manual deploy flow
Adds validated fleet install/lifecycle routes, bridge-backed Git and OCI workflows, persistent service cards, and the Local-tab Shipdeck deployment UI while preserving catalog and External flows.

Judge: urn:ump:if6udffdyelsf4qvskkr65ikhuprsjiajzij6h653fhf2zgyynzq
2026-09-15 11:13:29 -07:00

504 lines
24 KiB
Python

# DC-131: GitHub install — clone, detect, emit Shipdeckfile, deploy, persist metadata.
import json
import hashlib
import os
import re
import subprocess
import sys
# Imported by bridge.py (kept separate so the core bridge stays reviewable).
import shutil
import time
import urllib.parse
import urllib.request
# DC-133: source server is a user choice. Any https host with /owner/repo.
REPO_URL_RE = re.compile(
r"^https://([A-Za-z0-9.-]+)(?::(\d+))?/([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?$")
GITHUB_API_HOSTS = {"github.com", "www.github.com"}
FLEET_GITEA_HOST = os.environ.get("SHIPDECK_GITEA_HOST", "git.dashcaddy.net")
FLEET_GITEA_TOKEN_FILE = os.environ.get("SHIPDECK_GITEA_TOKEN_FILE", "/etc/shipdeck/gitea-token")
RESERVED_NAMES = {
"dashcaddy", "sec", "chat", "plex", "jellyfin", "atis", "atistest",
"status", "get", "get2", "mail", "sami", "moviecast", "cast", "shipdeck",
"src", "docs", "router", "sync", "torrent", "radarr", "sonarr", "prowlarr",
"portainer", "requests", "emby", "seerr", "gitea", "qdrant", "albyhub",
}
INSTALL_PORT_MIN, INSTALL_PORT_MAX = 8950, 8999
INSTALL_TIMEOUT = int(os.environ.get("SHIPDECK_INSTALL_TIMEOUT", "900"))
GH_APPS_DIR = os.environ.get("DASHCADDY_GH_APPS_DIR", "/opt/dashcaddy/dashcaddy-api/data/gh-apps")
Q3 = chr(34) * 3
SAFE_GO_PACKAGE_RE = re.compile(r"^(?:\.|\./[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*)$")
_STATE = {}
def init_shared(re_service, repos_root, port, lock, run_fn):
# bridge.py calls this once at import; avoids a circular import.
_STATE.update(RE_SERVICE=re_service, REPOS_ROOT=repos_root,
PORT=port, LOCK=lock, RUN=run_fn)
def _used_ports():
used = set([_STATE['PORT']])
try:
out = subprocess.run(["ss", "-ltn"], capture_output=True, text=True, timeout=10).stdout
for line in out.splitlines():
m = re.search(r":(\d+)\s", line)
if m:
used.add(int(m.group(1)))
except Exception:
pass
return used
def _pick_port():
used = _used_ports()
for p in range(INSTALL_PORT_MIN, INSTALL_PORT_MAX + 1):
if p not in used:
return p
return None
def _detect_and_emit(repo_dir, service, subdomain, host_ts_ip, requested_port=None):
"""Detect Go/Node/Python, write a Shipdeckfile, and return launch metadata."""
port = requested_port or _pick_port()
if not isinstance(port, int) or port < 1 or port > 65535:
raise RuntimeError("port must be 1-65535")
if port in _used_ports():
raise RuntimeError("requested port is already in use")
pkg_bin = "bin/app"
mode = ""
launch = []
build_cmd = ""
import glob as _glob
if os.path.isfile(os.path.join(repo_dir, "go.mod")):
main_pkg = None
for gf in _glob.glob(os.path.join(repo_dir, "*.go")):
try:
with open(gf, encoding="utf-8", errors="replace") as fh:
if "package main" in fh.read(2048):
main_pkg = "."
break
except OSError:
continue
if main_pkg is None:
dirs = sorted(_glob.glob(os.path.join(repo_dir, "*")))
dirs += sorted(_glob.glob(os.path.join(repo_dir, "cmd", "*")))
for d in dirs:
if not os.path.isdir(d):
continue
for gf in _glob.glob(os.path.join(d, "*.go")):
try:
with open(gf, encoding="utf-8", errors="replace") as fh:
if "package main" in fh.read(2048):
main_pkg = "./" + os.path.relpath(d, repo_dir)
break
except OSError:
continue
if main_pkg:
break
if not main_pkg:
raise RuntimeError("no Go main package found (module root, subdirs, or cmd/*)")
# main_pkg comes from repository-controlled directory names and is
# embedded in Shipdeck's shell build_cmd. Reject every shell metachar,
# whitespace byte and traversal segment before rendering it.
if not SAFE_GO_PACKAGE_RE.fullmatch(main_pkg) or ".." in main_pkg.split("/"):
raise RuntimeError("Go main package path contains unsafe characters")
build_cmd = "go build -buildvcs=false -o " + pkg_bin + " " + main_pkg
launch = ["/opt/" + service + "/current/app"]
mode = "go-build"
elif os.path.isfile(os.path.join(repo_dir, "package.json")):
with open(os.path.join(repo_dir, "package.json"), encoding="utf-8") as fh:
package = json.load(fh)
entry = package.get("main") or "server.js"
if not re.match(r"^[A-Za-z0-9][A-Za-z0-9._/-]*$", entry) or ".." in entry:
raise RuntimeError("package.json main is not a safe relative path")
pkg_bin = ".shipdeck-app"
build_cmd = ("npm ci && npm run build --if-present && rm -rf .shipdeck-app && "
"mkdir .shipdeck-app && cp -a package.json node_modules .shipdeck-app/ && "
"if [ -d dist ]; then cp -a dist .shipdeck-app/; fi && "
"if [ -d src ]; then cp -a src .shipdeck-app/; fi && "
"if [ -f " + entry + " ]; then mkdir -p .shipdeck-app/$(dirname " + entry + ") && cp -a " + entry + " .shipdeck-app/" + entry + "; fi")
launch = ["/usr/bin/node", "/opt/" + service + "/current/.shipdeck-app/" + entry]
mode = "node-build"
elif os.path.isfile(os.path.join(repo_dir, "requirements.txt")) or os.path.isfile(os.path.join(repo_dir, "pyproject.toml")):
entry = "app.py" if os.path.isfile(os.path.join(repo_dir, "app.py")) else "main.py"
if not os.path.isfile(os.path.join(repo_dir, entry)):
raise RuntimeError("Python repo requires app.py or main.py for automatic install")
pkg_bin = ".shipdeck-app"
install = ".venv/bin/pip install -r requirements.txt" if os.path.isfile(os.path.join(repo_dir, "requirements.txt")) else ".venv/bin/pip install ."
build_cmd = ("rm -rf .shipdeck-app .venv && python3 -m venv .venv && " + install +
" && mkdir .shipdeck-app && cp -a .venv " + entry + " .shipdeck-app/")
launch = ["/opt/" + service + "/current/.shipdeck-app/.venv/bin/python", "/opt/" + service + "/current/.shipdeck-app/" + entry]
mode = "python-build"
else:
raise RuntimeError("no automatic recipe: expected go.mod, package.json, requirements.txt, or pyproject.toml")
nl = "\n"
block = subdomain + ".sami {" + nl + "\treverse_proxy 127.0.0.1:" + str(port) + nl + "}"
Q = chr(34)
cfg = (
"# Shipdeckfile generated by shipdeck-bridge /api/install" + nl
+ "[service]" + nl
+ "name = " + Q + service + Q + nl
+ "build_cmd = " + Q + build_cmd.replace("\\", "\\\\").replace(Q, "\\" + Q) + Q + nl
+ "binary = " + Q + pkg_bin + Q + nl
+ nl + "[deploy]" + nl
+ "host = " + Q + "dns2" + Q + nl
+ "systemd_unit = " + Q + service + ".service" + Q + nl
+ "port = " + str(port) + nl
+ nl + "[caddy]" + nl
+ "block = " + Q*3 + nl + block + nl + Q*3 + nl
+ "tailnet_only = true" + nl
+ nl + "[dns]" + nl
+ "zone = " + Q + "sami" + Q + nl
+ "record = " + Q + subdomain + ".sami" + Q + nl
+ "target = " + Q + host_ts_ip + Q + nl
+ nl + "[verify]" + nl
+ "http = " + Q + "https://" + subdomain + ".sami/" + Q + nl
+ "timeout = 20" + nl
)
shipdeckfile = os.path.join(repo_dir, "Shipdeckfile")
with open(shipdeckfile, "w") as fh:
fh.write(cfg)
return {"mode": mode, "port": port, "binary": pkg_bin, "launch": launch,
"shipdeckfile": shipdeckfile}
# args->unit support (DC-131): optional launch args become a repo-provided
# systemd unit so shipdeck stages + packages it like any repo unit.
ARG_RE = re.compile(r"^[A-Za-z0-9_./=+-]+$")
def _write_repo_unit(repo_dir, service, binary_rel, args, env=None, launcher=None):
"""Write deploy/<service>.service with args + env baked in."""
unit_dir = os.path.join(repo_dir, "deploy")
os.makedirs(unit_dir, exist_ok=True)
binbase = os.path.basename(binary_rel)
if launcher:
if (not isinstance(launcher, list) or not launcher or any(
not isinstance(a, str) or not a or chr(10) in a or chr(13) in a
for a in launcher)):
raise ValueError("invalid detected launcher")
exec_line = " ".join(launcher)
else:
exec_line = "/opt/" + service + "/current/" + binbase
if args:
exec_line += " " + " ".join(args)
env_lines = ""
for k, v in sorted((env or {}).items()):
# gh_install validates this before shared-state mutation. Keep the
# helper fail-closed too: never silently drop an environment value.
if (not isinstance(k, str) or not isinstance(v, str)
or not re.match(r"^[A-Z_][A-Z0-9_]*$", k)
or len(v) > 300 or chr(34) in v or chr(92) in v
or any(ord(ch) < 32 or ord(ch) == 127 for ch in v)):
raise ValueError("invalid systemd environment entry: " + str(k)[:40])
env_lines += "Environment=" + chr(34) + k + "=" + v + chr(34) + chr(10)
nl = chr(10)
q = chr(34)
unit = (
"[Unit]" + nl
+ "Description=" + service + " (shipdeck)" + nl
+ "After=network-online.target" + nl
+ "Wants=network-online.target" + nl
+ nl + "[Service]" + nl
+ "Type=simple" + nl
+ "ExecStart=" + exec_line + nl
+ env_lines
+ "Restart=always" + nl
+ "RestartSec=5" + nl
+ "User=root" + nl
+ nl + "[Install]" + nl
+ "WantedBy=multi-user.target" + nl
)
path = os.path.join(unit_dir, service + ".service")
with open(path, "w") as fh:
fh.write(unit)
return path
# ---- Gitea support (DC-132, 2026-09-14) ------------------------------------
GITEA_HOST = os.environ.get("SHIPDECK_GITEA_HOST", "git.dashcaddy.net")
GITEA_URL_RE = re.compile(
r"^https://" + re.escape(GITEA_HOST) + r"/([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?/?$")
GITEA_TOKEN_FILE = os.environ.get("SHIPDECK_GITEA_TOKEN_FILE", "/etc/shipdeck/gitea-token")
def _gitea_token():
try:
with open(GITEA_TOKEN_FILE) as fh:
return fh.read().strip()
except OSError:
return ""
def _gitea_api(path):
tok = _gitea_token()
req = urllib.request.Request(
"https://" + GITEA_HOST + "/api/v1" + path,
headers={"Authorization": "token " + tok, "User-Agent": "shipdeck-bridge"})
with urllib.request.urlopen(req, timeout=15) as r:
return json.loads(r.read().decode("utf-8", "replace"))
def list_repos(payload):
"""List repos from the configured fleet Gitea only.
Arbitrary Git hosts remain valid clone sources for /api/install, but this
privileged bridge never turns a user-supplied host into an authenticated
HTTP metadata request (SSRF boundary).
"""
g_url = payload.get("gitea_url")
token_supplied = "token" in payload
req_tok = payload.get("token")
if req_tok is not None and (not isinstance(req_tok, str)
or len(req_tok) > 512):
# same contract as the panel proxy layer (routes/deploys.js)
return 400, {"ok": False, "error": "invalid token"}
if g_url is not None and not isinstance(g_url, str):
return 400, {"ok": False, "error": "gitea_url must be a string"}
g_url = (g_url or "").strip().rstrip("/")
if g_url:
try:
parsed = urllib.parse.urlparse(g_url)
parsed_port = parsed.port
except ValueError:
return 400, {"ok": False, "error": "invalid gitea_url"}
if (parsed.scheme != "https" or parsed.hostname != FLEET_GITEA_HOST
or parsed.username or parsed.password or parsed.path not in ("", "/")
or parsed.query or parsed.fragment or parsed_port not in (None, 443)):
return 400, {"ok": False, "error": "gitea_url must be the configured fleet Gitea host"}
api_base = "https://" + FLEET_GITEA_HOST + "/api/v1"
tok = (req_tok or "").strip()
else:
api_base = "https://" + FLEET_GITEA_HOST + "/api/v1"
# Omitted token = use fleet credential. Explicit empty token =
# anonymous, even against the fleet host (wire-level distinction).
tok = (req_tok or "").strip() if token_supplied else _gitea_token()
headers = {"User-Agent": "shipdeck-bridge"}
if tok:
headers["Authorization"] = "token " + tok
try:
req = urllib.request.Request(api_base + "/repos/search?limit=50&archived=false",
headers=headers)
with urllib.request.urlopen(req, timeout=15) as r:
repos = json.loads(r.read().decode("utf-8", "replace"))
except Exception as e:
return 502, {"ok": False, "error": "gitea API unreachable: " + str(e)[:200]}
host = re.match(r"https?://([^/]+)", api_base).group(1)
items = []
for repo in repos.get("data", []):
full = repo.get("full_name", "")
items.append({
"id": full.split("/")[-1].lower().replace("_", "-"),
"name": repo.get("name"),
"full_name": full,
"url": "https://" + host + "/" + full,
"host": host,
"logo": (repo.get("owner") or {}).get("avatar_url") or "",
"description": (repo.get("description") or "")[:120],
})
return 200, {"ok": True, "repos": items}
def _http_json(url, timeout=20, headers=None):
h = {"User-Agent": "shipdeck-bridge"}
if headers:
h.update(headers)
req = urllib.request.Request(url, headers=h)
with urllib.request.urlopen(req, timeout=timeout) as r:
return json.loads(r.read().decode("utf-8", "replace"))
def _gh_env_token():
return os.environ.get("SHIPDECK_GH_TOKEN", "")
def gh_install(payload):
"""Clone, detect, emit Shipdeckfile, deploy, persist metadata. -> (code, body)"""
repo_url = payload.get("repo_url")
service = payload.get("service")
subdomain = payload.get("subdomain")
req_token_raw = payload.get("token")
token_supplied = "token" in payload
# Validate types BEFORE any string ops: a non-string from a direct
# bridge call must 400, never raise (same contract as the panel proxy).
if repo_url is not None and not isinstance(repo_url, str):
return 400, {"ok": False, "error": "repo_url must be a string"}
if service is not None and not isinstance(service, str):
return 400, {"ok": False, "error": "service must be a string"}
if subdomain is not None and not isinstance(subdomain, str):
return 400, {"ok": False, "error": "subdomain must be a string"}
if req_token_raw is not None and not isinstance(req_token_raw, str):
return 400, {"ok": False, "error": "invalid token"}
repo_url = repo_url or ""
service = (service or "").strip().lower()
subdomain = (subdomain or service).strip().lower()
req_token = (req_token_raw or "").strip()
m = REPO_URL_RE.match(repo_url)
if not m:
return 400, {"ok": False, "error": "repo_url must be https://host/owner/repo"}
rh, rport, owner, repo = m.group(1), m.group(2), m.group(3), m.group(4)
if len(req_token) > 512:
return 400, {"ok": False, "error": "token too long"}
if req_token and not re.match(r"^[A-Za-z0-9_.=~-]+$", req_token):
return 400, {"ok": False, "error": "token has unexpected characters"}
# metadata: GitHub API for github.com, Gitea API for anything else.
# Best-effort: an install can proceed even if metadata is unavailable.
logo_url = ""
name = repo
try:
if rh in GITHUB_API_HOSTS:
logo_url = "https://github.com/" + owner + ".png"
gh_headers = {}
gh_token = req_token if token_supplied else _gh_env_token()
if gh_token:
gh_headers["Authorization"] = "token " + gh_token
meta = _http_json("https://api.github.com/repos/%s/%s" % (owner, repo),
headers=gh_headers)
name = meta.get("name") or repo
logo_url = (meta.get("owner") or {}).get("avatar_url") or logo_url
elif rh == FLEET_GITEA_HOST and rport in (None, "443"):
g_api = "https://" + rh + (":" + rport if rport else "") + "/api/v1"
g_tok = req_token if token_supplied else (
_gitea_token() if rh == FLEET_GITEA_HOST else "")
g_headers = {"Authorization": "token " + g_tok} if g_tok else {}
meta = _http_json(g_api + "/repos/" + owner + "/" + repo,
headers=g_headers)
name = meta.get("name") or repo
logo_url = (meta.get("owner") or {}).get("avatar_url") or (
"https://" + rh + "/avatars/" + owner)
# Other HTTPS Git hosts are clone-only. Do not make an HTTP metadata
# request to an arbitrary user-selected host from this root service.
except Exception as exc:
# Metadata is best-effort; the install can proceed without it. Log a
# sanitized diagnostic (repo identity only — never token values) so
# failures aren't silent.
print("gh_install: metadata lookup failed for %s/%s on %s: %s"
% (owner, repo, rh, exc), file=sys.stderr)
# clone auth: per-request token wins; else fleet token for fleet gitea.
# Credentials are passed via env-based git config (GIT_CONFIG_*), which
# never appears in process argv (/proc/cmdline) and never lands in the
# clone URL, so git's own error output cannot echo the token.
clone_url = repo_url
tok = req_token if token_supplied else (
_gitea_token() if rh == FLEET_GITEA_HOST else "")
# Start from the service environment but strip inherited GIT_CONFIG_*
# injection. Otherwise an operator/debug environment could leak an
# unrelated header into an explicit-anonymous clone. Add back only the
# one scoped auth config constructed here.
clone_env = {k: v for k, v in os.environ.items()
if not k.startswith("GIT_CONFIG_")}
clone_env["GIT_TERMINAL_PROMPT"] = "0"
if tok:
clone_env["GIT_CONFIG_COUNT"] = "1"
clone_env["GIT_CONFIG_KEY_0"] = "http.https://%s%s/.extraheader" % (
rh, ":" + rport if rport else "")
clone_env["GIT_CONFIG_VALUE_0"] = "Authorization: Bearer " + tok
def _scrub(text):
# defense-in-depth: never echo a token value back to the panel
return text.replace(tok, "<redacted>") if tok else text
if not _STATE["RE_SERVICE"].match(service):
return 400, {"ok": False, "error": "service must match ^[a-z0-9][a-z0-9-]{0,62}$"}
if service in RESERVED_NAMES or subdomain in RESERVED_NAMES:
return 400, {"ok": False, "error": "service name is reserved"}
if not _STATE["RE_SERVICE"].match(subdomain):
return 400, {"ok": False, "error": "invalid subdomain"}
target = os.path.join(_STATE["REPOS_ROOT"], "repos", "gh-" + service)
if os.path.exists(target):
return 409, {"ok": False, "error": "service dir already exists: " + target}
# Cheap input validation for args/env happens HERE, before the lock:
# a payload that was never valid must not touch shared state (no clone
# dir, no Shipdeckfile, no port scan). Port augmentation still happens
# after detection because it needs the chosen port.
args_cfg = payload.get("args")
if args_cfg is not None and (not isinstance(args_cfg, list) or any(
not isinstance(a, str) or not ARG_RE.match(a) or len(a) > 120
for a in args_cfg)):
return 400, { "ok": False, "error": "args must be a list of simple tokens" }
env_cfg = payload.get("env")
if env_cfg is not None and (not isinstance(env_cfg, dict) or any(
not isinstance(k, str) or not isinstance(v, str)
or not re.match(r"^[A-Z_][A-Z0-9_]*$", k)
or len(v) > 300 or chr(34) in v or chr(92) in v
or any(ord(ch) < 32 or ord(ch) == 127 for ch in v)
for k, v in env_cfg.items())):
return 400, {"ok": False, "error": (
"env must map valid uppercase names to strings <=300 chars "
"without quotes, backslashes, or control characters")}
requested_port = payload.get("port")
if requested_port is not None and (not isinstance(requested_port, int) or
isinstance(requested_port, bool) or
requested_port < 1 or requested_port > 65535):
return 400, {"ok": False, "error": "port must be an integer from 1 to 65535"}
sha_pin = payload.get("sha256")
if sha_pin is not None and (not isinstance(sha_pin, str) or
not re.match(r"^[a-f0-9]{64}$", sha_pin)):
return 400, {"ok": False, "error": "sha256 must be 64 lowercase hex characters"}
# Serialize the shared-state window on the bridge mutation lock.
# Judge round-3: port selection previously ran outside the lock
# (ss-snapshot race between concurrent installs). Now clone, port
# choice, file writes and deploy all run under the lock, so a
# concurrent install's ss scan sees the ports the previous install
# already bound — allocation is serialized, not racy.
with _STATE['LOCK']:
t0 = time.time()
clone = subprocess.run(
["git", "clone", "--depth", "1", "--single-branch", clone_url, target],
capture_output=True, text=True, timeout=180,
env=clone_env)
if clone.returncode != 0:
shutil.rmtree(target, ignore_errors=True)
return 400, {"ok": False,
"error": "clone failed: " + _scrub((clone.stderr or ""))[-400:]}
if sha_pin:
archived = subprocess.run(
["git", "-C", target, "archive", "--format=tar", "HEAD"],
capture_output=True, timeout=60)
if archived.returncode != 0:
shutil.rmtree(target, ignore_errors=True)
return 400, {"ok": False, "error": "could not hash cloned source"}
actual_sha = hashlib.sha256(archived.stdout).hexdigest()
if actual_sha != sha_pin:
shutil.rmtree(target, ignore_errors=True)
return 400, {"ok": False, "error": "source sha256 mismatch"}
try:
ts = subprocess.run(["tailscale", "ip", "-4"], capture_output=True,
text=True, timeout=10).stdout.split()
host_ts_ip = ts[0] if ts else ""
det = _detect_and_emit(target, service, subdomain, host_ts_ip, requested_port)
except Exception as e:
shutil.rmtree(target, ignore_errors=True)
return 400, {"ok": False, "error": str(e)[:400]}
args = payload.get("args") or []
# align the listen port with the deployed caddy target unless the
# caller supplied one
has_listen = any(a.lower().lstrip("-").startswith("listen") or a.lower().lstrip("-").startswith("addr") for a in args)
if not has_listen and det.get("port"):
args = args + ["-listen", "127.0.0.1:" + str(det["port"])]
env_cfg = payload.get("env") or {}
env_out = {str(k): str(v) for k, v in (env_cfg or {}).items()}
if det.get("port"):
env_out.setdefault("PORT", str(det["port"]))
_write_repo_unit(target, service, det.get("binary", "bin/app"), args,
env_out, det.get("launch"))
code, out = _STATE["RUN"](["deploy", target], INSTALL_TIMEOUT)
if code != 0:
return 500, {"ok": False, "error": "deploy failed", "output": out[-4000:], "dir": target}
info = {
"id": service, "name": name, "repo_url": repo_url,
"subdomain": subdomain, "url": "https://%s.sami" % subdomain,
"logo": logo_url, "mode": det.get("mode"), "port": det.get("port"),
"dir": target, "installed_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
"shipdeckfile": "/var/lib/shipdeck/services/" + service + "/Shipdeckfile",
"journal_row_id": service + ":" + str(int(time.time())),
"deploy_seconds": round(time.time() - t0, 1),
}
try:
os.makedirs(GH_APPS_DIR, exist_ok=True)
with open(os.path.join(GH_APPS_DIR, service + ".json"), "w") as f:
json.dump(info, f, indent=1)
except OSError:
pass
return 200, {"ok": True, "service": info, "output": out[-2000:]}