mirror of
https://github.com/bestnite/quadlet-migrator-skill.git
synced 2026-04-04 01:43:27 +00:00
nite
54376c4f62
Clarify that generated artifacts should be reviewed in the current directory first, install.sh only places Quadlet units into the Quadlet target directory, and runtime support files must be copied to their correct host-side paths. Also strengthen the skill's pod-first, support-file discovery, and env completeness validation rules. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# Deployment Notes
|
|
|
|
Use this file when the user wants deployment-ready instructions alongside generated Quadlet units.
|
|
|
|
## Delivery flow
|
|
|
|
1. Generate the reviewable artifacts in the current working directory.
|
|
2. Review the generated Quadlet files, env files, helper scripts, and any required repo-local support files or directories.
|
|
3. Use `install.sh` to copy only the reviewed unit files into the chosen Quadlet directory. Copy env files and any other required runtime support files into the correct host-side paths the deployment expects.
|
|
4. Use `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` to manage the deployed services.
|
|
|
|
## Apply target directory
|
|
|
|
### Rootless
|
|
|
|
- default apply target: `~/.config/containers/systemd/`
|
|
- user-scoped management commands use `systemctl --user`
|
|
|
|
### Rootful
|
|
|
|
- default apply target: `/etc/containers/systemd/`
|
|
- system-scoped management commands use `systemctl`
|
|
|
|
See `podman-systemd.unit.5.md` for the full search-path matrix.
|
|
|
|
## Helper scripts
|
|
|
|
- `install.sh`: canonical apply script; copy only reviewed Quadlet unit files into the selected Quadlet target directory, and copy env files plus any other required runtime support files into the correct host-side paths
|
|
- do not generate a separate `apply.sh` by default; reserve that alternate name only when the user explicitly asks for it
|
|
- `reload.sh`: run the appropriate `daemon-reload` command after installation changes
|
|
- `start.sh`: start the generated units
|
|
- `stop.sh`: stop the generated units
|
|
- `restart.sh`: restart the generated units after reload or config changes
|
|
|
|
Keep installation separate from service-management scripts so the user can review generated files before applying them.
|
|
`install.sh` should copy reviewed Quadlet unit files into the chosen Quadlet target directory and place required runtime support files into their correct host-side destinations only, and should not start, stop, restart, or reload services as a side effect.
|
|
`reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` should not silently install or overwrite reviewed files.
|
|
|
|
## Review checklist before install
|
|
|
|
Review not only the Quadlet unit files but also:
|
|
|
|
- env files referenced by `EnvironmentFile=`
|
|
- repo-local mounted config files and directory trees
|
|
- initialization files such as `init.sql`, seed data, or bootstrap assets
|
|
- repo-local entrypoint and helper scripts referenced by `Entrypoint=`, `Exec=`, docs, or wrapper scripts
|
|
|
|
Do not treat the deliverable as complete if these support files are still missing from the reviewable artifact set.
|
|
|
|
Execution checklist template before install:
|
|
|
|
- [ ] all reviewed artifacts are present in the current-directory deliverable tree
|
|
- [ ] required support files and directories are included alongside the Quadlet and env artifacts
|
|
- [ ] unit files map to the intended Quadlet directory
|
|
- [ ] support files map to the correct host-side runtime paths for mounts and scripts
|
|
- [ ] startup-critical env keys are present in the final env sources
|
|
- [ ] any unresolved values are clearly marked as intentionally non-runnable placeholders
|
|
- [ ] service-management scripts operate on the same reviewed artifact set that will be installed
|
|
|
|
## Rootless operational notes
|
|
|
|
- Bind mounts may hit UID/GID mismatches.
|
|
- For pod-based deployments that should preserve host ownership semantics, consider `UserNS=keep-id` on `[Pod]` when appropriate.
|
|
- If the service must survive logout, mention lingering:
|
|
|
|
```bash
|
|
sudo loginctl enable-linger <username>
|
|
```
|
|
|
|
## Paths and bind mounts
|
|
|
|
- Ensure bind-mount source directories exist before first start.
|
|
- Normalize relative source paths against the source Compose file directory or the directory the user specifies.
|
|
- Emit absolute host paths in generated Quadlet files when using bind mounts.
|
|
- Explain the resolved absolute path if the source used `./...`.
|
|
- If the source project bind-mounts repo-local files or directories, make sure the installed artifact set preserves the required contents and places them at the correct host-side paths expected by the mounts.
|
|
|
|
## Recommended service defaults
|
|
|
|
Depending on the workload, consider adding:
|
|
|
|
```ini
|
|
[Service]
|
|
Restart=always
|
|
TimeoutStartSec=900
|
|
```
|
|
|
|
Use the timeout especially when first start may need to pull large images or build locally.
|
|
|
|
## Useful optional enhancements
|
|
|
|
- `AutoUpdate=registry` for opt-in automatic image refresh workflows
|
|
- explicit `.volume` or `.network` units when the user wants declarative infrastructure instead of implicit Podman objects
|
|
|
|
## Output language
|
|
|
|
If you generate a README, deployment note, or operator-facing document as part of the migration, write it in the user's language unless the user explicitly asks for another language.
|