Initial commit

2025-11-29 18:50:06 +08:00
commit 5e3ca965d9
68 changed files with 11257 additions and 0 deletions
--- a/commands/deploy-github.md
+++ b/commands/deploy-github.md
@@ -0,0 +1,182 @@
+Deploy your Odoo PWA to GitHub Pages with GitHub Actions for continuous deployment.
+
+## What this command does:
+- Sets up GitHub Actions workflow for automated deployment
+- Configures GitHub Pages in repository settings
+- Sets up repository secrets for environment variables
+- Deploys the application to GitHub Pages
+- Provides custom domain setup instructions
+
+## Prerequisites:
+Before deploying, verify:
+1. ✅ Project builds successfully locally (`npm run build`)
+2. ✅ Git repository exists and is pushed to GitHub
+3. ✅ User has admin access to the repository
+4. ✅ GitHub Pages is enabled in repository settings
+5. ✅ Base URL configuration is correct for GitHub Pages
+
+## Important: GitHub Pages Limitations
+⚠️ Note: GitHub Pages is static hosting only. Server-side API routes won't work.
+
+**Recommendation**: For full Odoo PWA functionality with server-side API proxy:
+- Use Vercel, Cloudflare Pages, or Netlify instead
+- Or deploy API routes separately (e.g., Vercel Serverless Functions)
+
+## If Continuing with GitHub Pages:
+You'll need to modify the Odoo client to use CORS-enabled direct Odoo API calls or deploy API routes separately.
+
+## Steps:
+
+### 1. Configure GitHub Repository
+```bash
+# Ensure you're on main branch
+git checkout main
+git pull origin main
+```
+
+### 2. Set Up GitHub Actions Workflow
+Check if `.github/workflows/deploy.yml` exists:
+- If yes: Review and update if needed
+- If no: Create the workflow file
+
+### 3. Configure Repository Secrets
+Go to: Repository → Settings → Secrets and variables → Actions
+
+Add these secrets:
+```
+ODOO_API_KEY=your_production_api_key
+ODOO_USERNAME=your.email@company.com
+VITE_ODOO_URL=https://yourcompany.odoo.com
+VITE_ODOO_DB=yourcompany-main
+VITE_MODEL_NAME=x_expense
+VITE_MODEL_DISPLAY_NAME=Expense
+```
+
+### 4. Enable GitHub Pages
+Repository → Settings → Pages:
+- Source: Deploy from a branch
+- Branch: `gh-pages` (will be created by Actions)
+- Folder: `/ (root)`
+
+### 5. Update Base Path
+For framework-specific configuration:
+
+**SvelteKit** (`svelte.config.js`):
+```javascript
+paths: {
+  base: process.env.NODE_ENV === 'production' ? '/your-repo-name' : ''
+}
+```
+
+**React/Vue** (`vite.config.js`):
+```javascript
+base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/'
+```
+
+### 6. Commit and Push
+```bash
+git add .
+git commit -m "Configure GitHub Pages deployment"
+git push origin main
+```
+
+### 7. Monitor Deployment
+- Go to Actions tab in GitHub
+- Watch the deployment workflow
+- Check for any errors
+
+## GitHub Actions Workflow
+The workflow should:
+1. Trigger on push to `main` branch
+2. Install dependencies
+3. Build the project with environment variables
+4. Deploy to `gh-pages` branch
+5. GitHub Pages automatically serves from `gh-pages`
+
+## Example Workflow (.github/workflows/deploy.yml):
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install
+      - run: npm run build
+        env:
+          VITE_ODOO_URL: ${{ secrets.VITE_ODOO_URL }}
+          VITE_ODOO_DB: ${{ secrets.VITE_ODOO_DB }}
+          VITE_MODEL_NAME: ${{ secrets.VITE_MODEL_NAME }}
+          VITE_MODEL_DISPLAY_NAME: ${{ secrets.VITE_MODEL_DISPLAY_NAME }}
+      - uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build
+```
+
+## Custom Domain Setup (Optional):
+1. Add `CNAME` file to `static` folder with your domain
+2. Configure DNS records:
+   - A record: Points to GitHub Pages IPs
+   - Or CNAME: Points to `username.github.io`
+3. Enable HTTPS in repository settings (automatic)
+
+## Post-Deployment Checks:
+After deployment, verify:
+1. ✅ Application loads at `https://username.github.io/repo-name`
+2. ✅ All assets load correctly (check browser console)
+3. ✅ Base path is correct for all routes
+4. ✅ Odoo connection works (may need CORS configuration)
+5. ✅ PWA installs correctly
+
+## Example prompts to use this command:
+- `/deploy-github` - Interactive GitHub Pages deployment
+- User: "Deploy to GitHub Pages"
+- User: "Set up GitHub Actions for my PWA"
+
+## Troubleshooting:
+
+### Build Fails in Actions
+- Check Actions logs for specific error
+- Verify all secrets are set correctly
+- Ensure Node version is compatible
+- Test build locally first
+
+### 404 on GitHub Pages
+- Verify `gh-pages` branch exists
+- Check GitHub Pages settings
+- Ensure base path is configured
+- Wait a few minutes for DNS propagation
+
+### Assets Not Loading
+- Check base path configuration
+- Verify all asset paths are relative
+- Look for CORS issues in console
+- Ensure service worker paths are correct
+
+### API Routes Don't Work
+- GitHub Pages doesn't support server-side code
+- Deploy API routes to Vercel/Netlify separately
+- Or modify Odoo client for direct API calls with CORS
+
+## After Deployment:
+Provide the user with:
+1. GitHub Pages URL
+2. Link to Actions tab for monitoring
+3. Instructions for custom domain setup
+4. Reminder about server-side limitations
+5. Alternative hosting recommendations if needed