create-vordr-updater

Self-updating vordr instance for managing vordr releases and NPM publishing.

What It Does

Watches vordr repo → Runs tests → Syncs template → Publishes to NPM → Self-updates via Ragnarok.

Ragnarok = Self-destruct and reinstall from NPM (ensures updater runs published version).

Install

npx create-vordr-updater
cd vordr-updater
# Add NPM_TOKEN and NPM_EMAIL to .env
./tools/start.sh

Configuration

See envexample.vordr-updater.md for all variables.

Required additions to .env:

NPM_TOKEN=npm_xxx...          # From: npm token create
[email protected]

TEST_WEBHOOK_PORT=3001
TEST_WEBHOOK_SECRET=test_secret
TEST_GIT_REPO=https://github.com/octocat/Hello-World.git

RAGNAROK_PATH=/tmp/vordr-ragnarok
VORDR_PARENT_PATH=/home/user  # Where vordr-updater lives

Auto-configured:

• APP_PATH - Where monorepo clones (default: {cwd}/_project)
• SCRIPTS_PATH - Bootstrap scripts (default: ./scripts)

Flow

Normal Update

1. Push to vordr master
2. Webhook triggers
3. shutdown.sh
4. git pull monorepo → _project/
5. run-tests.sh (Gate #1: fail = delete _project/, abort)
6. init.sh
7. post-init.sh → sync-and-publish.sh:
   a. Backup template
   b. Sync _project/ → packages/create-vordr/template
   c. run-tests.sh (Gate #2: fail = restore backup, abort)
   d. Bump versions (query NPM for latest)
   e. Publish create-vordr
   f. Publish create-vordr-updater
   g. Commit version bumps
   h. Trigger Ragnarok

Ragnarok (Self-Update)

1. Inside vordr container:
   - Write /ragnarok/execute.sh
   - Backup .env
   - Spawn independent container:
     docker run -d node:18-alpine \
       -v /var/run/docker.sock:/var/run/docker.sock \
       -v /tmp/vordr-ragnarok:/ragnarok \
       -v /home/user:/workspace \
       sh -c 'sleep 10 && /ragnarok/execute.sh'

2. Ragnarok executor (independent):
   - Sleep 10s (wait for vordr to exit)
   - docker-compose down
   - rm -rf vordr-updater/
   - npx create-vordr-updater (latest from NPM)
   - Restore .env
   - Start new instance
   - Self-destruct (--rm)

Result: Updater runs latest NPM version (true dogfooding).

Architecture

Single-Source Monorepo:

• Base vordr has ZERO updater code
• Updater = minimal webhook dispatcher
• ALL logic in cloned monorepo at APP_PATH
• server.js auto-detects updater mode
• Uses scripts from ${APP_PATH}/packages/create-vordr-updater/scripts/
• Self-bootstrapping (scripts test themselves)

Patching: patch-docker-compose.sh adds to base vordr:

• /test-app mount → Isolated test deployments
• /ragnarok mount → Self-update workspace
• Environment variables for host paths

Directory Structure

project/
├── ragnarok-backup/          # Survives Ragnarok
│   └── .env
│
└── vordr-updater/           # Gets destroyed/recreated
    ├── _project/            # Cloned vordr monorepo
    ├── scripts/             # Updater-specific (overwrite base)
    │   ├── ragnarok.sh
    │   ├── sync-and-publish.sh
    │   ├── run-tests.sh
    │   ├── patch-docker-compose.sh
    │   ├── init.sh
    │   ├── shutdown.sh
    │   └── post-init.sh
    ├── docker/
    │   ├── docker-compose.yml      # PATCHED
    │   └── docker-compose.test.yml # For functional tests
    └── .env

Commands

./tools/start.sh              # Start updater
./tools/start.sh logs         # View logs
./scripts/ragnarok.sh         # Manual self-update
./scripts/sync-and-publish.sh # Manual publish

Safety

• .env backed up to ragnarok-backup/
• Two test gates (fail-fast on code, restore backup on template)
• Server stopped before Ragnarok
• Full logging

Testing

Test in dev branch first:

git checkout -b dev
# Make changes
git push origin dev  # Test without publishing

# When confident:
git checkout master
git merge dev
git push origin master  # Triggers updater

Troubleshooting

NPM publish fails:

• Check NPM_TOKEN: npm whoami
• Verify publish rights to package

Ragnarok fails:

• .env is safe in ragnarok-backup/
• Manual reinstall: npx create-vordr-updater
• Restore: cp ragnarok-backup/.env vordr-updater/.env

Tests fail:

• Gate #1 fail → _project/ deleted, wait for fix
• Gate #2 fail → Template restored, no publish

Non-Interactive Install

[email protected]:user/vordr.git \
VORDR_WEBHOOK_PORT=3000 \
VORDR_VPN_USER=vpn_user \
VORDR_VPN_PASS=vpn_pass \
VORDR_NPM_TOKEN=npm_xxx... \
[email protected] \
npx create-vordr-updater

Why Ragnarok?

Ensures updater runs what users install (published NPM version), not dev code. True dogfooding.

License

MIT