9.7 KiB
Skeleton Works: Conductor installation and handover
Audience: the VM administrator. This guide covers a new Skeleton Works Conductor installation using the verified v1.1.0 release. Upgrading an existing installation is covered by the upgrade and recovery guide from SLICE13.
Conductor is a required application in the Skeleton Works SaaS offering. Social Scheduler and future included applications are installed separately into it. Customers can still use Node-RED and its APIs for their daily work.
Before setup
Complete bootstrap.sh and setup-caddy.sh on the new Ubuntu AMD64 VM. The shared Caddy configuration and Docker/Compose must exist. DNS for the chosen Conductor hostname must point to this VM. Bootstrap deploys every sibling shell script into /opt/skeletonworks/scripts.
Deploy these three matching scripts together from the updated skeletonworks-scripts folder:
- setup-conductor.sh — installs the verified release.
- backup-conductor.sh — backs up SQLite, configuration, keys and installed app files.
- restore-conductor.sh — verifies and restores that recovery set; accepts backup formats v1 and v2.
If bootstrap has already run, copy these three updated files to the VM, then install them into the scripts directory:
sudo install -o admin -g admin -m 755 \
setup-conductor.sh backup-conductor.sh restore-conductor.sh \
/opt/skeletonworks/scripts/
Use this on a new installation. Do not replace the matched recovery tooling on the current combined 0.4.0 Conductor/Social Scheduler VM until following its upgrade plan.
Setup checks Docker/Compose, Python 3, OpenSSL, cron and the admin account. It does not install or use Node.js on the VM host. Node runs inside Conductor's container. There is no Conductor PostgreSQL setup: Conductor uses SQLite. Social Scheduler's own installer handles its PostgreSQL database.
The default is the published Conductor v1.1.0 image pinned to this verified OCI digest:
gitea.skeletonworks.online/vwiebe/conductor:v1.1.0@sha256:ab5e7dcaed065a304660af31e53ffada290b22dc9176ffeb5817f2e7f07ac313
The image supplies the finished management screens, default favicon, browser titles and installed-application host. Setup does not patch or build frontend source. Release artifacts and verification are publicly downloadable.
1. Review the plan
Replace customer.example.com with the customer's base domain:
sudo bash /opt/skeletonworks/scripts/setup-conductor.sh \
--domain customer.example.com \
--restartcaddy \
--dry-run
Why: confirm the hostname, exact image, container and volume before installation. Expected: a JSON plan and no changes to files, images, containers, keys, Caddy or cron.
Use sudo for dry-run too: bootstrap protects /opt/skeletonworks. A permission failure is not evidence that the installation is missing.
The default URL in this example is https://conductor.customer.example.com. Supported alternatives:
| Arguments | Resulting hostname |
|---|---|
| --domain customer.example.com | conductor.customer.example.com |
| --domain conductor.customer.example.com | conductor.customer.example.com |
| --domain customer.example.com --subdomain portal | portal.customer.example.com |
| --domain customer.example.com --subdomain portal.other.example.com | portal.other.example.com |
Supply DNS names without https://, a path or a port. Setup never substitutes a developer preview URL.
2. Install
Run the same command without --dry-run:
sudo bash /opt/skeletonworks/scripts/setup-conductor.sh \
--domain customer.example.com \
--restartcaddy
Why: install and expose the actual application. Expected: the pinned image is pulled publicly, its application-host capability is checked, Conductor becomes healthy, the Caddy configuration validates and reloads, and a backup job is installed.
The --restartcaddy flag applies the validated configuration through a graceful Caddy reload. Without it, setup saves the route but reports caddyApplied: false; apply that saved configuration before opening the browser. Validation uses the Caddy command-line interface and preserves other applications' site blocks.
The command prints a redacted JSON result and saves the same document at:
/opt/skeletonworks/conductor/CONDUCTOR_FQDN/setup-result.json
A complete installation reports status: success, started: true and health: healthy. The url and files fields are the discovery contract used by included-app installers.
Prepare now, start later
Use --no-start instead of --restartcaddy to write private configuration without pulling an image, starting a service, modifying Caddy or installing cron. The result is status: prepared, not a completed installation.
Rerun with the same domain, image and resource options, removing --no-start and adding --restartcaddy, to finish. The script verifies and reuses the prepared files and keys. Changed preparation files or different options are refused rather than silently overwritten.
An interrupted installation can resume from this preparation record. A completed or older installation is refused by fresh setup and directed to the separate upgrade process.
3. Application administrator handover
The VM administrator and application administrator can be different people. Give the customer's intended application administrator the final HTTPS URL and the Administrator Guide.
- Open that URL and create the first administrator. Why: establish the customer's application account; there is no default Conductor username or password. Expected: the first-run screen closes and the administrator reaches Conductor.
- Open Projects and create a small project. Why: verify the finished project-management screen and saving. Expected: the saved project appears in Projects.
- Open Publishing. Why: verify a clean installation does not advertise an app it cannot run. Expected: Included with Skeleton Works is empty.
- Check the browser tab. Why: confirm the installed release supplies the favicon and page titles. Expected: the Conductor icon and title appear; an installed app later receives its app-specific title.
- Follow the included application's installation/configuration guide. Why: keep app installation and customer-owned social credentials in their proper roles. Expected: a successfully installed app appears in Publishing.
For Social Scheduler, the VM administrator installs the 0.5.0 kit after Conductor, Node-RED and PostgreSQL are ready. The customer then connects social accounts in Conductor or Node-RED. The Social Scheduler installer remains responsible for registering its Publishing entry; base setup never seeds it.
The Social Scheduler discovery command also requires sudo:
sudo bash setup-social-scheduler.sh --dry-run
If multiple Conductor installations exist, use its --conductor-result option with the exact protected setup-result.json path above.
Persistence and recovery
The generated container has a read-only root filesystem, runs as its non-root application user, and exposes port 8080 only on the shared Docker network. Caddy provides public HTTPS.
One named volume holds all Conductor state beneath /data:
- SQLite users, projects, publications, icons, installed-app selections and encrypted backend connections.
- Installed application files beneath /data/applications.
The stack's .env and .secrets hold persistent keys and have mode 600; the stack directory has mode 700. Keep both keys with the data backup. Recreating the container must retain this volume and configuration.
The matched backup script runs as admin every day at 01:45 in the VM's cron timezone and retains seven days by default. It uses SQLite's online backup and copies the verified app files referenced by that snapshot. Its checksummed backup includes the keys and Compose configuration. Confirm backup output before relying on the schedule:
sudo -u admin /opt/skeletonworks/scripts/backup-conductor.sh \
--fqdn conductor.customer.example.com
Why: verify the scheduled user's permissions and complete recovery coverage. Expected: status: success and coverage.installedApplications: true, plus the archive path. Copy the protected archive and checksum off the VM.
List available backups without restoring anything:
sudo bash /opt/skeletonworks/scripts/restore-conductor.sh \
--fqdn conductor.customer.example.com --list
To restore a deliberately selected backup:
sudo bash /opt/skeletonworks/scripts/restore-conductor.sh \
--fqdn conductor.customer.example.com \
--backup-file /absolute/path/to/conductor_BACKUP_TIMESTAMP.tar.gz
Why: recover Conductor data and the keys needed to read it. Expected: checksum/format/hostname checks, a confirmation prompt, a safety backup, brief Conductor downtime, restored database/app files and a healthy service. Noninteractive restore requires --force. This is recovery, not an application upgrade.
These backups do not replace Node-RED or PostgreSQL backups. Social credentials, private media, schedules and posting history belong to their respective application backends.
Existing installations
Fresh setup stops if it finds an existing installation, container or volume that is not its own unfinished preparation. This includes the current combined Conductor/Social Scheduler image. It leaves customer keys, app registrations and data intact.
Do not delete the setup result, preparation record or data volume to bypass this check. Use update-conductor.sh and its recovery guide for image migration and repeatable upgrades. SLICE12 records the exact fresh-install validation and its limits.