12 KiB
Installing and releasing AstroFrame
First release
The first published version, 1.0.1, targets x64 Windows and Linux desktops. Download it from the release page. Windows uses a per-user Velopack installer. Linux uses one self-contained AppImage plus an optional per-user application-menu installer; the same binary targets both Debian and Arch. No Git client, Python, .NET runtime installation or administrator access is required to install AstroFrame itself.
Windows
Run AstroFrame-win-x64-Setup.exe. Setup creates application-menu and desktop shortcuts and an uninstall entry. Installations live under the user's local application-data directory. Updates replace the application files while leaving projects and preferences in their separate data directory.
These first packages are unsigned; Windows may display its unknown-publisher/SmartScreen prompt. Signing requires the maintainer's own signing certificate or signing service, and can be added to the Velopack pack command later.
Linux: Debian and Arch
Use a current x64 desktop with X11, or a Wayland desktop with XWayland. The AppImage bundles .NET and Avalonia; it still uses normal Linux system libraries. Debian 12/13 and current Arch are the intended targets. Minimal/server installations may need the following prerequisites.
Debian 12:
sudo apt install libicu72 libx11-6 libice6 libsm6 libfontconfig1 libxrandr2 libxi6 libxcursor1 libxrender1 libxext6 libfuse2 ca-certificates
Debian 13 uses libicu76 and libfuse2t64 instead of libicu72 and libfuse2. On Arch:
sudo pacman -Syu --needed icu libx11 libice libsm fontconfig libxrandr libxi libxcursor libxrender libxext fuse2 ca-certificates
AppImage runtimes may fall back to extraction when FUSE is unavailable. APPIMAGE_EXTRACT_AND_RUN=1 ./AstroFrame-linux-x64.AppImage explicitly requests that mode.
The Windows build also creates AstroFrame-<version>-linux-x64.zip containing the AppImage and installation helpers. Extract it, or download AstroFrame-linux-x64.AppImage, install-linux.sh and astroframe.png into the same folder. Then:
bash install-linux.sh ./AstroFrame-linux-x64.AppImage
This puts the AppImage in $XDG_DATA_HOME/AstroFrame/app/ (normally ~/.local/share/AstroFrame/app/) and adds an AstroFrame application-menu entry. It keeps the AppImage writable for updates. Alternatively, chmod +x AstroFrame-linux-x64.AppImage and run the file directly from a writable folder.
To uninstall a script-installed Linux copy, close AstroFrame and remove only ~/.local/share/AstroFrame/app, ~/.local/share/applications/astroframe.desktop and ~/.local/share/icons/hicolor/256x256/apps/astroframe.png (adjust paths if using XDG_DATA_HOME). Keep the other AstroFrame directories to preserve projects and settings.
Settings and updates
Version 1.0.2 corrects the spatial preview overlay. Pink shows the strongest positive sky structure against the clean session reference; the display fit resists bright cloud contamination, and weak background residuals are suppressed. Both bright and moderately bright cloud patches remain visible. The grid shows regional stellar flux. This is supporting evidence rather than an exact cloud boundary. Existing saved projects reconstruct the display from cached catalogs without changing classification metrics or human decisions. See 1.0.2 release notes.
Open Settings → Updates for the installed version, update status, last successful check, automatic-check preference, and Check for updates. The sidebar and independent settings store leave room for future categories.
Installed packages check on launch and every six hours while running. A persistent Settings · Update available indicator appears when a newer stable version is found. Install update and restart downloads the update, validates its package checksum, saves the project and restarts. Analysis, export and saving block installation; if work starts during download, the package remains ready for a later restart. Projects and settings survive updates. Failed checks display an error rather than claiming the app is up to date. Source-tree builds explain that installing a package enables updates.
The source is the repository's public Gitea releases API:
https://git.elijahkuntz.com/Elijah/AstroFrame/releases
Only published stable release assets are consumed. Git commits by themselves do not trigger an update. End-user installations contain no repository write token. Packages use separate win-x64 and linux-x64 channels. Versions never downgrade automatically.
Automatic server releases
.forgejo/workflows/release.yml selects the ubuntu-latest label advertised by unraid-runner and runs in a node:22-bookworm container. Actions selects runners by their labels, not their names. The job installs a .NET 10 SDK, the .NET 8 runtime used by the tests, and PowerShell 7.4.20 inside its disposable container. The Linux runner builds both the Windows Setup executable and Linux AppImage using Velopack's cross-platform packager; a Windows runner is not required for these unsigned installers.
Once this workflow is committed and pushed, enable Actions for the AstroFrame repository and ensure its Docker runner is available. Checkout is pinned to v4.4.0, which uses the Node 20 action runtime supported by runner v6.4.0. No separate personal token is needed for the workflow: the publish step uses Forgejo's built-in repository-scoped Actions token. The server must allow that token to create releases. The existing personal-token publisher remains available for local use.
To release a new version:
./packaging/Set-Version.ps1 -Version 1.0.3
git add Directory.Build.props
git commit -m "Release 1.0.3"
git push origin main
git tag v1.0.3
git push origin v1.0.3
Include all intended source changes in the release commit before tagging. The pushed tag is the publication trigger; ordinary commits to main run the build and checks without publishing. The version in Directory.Build.props must exactly match the tag. Version v1.0.1 is published; v1.0.0 remains an unpublished tag from the first failed publishing attempt. Choose a new version for each later release.
The job runs the engine, updater and release-publisher validation suites, builds both packages, renders the Linux settings page under Xvfb, then uploads everything into one draft release. Only after all uploads succeed does it make the release public, so users cannot discover an incomplete update. No local installer build or manual asset attachment is needed.
Use Actions → Release AstroFrame → Run workflow on main to verify runner setup without publishing. A manual run on a version tag publishes that version. Existing published releases cannot be overwritten. Interrupted uploads remain draft releases and can resume when matching build files are reused. If a fresh rebuild generates different bytes, the publisher reports the conflicting draft asset; remove the incomplete draft explicitly before rerunning. Do not delete an already published version.
The workflow tests Linux execution in Debian Bookworm; it creates Windows packages but cannot exercise their Windows UI. Windows desktop acceptance still needs a Windows machine. Upload/package failures appear in the Actions job log. Builds require outbound access to the Forgejo checkout action, Microsoft's SDK download endpoints and NuGet, plus enough disk space for both self-contained builds.
Local package builds
Set the next stable version in Directory.Build.props. -Version can override it for a build. The application and package versions must match. A .NET 10 SDK/runtime is needed for the pinned Velopack CLI; the application itself targets .NET 8 and is published self-contained. Use PowerShell 7 for the release scripts.
./Build.ps1 -Test
./packaging/Release.ps1
The Windows script cross-packages both platforms. Results appear in artifacts/releases/win-x64 and artifacts/releases/linux-x64. It refuses to reuse an existing publish folder, avoiding stale application files. For an intentional local rebuild use a fresh -PublishRoot artifacts/publish-candidate and a fresh -Output artifacts/releases-candidate; published version numbers must remain immutable.
On Linux with a .NET 10 SDK:
bash packaging/release.sh 1.0.2
That script builds the Linux channel. The tool manifest pins Velopack CLI 1.2.161, matching the application's SDK dependency. Building on Windows is enough to create both packages, but compatibility should still be checked on target Linux desktops.
Publish to the repository
Commit and push the versioned source first. Version v1.0.1 was built and published automatically by the server. The following local publisher is an alternative to the tag workflow for future versions.
The helper script reads a repository-write token from ASTROFRAME_RELEASE_TOKEN in the process environment. On the server this is supplied automatically by the workflow. For local publication, set your own Gitea/Forgejo repository-write token. The script uploads both platforms into one draft, including the Linux installation helpers. It does not store the token or embed it in the application:
./packaging/Publish.ps1
Review the draft in Gitea and publish it there. For a deliberately immediate publication use ./packaging/Publish.ps1 -Publish. The script refuses to modify an already published version. A partial upload can be resumed by rerunning with the same packages: existing assets are downloaded and compared by SHA256 before skipping them. Conflicting bytes require explicitly removing the draft asset or the incomplete draft. Do not put the token in a script, commit, or command history.
For manual publication attach, from both channel folders:
AstroFrame-<version>-<channel>-full.nupkgand any generated delta package;releases.<channel>.json,RELEASES-<channel>andassets.<channel>.json;- the Windows Setup executable and Linux AppImage;
install-linux.shandastroframe.png.
Keep older published releases available. The CLI can produce delta packages when previous packages are in the output folder. Full packages always support upgrading from older installs, even without a delta.
For later releases, use the automatic tag workflow above, or validate/build/publish locally. Existing installations then receive the notification and can update without reinstalling.
Verification
./tools/Verify-ReleaseAutomation.ps1 exercises version/tag mismatch, upload failure, draft resumption, conflicting assets, immutable published releases and package integrity with a mocked release API. It never publishes a real release.
tests/AstroFrame.Updates.Validation covers settings recovery, network failures, concurrent checks, restart safety, save failure, real package checksums, corruption rejection and downgrade prevention. An optional release-feed argument adds real-package checks:
dotnet run --project tests/AstroFrame.Updates.Validation -c Release -- artifacts/update-verification/releases/win-x64 win-x64
That test feed must contain a 1.0.1 package for the requested channel; it is not a production release. An explicit packaged-app --verify-update <local feed directory> <report.jsonl> --apply probe verifies actual replacement and restart. A --capture-settings <output.png> [width] [dpi] diagnostic captures the real settings page.
Both Windows and Linux local 1.0.0 → 1.0.1 replacement/restart were exercised during implementation. Linux rendering and per-user installation were checked under Ubuntu WSL with the missing ICU/X11 libraries extracted into a workspace test directory. Debian and Arch desktop execution have not yet been tested directly; those compatibility targets are based on the cross-platform runtime and documented system dependencies, not separate distro acceptance runs. Server run #8 built and published version 1.0.1 with all 13 assets, passed 39 engine, 18 updater and 10 publisher checks, and rendered the packaged Linux settings page under Debian Bookworm. A packaged Linux 1.0.0 app also discovered and downloaded the public 1.0.1 update through the real Gitea source with checksum validation.
References: Velopack C# integration, cross-packaging, Linux update behavior, Gitea distribution, Avalonia Linux dependencies.