Add local development deployment workflow · 8b9c061

Add local development deployment workflow
Browse files

bogdan authored and Xdev Host Manager committed a day ago

main

1 parent 4d3f381

commit 8b9c061

Showing 3 changed files with 149 additions and 2 deletions

+15 -1

.doc/host-manager.md

@@ -68,7 +68,13 @@ hosts.madagascar.xdev.ro
 
 Configurațiile de deployment sunt în `deploy/jumper/`.
 
-Instanța de pe jumper este instalată în `/usr/local/xdev-host-manager` și publicată prin:
+Checkout-ul de dezvoltare este local:
+
+```text
+/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority
+```
+
+Instanța runtime de pe jumper este instalată în `/usr/local/xdev-host-manager` și publicată prin:
 
 ```text
 http://hosts.madagascar.xdev.ro/
@@ -80,6 +86,14 @@ Secretul TOTP nu este în repo. Pentru bootstrap, citește URI-ul root-only de p
 ssh jumper.madagascar.xdev.ro 'cat /etc/xdev/host-manager.totp-uri'
 ```
 
+Codul aplicației se modifică local și se publică pe jumper cu:
+
+```bash
+scripts/deploy_to_jumper.sh
+```
+
+Scriptul de deploy nu copiază implicit `config/`, deoarece acesta conține date operaționale editabile de aplicația live. Folosește `--include-config` doar când vrei explicit să înlocuiești registrul runtime.
+
 ## OTP
 
 `HOST_MANAGER_TOTP_SECRET` trebuie să fie un secret Base32 compatibil TOTP. Fără această variabilă, healthcheck-ul și pagina de login funcționează, dar login-ul, API-ul, download-urile și scrierile nu.


+24 -1

README.md

View

@@ -2,7 +2,13 @@
 
 Local authority for Madagascar hosts, DNS manifests, work orders, and host certificates.
 
-This project lives on jumper and is the local source for:
+The development checkout lives locally at:
+
+```text
+/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority
+```
+
+The runtime instance lives on jumper and remains the local source for operational registry data:
 
 - `config/hosts.yaml` - git-versioned host registry
 - `config/local-hosts.tsv` - DNS manifest exported for local resolvers
@@ -25,6 +31,23 @@ The product name is **Madagascar Local Authority**. The technical service, Unix
 
 The web UI is OTP-protected for all registry data, downloads, exports, and writes. Automation should consume this repository through git with dedicated read-only keys, not through unauthenticated HTTP.
 
+## Local development and deployment
+
+Work on application code locally, commit changes, then deploy to jumper:
+
+```bash
+cd /Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority
+scripts/deploy_to_jumper.sh
+```
+
+The deploy script copies code, docs and deployment assets, restarts `host-manager`, and checks `/healthz`.
+
+`config/` is not deployed by default because `hosts.yaml`, `local-hosts.tsv`, and `work-orders.yaml` are operational data that may be changed on jumper by the application. Deploy config only when intentionally replacing runtime registry data:
+
+```bash
+scripts/deploy_to_jumper.sh --include-config
+```
+
 The default internal domain is `madagascar.xdev.ro`. Short aliases are derived automatically from FQDNs, so `autonas01.madagascar.xdev.ro` also publishes `autonas01` without declaring it separately.
 
 Name removals with operational impact go through a Work Order. A WO records intent first; the operational checklist must be completed before confirmation can update `hosts.yaml`, mark the WO as confirmed, and regenerate `local-hosts.tsv`. Resolver sync remains an explicit operator step.


+110 -0

scripts/deploy_to_jumper.sh

View

