@smbcloud / pepakbasajawa-web
Code Commits Issues Pulls Cloud Agent CI/CD
main
copilot/add-i18n-support-for-english dependabot/npm_and_yarn/astro-5.16.4 dependabot/npm_and_yarn/katex-0.16.27 dependabot/npm_and_yarn/prettier-3.7.4 dependabot/npm_and_yarn/tailwindcss-4.1.16 dependabot/npm_and_yarn/tailwindcss/vite-4.1.16 dependabot/npm_and_yarn/typescript-eslint-8.46.2 dependabot/npm_and_yarn/typescript-eslint/parser-8.46.2 development main
md 238 lines 6.59 KB
Rendered Raw
1 # Desktop Downloads Setup Guide
2
3 This guide explains how to set up the desktop app downloads feature that fetches releases from your private GitHub repository.
4
5 ## Overview
6
7 The system consists of:
8 1. **API Endpoint** (`/api/download-desktop-app`) - Fetches releases from GitHub and proxies downloads
9 2. **Download Page** (`/download`) - Displays available downloads with platform-specific information
10
11 ## Prerequisites
12
13 ### 1. GitHub Personal Access Token
14
15 You need a GitHub Personal Access Token (PAT) with access to your private repository.
16
17 #### Creating a GitHub Token:
18
19 1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
20 2. Click "Generate new token (classic)"
21 3. Give it a descriptive name like "PepakBasaJawa Downloads"
22 4. Set expiration (recommend: No expiration for production, or use fine-grained tokens with auto-renewal)
23 5. Select the following scopes:
24 - `repo` (Full control of private repositories)
25 6. Click "Generate token"
26 7. **Copy the token immediately** (you won't be able to see it again)
27
28 #### Alternative: Fine-Grained Personal Access Token (Recommended)
29
30 1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
31 2. Click "Generate new token"
32 3. Configure:
33 - **Token name**: "PepakBasaJawa Downloads"
34 - **Expiration**: Custom (1 year recommended)
35 - **Repository access**: Only select repositories → `setoelkahfi/pepakbasajawa`
36 - **Permissions**:
37 - Repository permissions → Contents: Read-only
38 - Repository permissions → Metadata: Read-only (automatically included)
39 4. Click "Generate token"
40 5. Copy the token
41
42 ### 2. Environment Variables
43
44 Add the GitHub token to your environment variables:
45
46 **For local development (`.env`):**
47 ```env
48 GITHUB_TOKEN=ghp_your_token_here
49 ```
50
51 **For production (Vercel/Netlify/etc):**
52 Add the environment variable in your hosting platform's dashboard:
53 - Variable name: `GITHUB_TOKEN`
54 - Value: Your GitHub token
55
56 ## How It Works
57
58 ### 1. Fetching Releases
59
60 The API endpoint (`/api/download-desktop-app`) calls the GitHub API:
61
62 ```
63 GET https://api.github.com/repos/setoelkahfi/pepakbasajawa/releases/latest
64 ```
65
66 This requires authentication using the `GITHUB_TOKEN`.
67
68 ### 2. Asset Detection
69
70 The system automatically detects platform and architecture based on filename patterns:
71
72 **macOS:**
73 - Filenames containing: `mac`, `darwin`, or ending with `.dmg`
74 - **Apple Silicon**: `arm64`, `aarch64`, `apple`
75 - **Intel**: `x64`, `intel`, `x86_64`
76 - **Universal**: No architecture specified
77
78 **Windows:**
79 - Filenames containing: `win` or ending with `.exe`, `.msi`
80 - **x64**: `x64`, `x86_64`
81 - **ARM64**: `arm64`
82
83 **Linux:**
84 - Filenames containing: `linux` or ending with `.appimage`, `.deb`, `.rpm`, `.tar.gz`
85 - **x64**: `x64`, `x86_64`
86 - **ARM64**: `arm64`, `aarch64`
87
88 ### 3. Secure Downloads
89
90 Downloads are proxied through the API to keep your GitHub token secure:
91
92 ```
93 User clicks download → /api/download-desktop-app?action=download&assetId=123
94 → API authenticates with GitHub → GitHub provides temporary redirect URL
95 → User downloads file
96 ```
97
98 This approach (inspired by the [Practical Bazel blog post](https://www.stevenengelhardt.com/2023/05/23/practical-bazel-downloading-private-release-assets-from-github/)) ensures:
99 - GitHub token is never exposed to the client
100 - Downloads work without requiring users to authenticate
101 - Assets remain private on GitHub
102
103 ## Release Naming Convention
104
105 For best results, use consistent naming for your release assets:
106
107 ### Recommended Format:
108 ```
109 pepakbasajawa-{version}-{platform}-{arch}.{ext}
110 ```
111
112 ### Examples:
113 - `pepakbasajawa-1.0.0-macos-arm64.dmg` (macOS Apple Silicon)
114 - `pepakbasajawa-1.0.0-macos-x64.dmg` (macOS Intel)
115 - `pepakbasajawa-1.0.0-windows-x64.exe` (Windows)
116 - `pepakbasajawa-1.0.0-linux-x64.AppImage` (Linux)
117 - `pepakbasajawa-1.0.0-linux-x64.deb` (Linux Debian)
118
119 ## Testing
120
121 ### Local Testing:
122
123 1. Set up environment variable:
124 ```bash
125 echo "GITHUB_TOKEN=your_token_here" >> .env
126 ```
127
128 2. Start the dev server:
129 ```bash
130 npm run dev
131 ```
132
133 3. Visit: `http://localhost:4321/download`
134
135 4. Test the API directly:
136 ```bash
137 curl http://localhost:4321/api/download-desktop-app
138 ```
139
140 ### Testing with GitHub:
141
142 1. Create a test release in your repository
143 2. Upload test assets with appropriate names
144 3. Verify they appear on the download page
145 4. Test downloading each asset
146
147 ## Troubleshooting
148
149 ### Error: "GITHUB_TOKEN is not configured"
150 - Ensure the environment variable is set correctly
151 - Restart your dev server after adding the token
152 - Check your hosting platform's environment variables in production
153
154 ### Error: "Failed to fetch releases"
155 - Verify your GitHub token has the correct permissions
156 - Check if the token has expired
157 - Ensure the repository name is correct in the code
158
159 ### Downloads not appearing:
160 - Check if release assets follow the naming conventions
161 - Verify the release is marked as "latest" on GitHub
162 - Check browser console for API errors
163
164 ### Download links not working:
165 - Ensure the asset ID is being passed correctly
166 - Verify GitHub token has access to download assets
167 - Check API logs for authentication errors
168
169 ## Security Best Practices
170
171 1. **Never commit tokens**: Add `.env` to `.gitignore`
172 2. **Use fine-grained tokens**: Limit scope to only what's needed
173 3. **Rotate tokens regularly**: Update tokens every 6-12 months
174 4. **Monitor token usage**: Check GitHub's token usage logs
175 5. **Use environment variables**: Never hardcode tokens
176
177 ## Caching
178
179 The API response is cached for 5 minutes to reduce GitHub API calls:
180
181 ```typescript
182 'Cache-Control': 'public, max-age=300'
183 ```
184
185 Adjust this value in `/src/pages/api/download-desktop-app.ts` if needed.
186
187 ## GitHub API Rate Limits
188
189 - **Authenticated requests**: 5,000 per hour
190 - **Unauthenticated requests**: 60 per hour
191
192 With caching enabled, this should be sufficient for most traffic levels.
193
194 ## CI/CD Integration
195
196 ### Automated Releases
197
198 You can automate releases using GitHub Actions:
199
200 ```yaml
201 name: Release Desktop App
202
203 on:
204 push:
205 tags:
206 - 'v*'
207
208 jobs:
209 release:
210 runs-on: ubuntu-latest
211 steps:
212 - uses: actions/checkout@v3
213
214 - name: Build Desktop Apps
215 run: |
216 # Your build commands here
217
218 - name: Create Release
219 uses: softprops/action-gh-release@v1
220 with:
221 files: |
222 dist/*.dmg
223 dist/*.exe
224 dist/*.AppImage
225 dist/*.deb
226 env:
227 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
228 ```
229
230 ## Support
231
232 For questions or issues:
233 - Email: info@pepakbasajawa.com
234 - Repository: https://github.com/setoelkahfi/pepakbasajawa
235
236 ## License
237
238 This implementation is part of the PepakBasaJawa project.