107 lines
8.4 KiB
Markdown
107 lines
8.4 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|
|
|
|
```powershell
|
|
./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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```powershell
|
|
./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.nupkg` and any generated delta package;
|
|
- `releases.<channel>.json`, `RELEASES-<channel>` and `assets.<channel>.json`;
|
|
- the Windows Setup executable and Linux AppImage;
|
|
- `install-linux.sh` and `astroframe.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:
|
|
|
|
```powershell
|
|
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](https://docs.velopack.io/getting-started/csharp), [cross-packaging](https://docs.velopack.io/packaging/cross-compiling), [Linux update behavior](https://docs.velopack.io/packaging/operating-systems/linux), [Gitea distribution](https://docs.velopack.io/distributing/self-hosting), [Avalonia Linux dependencies](https://v11.docs.avaloniaui.net/docs/overview/supported-platforms/).
|