+                    +#!/usr/bin/env bash
+                    +# Deploy Madagascar Local Authority application code to jumper.
+                    +set -euo pipefail
+                    +TARGET_HOST="${TARGET_HOST:-jumper.madagascar.xdev.ro}"
+                    +TARGET_DIR="${TARGET_DIR:-/usr/local/xdev-host-manager}"
+                    +RESTART=1
+                    +ALLOW_DIRTY=0
+                    +DRY_RUN=0
+                    +INCLUDE_CONFIG=0
+                    +usage() {
+                    +    cat <<EOF
+                    +Usage: $0 [--target host] [--target-dir path] [--no-restart] [--allow-dirty] [--dry-run] [--include-config]
+                    +Deploys application code/docs to jumper. Runtime registry data in config/ is not
+                    +deployed unless --include-config is explicit.
+                    +Environment:
+                    +  TARGET_HOST   Default: jumper.madagascar.xdev.ro
+                    +  TARGET_DIR    Default: /usr/local/xdev-host-manager
+                    +EOF
+                    +}
+                    +while [[ $# -gt 0 ]]; do
+                    +    case "$1" in
+                    +        --target)
+                    +            TARGET_HOST="$2"
+                    +            shift 2
+                    +            ;;
+                    +        --target-dir)
+                    +            TARGET_DIR="$2"
+                    +            shift 2
+                    +            ;;
+                    +        --no-restart)
+                    +            RESTART=0
+                    +            shift
+                    +            ;;
+                    +        --allow-dirty)
+                    +            ALLOW_DIRTY=1
+                    +            shift
+                    +            ;;
+                    +        --dry-run)
+                    +            DRY_RUN=1
+                    +            shift
+                    +            ;;
+                    +        --include-config)
+                    +            INCLUDE_CONFIG=1
+                    +            shift
+                    +            ;;
+                    +        --help|-h)
+                    +            usage
+                    +            exit 0
+                    +            ;;
+                    +        *)
+                    +            echo "Unknown option: $1" >&2
+                    +            usage >&2
+                    +            exit 2
+                    +            ;;
+                    +    esac
+                    +done
+                    +cd "$(dirname "$0")/.."
+                    +if [[ "$ALLOW_DIRTY" -ne 1 ]] && [[ -n "$(git status --porcelain)" ]]; then
+                    +    echo "Working tree is dirty; commit first or pass --allow-dirty." >&2
+                    +    git status --short >&2
+                    +    exit 1
+                    +fi
+                    +command -v rsync >/dev/null 2>&1 || {
+                    +    echo "rsync is required for deployment." >&2
+                    +    exit 1
+                    +}
+                    +ssh "$TARGET_HOST" "command -v rsync >/dev/null 2>&1" || {
+                    +    echo "rsync is required on $TARGET_HOST." >&2
+                    +    exit 1
+                    +}
+                    +perl -c scripts/host_manager.pl >/dev/null
+                    +rsync_args=(-az --delete)
+                    +if [[ "$DRY_RUN" -eq 1 ]]; then
+                    +    rsync_args+=(--dry-run --itemize-changes)
+                    +fi
+                    +ssh "$TARGET_HOST" "mkdir -p '$TARGET_DIR/scripts' '$TARGET_DIR/deploy' '$TARGET_DIR/.doc'"
+                    +rsync "${rsync_args[@]}" scripts/ "$TARGET_HOST:$TARGET_DIR/scripts/"
+                    +rsync "${rsync_args[@]}" deploy/ "$TARGET_HOST:$TARGET_DIR/deploy/"
+                    +rsync "${rsync_args[@]}" .doc/ "$TARGET_HOST:$TARGET_DIR/.doc/"
+                    +rsync "${rsync_args[@]}" README.md "$TARGET_HOST:$TARGET_DIR/README.md"
+                    +if [[ "$INCLUDE_CONFIG" -eq 1 ]]; then
+                    +    ssh "$TARGET_HOST" "mkdir -p '$TARGET_DIR/config'"
+                    +    rsync "${rsync_args[@]}" config/ "$TARGET_HOST:$TARGET_DIR/config/"
+                    +fi
+                    +if [[ "$DRY_RUN" -eq 1 ]]; then
+                    +    exit 0
+                    +fi
+                    +ssh "$TARGET_HOST" "cd '$TARGET_DIR' && perl -c scripts/host_manager.pl >/dev/null"
+                    +if [[ "$RESTART" -eq 1 ]]; then
+                    +    ssh "$TARGET_HOST" "sudo -n systemctl restart host-manager && systemctl is-active host-manager >/dev/null"
+                    +fi
+                    +ssh "$TARGET_HOST" "curl -fsS http://127.0.0.1:8088/healthz >/dev/null"
+                    +echo "Deployed to $TARGET_HOST:$TARGET_DIR"

	@@ -68,7 +68,13 @@ hosts.madagascar.xdev.ro
