8.4 KiB
Installing and releasing AstroFrame
First release
Version 1.0.0 targets x64 Windows and Linux desktops. 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
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.
Build release packages
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.0
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. The initial release has not been uploaded by this implementation. To make update discovery live, create a public stable release tagged v1.0.0 and attach the files described below.
The helper script reads a Gitea repository-write token from ASTROFRAME_RELEASE_TOKEN in the process environment. It 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. If a partial upload fails, delete the incomplete draft and retry, or attach the remaining files manually. 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: change the version, validate, build, push the corresponding source, and publish a new stable tagged release with both channels. Existing installations then receive the notification and can update without reinstalling.
Verification
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. The public repository API was verified anonymously; it currently contains no published releases.
References: Velopack C# integration, cross-packaging, Linux update behavior, Gitea distribution, Avalonia Linux dependencies.