Skip to content

Commit 23f30f5

Browse files
coroacoroa
committed
feat: add windows installer
1 parent 3ef767c commit 23f30f5

6 files changed

Lines changed: 833 additions & 0 deletions

File tree

‎.github/workflows/build-installer.yaml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
name: Build Windows Installer
2+
3+
on:
4+
push:
5+
branches:
6+
- '**'
7+
pull_request:
8+
workflow_dispatch:
9+
10+
jobs:
11+
build-windows-installer:
12+
name: Build Windows Installer
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v6
16+
17+
- name: Setup Pixi
18+
uses: prefix-dev/setup-pixi@v0.9.3
19+
with:
20+
pixi-version: v0.59.0
21+
cache: true
22+
cache-write: false
23+
24+
- name: Download pixi executable for Windows
25+
run: |
26+
cd utils/windows-installer
27+
curl -L https://github.com/prefix-dev/pixi/releases/latest/download/pixi-x86_64-pc-windows-msvc.exe -o pixi.exe
28+
29+
- name: Get version from git
30+
id: get_version
31+
run: |
32+
# Try to get version from git tag, fallback to commit hash
33+
VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo "0.0.0-dev")
34+
# Remove 'v' prefix if present
35+
VERSION=${VERSION#v}
36+
echo "version=$VERSION" >> $GITHUB_OUTPUT
37+
echo "Building installer version: $VERSION"
38+
39+
- name: Build Windows installer
40+
run: |
41+
cd utils/windows-installer
42+
pixi exec --spec nsis makensis -DPRODUCT_VERSION=${{ steps.get_version.outputs.version }} pixi_installer.nsi
43+
ls -lh open-tyndp-*.exe
44+
45+
- name: Generate checksum
46+
run: |
47+
cd utils/windows-installer
48+
sha256sum open-tyndp-*.exe > checksums.txt
49+
cat checksums.txt
50+
51+
- name: Upload installer artifact
52+
uses: actions/upload-artifact@v4
53+
with:
54+
name: windows-installer
55+
path: |
56+
utils/windows-installer/open-tyndp-*.exe
57+
utils/windows-installer/checksums.txt
58+
59+
- name: Comment on PR
60+
if: github.event_name == 'pull_request'
61+
uses: actions/github-script@v7
62+
with:
63+
script: |
64+
const fs = require('fs');
65+
const checksums = fs.readFileSync('utils/windows-installer/checksums.txt', 'utf8');
66+
67+
github.rest.issues.createComment({
68+
issue_number: context.issue.number,
69+
owner: context.repo.owner,
70+
repo: context.repo.repo,
71+
body: `## 🪟 Windows Installer Built Successfully
72+
73+
The Windows installer has been built and is available as an artifact in this workflow run.
74+
75+
**Download:** [windows-installer](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})
76+
77+
**SHA256 Checksums:**
78+
\`\`\`
79+
${checksums}
80+
\`\`\`
81+
82+
The installer includes:
83+
- Pixi executable (~20 MB)
84+
- Automatic repository cloning
85+
- Environment installation on-demand
86+
- PowerShell and CMD shortcuts
87+
- Official Open Energy Transition branding`
88+
})

‎REUSE.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,3 +50,10 @@ path = [
5050
]
5151
SPDX-FileCopyrightText = "Open Energy Transition gGmbH"
5252
SPDX-License-Identifier = "MIT"
53+
54+
[[annotations]]
55+
path = [
56+
"utils/windows-installer/oet_logo.*",
57+
]
58+
SPDX-FileCopyrightText = "Open Energy Transition gGmbH"
59+
SPDX-License-Identifier = "CC-BY-4.0"

‎utils/windows-installer/README.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
<!--
2+
SPDX-FileCopyrightText: Contributors to Open-TYNDP <https://github.com/open-energy-transition/open-tyndp>
3+
SPDX-License-Identifier: CC-BY-4.0
4+
-->
5+
6+
# Windows Installer for Open-TYNDP
7+
8+
Guide for building and using the Windows installer based on pixi and NSIS.
9+
10+
**Table of Contents:**
11+
- [Quick Start](#quick-start) - Get building quickly
12+
- [Overview](#overview) - Understanding the approach
13+
- [Building](#building-the-installer) - Detailed build instructions
14+
- [Using](#using-the-installed-environment) - For end users
15+
- [Customization](#customization) - Modify the installer
16+
- [Troubleshooting](#troubleshooting) - Common issues and solutions
17+
- [Advanced](#advanced-topics) - Cross-platform builds, automation, CI/CD
18+
19+
---
20+
21+
## Quick Start
22+
23+
**Automated Build (Recommended):**
24+
25+
The Windows installer is built automatically on every GitHub release. Simply create a new release tag and the installer will be attached as a release asset.
26+
27+
**Manual Build:**
28+
29+
```bash
30+
# Navigate to installer directory
31+
cd utils/windows-installer
32+
33+
# Run the build script
34+
./build_pixi_installer.sh # Linux/macOS/Git Bash
35+
36+
# Output: open-tyndp-0.4.0-pixi-Windows-x86_64.exe (~20 MB)
37+
```
38+
39+
**File structure:**
40+
```
41+
utils/windows-installer/
42+
├── build_pixi_installer.sh
43+
├── pixi_installer.nsi
44+
├── oet_logo.bmp
45+
└── oet_logo.ico
46+
```
47+
48+
---
49+
50+
## Overview
51+
52+
### What This Approach Does
53+
54+
Combines three technologies:
55+
1. **pixi executable** - Bundled package manager (~20 MB)
56+
2. **NSIS** - Creates Windows installer executable
57+
3. **Git integration** - Automatically clones repository during installation
58+
59+
### Key Features
60+
61+
✅ **Small installer** - Only ~20 MB download (pixi executable only)
62+
✅ **On-demand environment** - Downloads packages from conda-forge during installation
63+
✅ **Integrated Git cloning** - One-click setup with custom directory selection
64+
✅ **Cross-platform builds** - Build Windows installers from Linux/macOS
65+
✅ **Direct shortcuts** - PowerShell and CMD shortcuts with embedded commands
66+
✅ **No admin required** - User-level installation
67+
✅ **Official branding** - Open Energy Transition logos and colors
68+
69+
### How It Works
70+
71+
1. **Installation**: Copies pixi.exe to `%LOCALAPPDATA%\open-tyndp`
72+
2. **Repository Setup**: Clones repository using bundled pixi (via `pixi exec git`)
73+
3. **Environment Installation**: Runs `pixi install` to download and set up conda environment
74+
4. **Shortcuts**: Creates Start Menu shortcuts that activate environment via `pixi shell`
75+
76+
### Environment Activation
77+
78+
The shortcuts use `pixi shell` to activate the environment:
79+
- **PowerShell**: `pixi shell -e open-tyndp` launches PowerShell in activated environment
80+
- **CMD**: `pixi shell -e open-tyndp` launches CMD in activated environment
81+
- **No PATH modification** - Environment only active in launched shell
82+
- **No base environment** - Only the project environment is installed
83+
84+
---
85+
86+
## Building the Installer
87+
88+
### Automated Build
89+
90+
The installer is built automatically by GitHub Actions:
91+
- **On every push/PR**: Workflow builds installer and uploads as artifact
92+
- **On release tags**: Workflow builds installer and attaches to GitHub Release
93+
94+
### Using the Build Script
95+
96+
```bash
97+
cd utils/windows-installer
98+
./build_pixi_installer.sh # Linux/macOS/Git Bash
99+
```
100+
101+
The script automatically downloads pixi.exe if needed and builds the installer.
102+
103+
---
104+
105+
## How the Installer Works
106+
107+
### Installation Wizard Flow
108+
109+
1. **Welcome Page** - Introduction and license acceptance
110+
2. **Repository Setup Page**
111+
- Checkbox to enable/disable auto-clone
112+
- Directory picker for repository location (default: `%USERPROFILE%\open-tyndp`)
113+
- Browse button for custom location
114+
- Validation of existing directories
115+
- Shows where pixi.exe will be installed
116+
3. **Installation** - Progress bar showing:
117+
- Installing pixi executable
118+
- Cloning repository using `pixi exec git` (~1-2 minutes if enabled)
119+
- Installing environment using `pixi install` (~5-15 minutes, ~500-800 MB download)
120+
4. **Finish** - Summary with next steps
121+
122+
### What Gets Installed
123+
124+
**Pixi executable** (`%LOCALAPPDATA%\open-tyndp`):
125+
```
126+
open-tyndp/
127+
├── pixi.exe # Pixi package manager (~20 MB)
128+
└── Uninstall.exe # Uninstaller
129+
```
130+
131+
**Repository files** (`%USERPROFILE%\open-tyndp` - if cloned):
132+
```
133+
open-tyndp/
134+
├── .git/
135+
├── .pixi/
136+
│ └── envs/
137+
│ └── open-tyndp/ # Conda environment installed by pixi
138+
├── workflow/
139+
├── config/
140+
├── pixi.toml
141+
├── pixi.lock
142+
└── ... (project files)
143+
```
144+
145+
**Start Menu shortcuts** (`%APPDATA%\Microsoft\Windows\Start Menu\Programs\Open-TYNDP`):
146+
- Open-TYNDP PowerShell.lnk
147+
- Open-TYNDP Command Prompt.lnk
148+
- Uninstall Open-TYNDP.lnk
149+
150+
**Registry entries**:
151+
- `HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\Open-TYNDP` - For Add/Remove Programs
152+
- `HKCU\Software\Open-TYNDP\RepositoryPath` - Stores repository location
153+
154+
155+
---
156+
157+
## Using the Installed Environment
158+
159+
### For End Users
160+
161+
#### Installation
162+
163+
1. **Run the installer**
164+
- Double-click `open-tyndp-0.4.0-Windows-x86_64.exe`
165+
- Accept UAC prompt if needed
166+
167+
2. **Follow the wizard**
168+
- Click "Next" through Welcome and License
169+
- Choose environment location (or keep default)
170+
- **On Repository Setup page:**
171+
- ✅ Keep "Clone repository automatically" checked
172+
- Choose location or browse (default: `C:\Users\YourName\open-tyndp`)
173+
- Click "Next"
174+
- Wait for installation (3-5 minutes total)
175+
176+
3. **Start working**
177+
- Open Start Menu → "Open-TYNDP" → "Open-TYNDP PowerShell"
178+
- PowerShell opens in repository directory with environment activated
179+
- Run: `snakemake --help` to verify
180+
- Everything is ready!
181+
182+
183+
### Uninstalling
184+
185+
**Via Add/Remove Programs:**
186+
1. Open Settings → Apps → Installed apps
187+
2. Find "Open-TYNDP"
188+
3. Click "Uninstall"
189+
4. **Important prompt:** "Remove repository directory?"
190+
- **Yes** - Deletes everything (environment + repository + your work!)
191+
- **No** - Keeps repository and your files, removes only environment
192+
193+
**Via Start Menu:**
194+
- Start Menu → Open-TYNDP → Uninstall
195+
196+
---
197+
198+
## Troubleshooting
199+
200+
201+
### Debugging Installation Issues
202+
203+
Enable NSIS logging (edit `.nsi`):
204+
205+
```nsis
206+
# At top of file
207+
!define ENABLE_LOGGING
208+
209+
# Installer will create install.log in installation directory
210+
# View with: notepad %LOCALAPPDATA%\open-tyndp\install.log
211+
```
212+
213+
---
214+
215+
## References and Resources
216+
217+
### Documentation
218+
- [NSIS Documentation](https://nsis.sourceforge.io/Docs/) - Complete NSIS reference
219+
- [NSIS Modern UI](https://nsis.sourceforge.io/Docs/Modern%20UI%202/Readme.html) - UI customization
220+
221+
### Examples and Templates
222+
- [Conda Constructor NSIS Template](https://github.com/conda/constructor/blob/main/constructor/nsis/main.nsi.tmpl) - Reference implementation
223+
224+
### Tools
225+
- [NSIS Download](https://nsis.sourceforge.io/Download) - Windows installer creator
226+
227+
### Support
228+
- Project issues: https://github.com/open-energy-transition/open-tyndp/issues
229+
- NSIS forums: https://forums.winamp.com/forum/151-nsis-discussion/

‎utils/windows-installer/oet_logo.bmp‎

151 KB
Binary file not shown.

‎utils/windows-installer/oet_logo.ico‎

108 KB
Binary file not shown.

0 commit comments

Comments
 (0)