68	68
69	69	Configurațiile de deployment sunt în `deploy/jumper/`.
70	70
71		-Instanța de pe jumper este instalată în `/usr/local/xdev-host-manager` și publicată prin:
	71	+Checkout-ul de dezvoltare este local:
	72	+
	73	+```text
	74	+/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority
	75	+```
	76	+
	77	+Instanța runtime de pe jumper este instalată în `/usr/local/xdev-host-manager` și publicată prin:
72	78
73	79	```text
74	80	http://hosts.madagascar.xdev.ro/
	@@ -80,6 +86,14 @@ Secretul TOTP nu este în repo. Pentru bootstrap, citește URI-ul root-only de p
80	86	ssh jumper.madagascar.xdev.ro 'cat /etc/xdev/host-manager.totp-uri'
81	87	```
82	88
	89	+Codul aplicației se modifică local și se publică pe jumper cu:
	90	+
	91	+```bash
	92	+scripts/deploy_to_jumper.sh
	93	+```
	94	+
	95	+Scriptul de deploy nu copiază implicit `config/`, deoarece acesta conține date operaționale editabile de aplicația live. Folosește `--include-config` doar când vrei explicit să înlocuiești registrul runtime.
	96	+
83	97	## OTP
84	98
85	99	`HOST_MANAGER_TOTP_SECRET` trebuie să fie un secret Base32 compatibil TOTP. Fără această variabilă, healthcheck-ul și pagina de login funcționează, dar login-ul, API-ul, download-urile și scrierile nu.

	@@ -2,7 +2,13 @@
2	2
3	3	Local authority for Madagascar hosts, DNS manifests, work orders, and host certificates.
4	4
5		-This project lives on jumper and is the local source for:
	5	+The development checkout lives locally at:
	6	+
	7	+```text
	8	+/Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority
	9	+```
	10	+
	11	+The runtime instance lives on jumper and remains the local source for operational registry data:
6	12
7	13	- `config/hosts.yaml` - git-versioned host registry
8	14	- `config/local-hosts.tsv` - DNS manifest exported for local resolvers
	@@ -25,6 +31,23 @@ The product name is Madagascar Local Authority. The technical service, Unix
25	31
26	32	The web UI is OTP-protected for all registry data, downloads, exports, and writes. Automation should consume this repository through git with dedicated read-only keys, not through unauthenticated HTTP.
27	33
	34	+## Local development and deployment
	35	+
	36	+Work on application code locally, commit changes, then deploy to jumper:
	37	+
	38	+```bash
	39	+cd /Users/bogdan/Documents/Workspaces/Xdev/Madagascar/LocalAuthority
	40	+scripts/deploy_to_jumper.sh
	41	+```
	42	+
	43	+The deploy script copies code, docs and deployment assets, restarts `host-manager`, and checks `/healthz`.
	44	+
	45	+`config/` is not deployed by default because `hosts.yaml`, `local-hosts.tsv`, and `work-orders.yaml` are operational data that may be changed on jumper by the application. Deploy config only when intentionally replacing runtime registry data:
	46	+
	47	+```bash
	48	+scripts/deploy_to_jumper.sh --include-config
	49	+```
	50	+
28	51	The default internal domain is `madagascar.xdev.ro`. Short aliases are derived automatically from FQDNs, so `autonas01.madagascar.xdev.ro` also publishes `autonas01` without declaring it separately.
29	52
30	53	Name removals with operational impact go through a Work Order. A WO records intent first; the operational checklist must be completed before confirmation can update `hosts.yaml`, mark the WO as confirmed, and regenerate `local-hosts.tsv`. Resolver sync remains an explicit operator step.