Add GitHub Pages self-hosting guide

GITHUB_PAGES_HOSTING.md

@@ -0,0 +1,282 @@
+# Hosting OpenCode on GitHub Pages
+
+This guide explains how to host your own version of OpenCode on GitHub Pages, allowing you to work with your other repositories and customize the deployment to your needs.
+
+## Overview
+
+OpenCode is an AI-powered coding agent that can be self-hosted on various platforms, including GitHub Pages. This guide will walk you through setting up your own instance that integrates with your GitHub repositories.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- A GitHub account
+- Git installed on your local machine
+- Node.js 18+ or Bun 1.3+ installed
+- Basic knowledge of Git and GitHub workflows
+
+## Fork and Clone the Repository
+
+1. **Fork the OpenCode repository** to your GitHub account:
+   - Visit https://github.com/anomalyco/opencode
+   - Click the "Fork" button in the top-right corner
+   - Select your account as the destination
+
+2. **Clone your forked repository**:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/opencode.git
+   cd opencode
+   ```
+
+   > **Note**: The default branch for OpenCode is `dev`. Make sure you're working on the appropriate branch for your deployment.
+
+3. **Install dependencies**:
+   ```bash
+   bun install
+   # or if using npm
+   npm install
+   ```
+
+## Configure for GitHub Pages
+
+### Option 1: Deploy Documentation Site
+
+If you want to host the OpenCode documentation on GitHub Pages:
+
+1. **Navigate to the docs package**:
+   ```bash
+   cd packages/docs
+   ```
+
+2. **Build the documentation**:
+   ```bash
+   bun run build
+   # or
+   npm run build
+   ```
+
+3. **Create a GitHub Actions workflow** for automatic deployment:
+
+   Create `.github/workflows/gh-pages.yml` in your repository root:
+   ```yaml
+   name: Deploy to GitHub Pages
+
+   on:
+     push:
+       branches:
+         - dev  # or main, depending on your default branch
+     workflow_dispatch:
+
+   permissions:
+     contents: read
+     pages: write
+     id-token: write
+
+   concurrency:
+     group: "pages"
+     cancel-in-progress: false
+
+   jobs:
+     build:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v4
+
+         - name: Setup Bun
+           uses: oven-sh/setup-bun@v2
+           with:
+             bun-version: latest
+
+         - name: Install dependencies
+           run: bun install
+
+         - name: Build documentation
+           run: |
+             cd packages/docs
+             bun run build
+
+         - name: Upload artifact
+           uses: actions/upload-pages-artifact@v3
+           with:
+             path: './packages/docs/dist'
+
+     deploy:
+       environment:
+         name: github-pages
+         url: ${{ steps.deployment.outputs.page_url }}
+       runs-on: ubuntu-latest
+       needs: build
+       steps:
+         - name: Deploy to GitHub Pages
+           id: deployment
+           uses: actions/deploy-pages@v4
+   ```
+
+### Option 2: Deploy the Full Application
+
+If you want to host the entire OpenCode application:
+
+1. **Build the application**:
+   ```bash
+   bun run build
+   ```
+
+2. **Configure the base path** for GitHub Pages in your build configuration.
+
+   For the web package, update `packages/web/astro.config.mjs`:
+   ```javascript
+   export default defineConfig({
+     site: 'https://YOUR_USERNAME.github.io',
+     base: '/opencode',
+     // ... other config
+   });
+   ```
+
+3. **Use the GitHub Actions workflow** (similar to Option 1, but adjust the build path).
+
+## Enable GitHub Pages
+
+1. Go to your repository on GitHub
+2. Click on **Settings** → **Pages**
+3. Under **Source**, select:
+   - **Source**: GitHub Actions (recommended)
+   - Or if deploying manually: **Deploy from a branch** and select `gh-pages` branch
+
+## Configure Repository Access
+
+To allow your hosted OpenCode instance to work with your other repositories:
+
+1. **Generate a Personal Access Token (PAT)**:
+   - Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
+   - Click "Generate new token (classic)"
+   - Select scopes: `repo`, `workflow`, `read:org`
+   - Save the token securely
+
+2. **Add the token to your repository secrets**:
+   - Go to your forked repository Settings → Secrets and variables → Actions
+   - Click "New repository secret"
+   - Name: `GH_PAT` or `GITHUB_TOKEN`
+   - Value: Your personal access token
+
+3. **Configure OpenCode** to use your token in the environment configuration.
+
+## Custom Domain (Optional)
+
+To use a custom domain with your GitHub Pages deployment:
+
+1. Add a `CNAME` file to your build output with your domain name
+2. Configure DNS settings at your domain provider:
+   - Add a CNAME record pointing to `YOUR_USERNAME.github.io`
+3. Enable HTTPS in GitHub Pages settings
+
+## Environment Variables
+
+Create a `.env.local` file in your repository root with necessary configuration:
+
+```env
+# GitHub Configuration
+GITHUB_TOKEN=your_personal_access_token_here
+
+# Optional: API Keys for AI providers
+ANTHROPIC_API_KEY=your_anthropic_key
+OPENAI_API_KEY=your_openai_key
+
+# Optional: Custom configuration
+OPENCODE_BASE_URL=https://your-username.github.io/opencode
+```
+
+## Working with Multiple Repositories
+
+Once your OpenCode instance is deployed:
+
+1. **Clone your other repositories** locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/your-other-repo.git
+   cd your-other-repo
+   ```
+
+2. **Run OpenCode** against those repositories:
+   ```bash
+   opencode
+   # or if running from source
+   bun dev /path/to/your-other-repo
+   ```
+
+3. **Configure repository access** in OpenCode's settings to work across multiple repositories.
+
+## Updating Your Deployment
+
+To update your deployed version:
+
+1. **Sync with upstream** (optional, to get latest changes from the original repository):
+   ```bash
+   git remote add upstream https://github.com/anomalyco/opencode.git
+   git fetch upstream
+   git merge upstream/dev  # The default branch for OpenCode is 'dev'
+   ```
+
+2. **Make your changes** and commit:
+   ```bash
+   git add .
+   git commit -m "Update deployment configuration"
+   ```
+
+3. **Push to GitHub** (to your default branch):
+   ```bash
+   git push origin dev  # or 'main' if that's your default branch
+   ```
+
+   The GitHub Actions workflow will automatically build and deploy your changes.
+
+## Troubleshooting
+
+### Build Failures
+
+- **Issue**: Build fails with dependency errors
+  - **Solution**: Clear cache and reinstall: `rm -rf node_modules bun.lock && bun install`
+
+- **Issue**: GitHub Actions workflow fails
+  - **Solution**: Check the Actions tab for detailed logs and ensure all secrets are configured
+
+### Access Issues
+
+- **Issue**: Cannot access other repositories
+  - **Solution**: Verify your Personal Access Token has the correct scopes and hasn't expired
+
+- **Issue**: 404 errors on GitHub Pages
+  - **Solution**: Check that the base path in your configuration matches your repository name
+
+### Performance Issues
+
+- **Issue**: Slow loading or timeouts
+  - **Solution**: Consider using a different hosting platform (Vercel, Netlify) for better performance, or optimize build output
+
+## Alternative Hosting Options
+
+While GitHub Pages is convenient, you may also consider:
+
+- **Vercel**: Better performance and automatic deployments
+- **Netlify**: Similar to Vercel with additional features
+- **Cloudflare Pages**: Fast global CDN
+- **Self-hosted**: VPS or dedicated server for full control
+
+Each has its own advantages depending on your needs.
+
+## Security Considerations
+
+- Never commit sensitive tokens or API keys to your repository
+- Use GitHub Secrets for sensitive configuration
+- Regularly rotate your Personal Access Tokens
+- Review and limit repository access permissions
+- Enable branch protection rules on your main/dev branches
+
+## Getting Help
+
+- Check the [OpenCode documentation](https://opencode.ai/docs)
+- Visit the [GitHub repository](https://github.com/anomalyco/opencode)
+- Join the [Discord community](https://opencode.ai/discord)
+- Review [contributing guidelines](./CONTRIBUTING.md)
+
+## License
+
+OpenCode is released under the MIT License. See [LICENSE](./LICENSE) for details.

README.md

@@ -110,6 +110,10 @@ Learn more about [agents](https://opencode.ai/docs/agents).
 
 For more info on how to configure OpenCode, [**head over to our docs**](https://opencode.ai/docs).
 
+### Self-Hosting
+
+Want to host your own version of OpenCode on GitHub Pages? Check out our [**GitHub Pages hosting guide**](./GITHUB_PAGES_HOSTING.md) for detailed instructions on setting up your own instance.
+
 ### Contributing
 
 If you're interested in contributing to OpenCode, please read our [contributing docs](./CONTRIBUTING.md) before submitting a pull request.