@smbcloud / pepakbasajawa-web
Code Commits Issues Pulls Cloud Agent CI/CD
dependabot/npm_and_yarn/astro-5.16.4
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 197 lines 4.48 KB
Rendered Raw
1 # Quick Start: Desktop Downloads Feature
2
3 Get the desktop downloads feature running in 5 minutes.
4
5 ## 1. Get Your GitHub Token
6
7 ```bash
8 # Go to: https://github.com/settings/tokens
9 # Click "Generate new token (classic)"
10 # Select scope: "repo" (for private repos)
11 # Copy the token
12 ```
13
14 ## 2. Add Token to Environment
15
16 ```bash
17 # Create .env file in project root
18 echo "GITHUB_TOKEN=ghp_your_actual_token_here" > .env
19 ```
20
21 ## 3. Test Locally
22
23 ```bash
24 # Install dependencies (if needed)
25 npm install
26
27 # Start dev server
28 npm run dev
29
30 # Visit in browser
31 open http://localhost:4321/download
32 ```
33
34 ## 4. Deploy to Production
35
36 ### Vercel
37 ```bash
38 # Add environment variable
39 vercel env add GITHUB_TOKEN
40 # Paste your token when prompted
41
42 # Deploy
43 vercel --prod
44 ```
45
46 ### Netlify
47 ```bash
48 # Add environment variable in Netlify dashboard:
49 # Site settings → Environment variables → Add variable
50 # Key: GITHUB_TOKEN
51 # Value: your_token
52
53 # Deploy
54 netlify deploy --prod
55 ```
56
57 ### Other Platforms
58 Add `GITHUB_TOKEN` environment variable in your platform's dashboard.
59
60 ## 5. Upload Release to GitHub
61
62 Your release assets should follow this naming pattern:
63
64 ```
65 ✅ pepakbasajawa-1.0.0-macos-arm64.dmg
66 ✅ pepakbasajawa-1.0.0-macos-x64.dmg
67 ✅ pepakbasajawa-1.0.0-windows-x64.exe
68 ✅ pepakbasajawa-1.0.0-linux-x64.AppImage
69 ```
70
71 Steps:
72 1. Go to: https://github.com/setoelkahfi/pepakbasajawa/releases
73 2. Click "Draft a new release"
74 3. Create a tag (e.g., `v1.0.0`)
75 4. Upload your built app files
76 5. Click "Publish release"
77
78 ## How It Works
79
80 ```
81 ┌─────────────┐
82 │ Browser │
83 │ (User) │
84 └─────┬───────┘
85 │ 1. Visit /download
86 ▼
87 ┌─────────────────┐
88 │ Download Page │
89 │ (Astro) │
90 └─────┬───────────┘
91 │ 2. Fetch releases
92 ▼
93 ┌──────────────────────┐
94 │ API Endpoint │
95 │ /api/download-... │
96 └─────┬────────────────┘
97 │ 3. Authenticate with GitHub
98 ▼
99 ┌──────────────────┐
100 │ GitHub API │
101 │ (Private Repo) │
102 └─────┬────────────┘
103 │ 4. Return releases
104 ▼
105 ┌─────────────┐
106 │ Browser │
107 │ (Shows │
108 │ links) │
109 └─────────────┘
110 ```
111
112 When user clicks download:
113 ```
114 User → API (with asset ID) → GitHub → Temporary URL → User downloads
115 ```
116
117 ## Troubleshooting
118
119 **Problem**: "GITHUB_TOKEN is not configured"
120 ```bash
121 # Solution: Check your .env file exists and contains the token
122 cat .env | grep GITHUB_TOKEN
123
124 # Restart dev server
125 npm run dev
126 ```
127
128 **Problem**: "Failed to fetch releases"
129 ```bash
130 # Solution 1: Verify token permissions
131 # Go to: https://github.com/settings/tokens
132 # Make sure token has "repo" scope
133
134 # Solution 2: Check token hasn't expired
135 # Generate a new token if needed
136
137 # Solution 3: Verify repository name in code
138 # Check: src/pages/api/download-desktop-app.ts
139 # Line with: const GITHUB_REPO = 'setoelkahfi/pepakbasajawa'
140 ```
141
142 **Problem**: No downloads showing
143 ```bash
144 # Solution: Check release exists and has assets
145 # Visit: https://github.com/setoelkahfi/pepakbasajawa/releases
146
147 # Make sure:
148 # 1. At least one release is marked as "latest"
149 # 2. Release has uploaded asset files
150 # 3. Asset filenames match patterns (mac/win/linux)
151 ```
152
153 ## API Endpoints
154
155 ### Get Releases
156 ```bash
157 curl http://localhost:4321/api/download-desktop-app
158 ```
159
160 Response:
161 ```json
162 {
163 "version": "v1.0.0",
164 "name": "Release 1.0.0",
165 "published_at": "2024-01-15T10:00:00Z",
166 "downloads": [
167 {
168 "platform": "macOS",
169 "architecture": "Apple Silicon",
170 "url": "/api/download-desktop-app?action=download&assetId=12345",
171 "filename": "pepakbasajawa-1.0.0-macos-arm64.dmg",
172 "size": 125829120,
173 "version": "v1.0.0"
174 }
175 ]
176 }
177 ```
178
179 ### Download Asset
180 ```bash
181 curl -L "http://localhost:4321/api/download-desktop-app?action=download&assetId=12345" \
182 -o app.dmg
183 ```
184
185 ## Security Checklist
186
187 - [ ] `.env` file is in `.gitignore`
188 - [ ] GitHub token is not committed to repository
189 - [ ] Token has minimum required permissions (repo scope only)
190 - [ ] Production environment variable is set
191 - [ ] Token is rotated periodically (every 6-12 months)
192
193 ## Need More Help?
194
195 See detailed documentation: [DESKTOP_DOWNLOADS_SETUP.md](./DESKTOP_DOWNLOADS_SETUP.md)
196
197 Email: info@pepakbasajawa.com