Skip to content

Commit 1cf7d1e

Browse files
waynesuttonwaynesutton
committed
Add one-click deploy buttons for Vercel and Netlify with setup banner
1 parent f00064e commit 1cf7d1e

9 files changed

Lines changed: 288 additions & 5 deletions

File tree

‎ONE-CLICK-DEPLOY.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# One-Click Deploy Checklist
2+
3+
You clicked a deploy button and now have the OpenSync frontend running on Vercel or Netlify. The frontend is deployed, but the app won't work until you complete the backend setup.
4+
5+
## What one-click deploy does
6+
7+
- Forks the OpenSync repository to your GitHub account
8+
- Deploys the React frontend to Vercel or Netlify
9+
- Prompts you for environment variables (which you may not have yet)
10+
11+
## What one-click deploy does NOT do
12+
13+
- Set up the Convex backend (database and functions)
14+
- Create your WorkOS authentication account
15+
- Configure OAuth redirect URIs
16+
- Set up OpenAI for embeddings
17+
18+
## Post-deploy checklist
19+
20+
Complete these steps to get OpenSync fully working:
21+
22+
### 1. Set up Convex backend
23+
24+
```bash
25+
# Clone your forked repo locally
26+
git clone https://github.com/YOUR_USERNAME/opensync.git
27+
cd opensync
28+
npm install
29+
30+
# Initialize Convex (creates a new project)
31+
npx convex dev
32+
```
33+
34+
This will:
35+
- Prompt you to log in to Convex (create account if needed)
36+
- Create a new Convex project
37+
- Deploy the schema and functions
38+
- Give you a deployment URL like `https://happy-animal-123.convex.cloud`
39+
40+
Keep this terminal running during development.
41+
42+
- [ ] Convex project created
43+
- [ ] Note your Convex URL: `https://____________.convex.cloud`
44+
45+
### 2. Set up WorkOS authentication
46+
47+
1. Go to [dashboard.workos.com](https://dashboard.workos.com) and create a project
48+
2. Enable **Email + Password** authentication in Authentication section
49+
3. Add redirect URIs in the Redirects section:
50+
51+
```
52+
https://your-deployed-url.vercel.app/callback
53+
https://your-deployed-url.netlify.app/callback
54+
```
55+
56+
Replace with your actual deployed URL from Vercel or Netlify.
57+
58+
4. Copy your **Client ID** (`client_xxxxx`) from API Keys
59+
60+
- [ ] WorkOS project created
61+
- [ ] Email + Password auth enabled
62+
- [ ] Redirect URI added for your deployed URL
63+
- [ ] Note your Client ID: `client_____________`
64+
65+
### 3. Set up OpenAI (for semantic search)
66+
67+
1. Go to [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
68+
2. Create a new API key
69+
3. Copy it (you won't see it again)
70+
71+
- [ ] OpenAI API key created
72+
- [ ] Note your API key: `sk-____________`
73+
74+
### 4. Set Convex environment variables
75+
76+
In the [Convex dashboard](https://dashboard.convex.dev):
77+
78+
1. Select your project
79+
2. Go to **Settings** > **Environment Variables**
80+
3. Add these variables:
81+
82+
| Name | Value |
83+
|------|-------|
84+
| `WORKOS_CLIENT_ID` | `client_xxxxx` (from step 2) |
85+
| `OPENAI_API_KEY` | `sk-xxxxx` (from step 3) |
86+
87+
- [ ] WORKOS_CLIENT_ID set in Convex
88+
- [ ] OPENAI_API_KEY set in Convex
89+
90+
### 5. Deploy Convex backend
91+
92+
```bash
93+
npx convex deploy
94+
```
95+
96+
This deploys your backend to production.
97+
98+
- [ ] Convex backend deployed
99+
100+
### 6. Update frontend environment variables
101+
102+
In your Vercel or Netlify dashboard, update environment variables:
103+
104+
**Vercel:** Project Settings > Environment Variables
105+
106+
**Netlify:** Site settings > Environment variables
107+
108+
| Variable | Value |
109+
|----------|-------|
110+
| `VITE_CONVEX_URL` | `https://your-project.convex.cloud` (from step 1) |
111+
| `VITE_WORKOS_CLIENT_ID` | `client_xxxxx` (from step 2) |
112+
113+
- [ ] VITE_CONVEX_URL set
114+
- [ ] VITE_WORKOS_CLIENT_ID set
115+
116+
### 7. Redeploy frontend
117+
118+
Trigger a new deployment in Vercel or Netlify to pick up the new environment variables.
119+
120+
**Vercel:** Deployments > Redeploy
121+
122+
**Netlify:** Deploys > Trigger deploy
123+
124+
- [ ] Frontend redeployed with correct environment variables
125+
126+
### 8. Test the app
127+
128+
1. Visit your deployed URL
129+
2. Click "Get Started" to sign in
130+
3. Create an account or sign in
131+
4. You should see the empty dashboard
132+
5. Go to Settings and generate an API key
133+
134+
- [ ] Can sign in with WorkOS
135+
- [ ] Dashboard loads correctly
136+
- [ ] Can generate API key in Settings
137+
138+
## Install a sync plugin (optional)
139+
140+
Once your instance is working, install a plugin to sync coding sessions:
141+
142+
**For Claude Code:**
143+
```bash
144+
npm install -g claude-code-sync
145+
claude-code-sync login
146+
```
147+
148+
**For OpenCode:**
149+
```bash
150+
npm install -g opencode-sync-plugin
151+
opencode-sync login
152+
```
153+
154+
**For Codex CLI:**
155+
```bash
156+
npm install -g codex-sync
157+
codex-sync login
158+
```
159+
160+
Enter your Convex URL and API key when prompted.
161+
162+
## Troubleshooting
163+
164+
### "Setup incomplete" banner showing
165+
166+
The app detected missing environment variables. Check that:
167+
- `VITE_CONVEX_URL` is set in Vercel/Netlify
168+
- `VITE_WORKOS_CLIENT_ID` is set in Vercel/Netlify
169+
- You redeployed after setting the variables
170+
171+
### Login redirects but user stays on login page
172+
173+
1. Check WorkOS redirect URI matches your deployed URL exactly
174+
2. Check `WORKOS_CLIENT_ID` is set in Convex environment variables
175+
3. Run `npx convex deploy` to sync changes
176+
177+
### "Invalid token" errors
178+
179+
1. Verify `WORKOS_CLIENT_ID` matches between Convex and frontend
180+
2. Run `npx convex deploy` after changing Convex env vars
181+
182+
### Sessions not appearing after plugin setup
183+
184+
1. Check plugin is authenticated: `claude-code-sync status` or `opencode-sync status`
185+
2. Check Convex dashboard logs for errors
186+
3. Verify API key is valid in OpenSync Settings
187+
188+
### Semantic search not working
189+
190+
1. Verify `OPENAI_API_KEY` is set in Convex environment variables
191+
2. Run `npx convex deploy`
192+
3. Wait a minute (embeddings generate asynchronously)
193+
194+
## Next steps
195+
196+
- [Full setup guide](https://www.opensync.dev/docs#hosting) for detailed configuration
197+
- [Plugin development guide](https://www.opensync.dev/docs#plugins) to build your own sync plugin
198+
- [API reference](https://www.opensync.dev/docs#api) for programmatic access
199+
- [install.md](install.md) for local development setup
200+
201+
## Need help?
202+
203+
Open an issue on [GitHub](https://github.com/waynesutton/opensync/issues) with:
204+
- Your deployment platform (Vercel or Netlify)
205+
- Which step you're stuck on
206+
- Any error messages from browser console or Convex logs

‎README.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,10 +96,19 @@ npm install
9696
npx convex dev
9797
```
9898

99-
Requires Convex, WorkOS, and Netlify accounts.
99+
Requires Convex, WorkOS, and OpenAI accounts.
100100

101101
[Self hosting guide](https://www.opensync.dev/docs#hosting) | [Fork guide](https://www.opensync.dev/docs#fork) | [install.md](install.md)
102102

103+
### One-click deploy
104+
105+
Deploy the frontend to Vercel or Netlify. **This deploys the web UI only.** You must set up Convex and WorkOS separately.
106+
107+
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/waynesutton/opensync&env=VITE_CONVEX_URL,VITE_WORKOS_CLIENT_ID&envDescription=Required%20environment%20variables%20for%20OpenSync&envLink=https://github.com/waynesutton/opensync/blob/main/ONE-CLICK-DEPLOY.md)
108+
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/waynesutton/opensync)
109+
110+
After deploying, follow the [post-deploy checklist](ONE-CLICK-DEPLOY.md) to complete setup.
111+
103112
## Dashboard
104113

105114
Four views for managing your sessions:

‎changelog.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,16 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
66

77
## [Unreleased]
88

9+
### Added
10+
11+
- One-click deploy buttons for Vercel and Netlify in README
12+
- Deploy buttons deploy frontend only with explicit warning
13+
- Created ONE-CLICK-DEPLOY.md post-deploy checklist with step-by-step Convex/WorkOS/OpenAI setup
14+
- Created vercel.json with SPA rewrite rules for client-side routing
15+
- Created SetupIncompleteBanner component showing when VITE_CONVEX_URL or VITE_WORKOS_CLIENT_ID is missing
16+
- Banner links to GitHub checklist for completing setup
17+
- Updated install.md with quick link to one-click deploy option
18+
919
### Fixed
1020

1121
- Fixed duplicate "cursor" and "Cursor" entries in source filter dropdown

‎files.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ Codebase file structure and descriptions.
1414
| `tailwind.config.js` | Tailwind CSS configuration |
1515
| `postcss.config.js` | PostCSS configuration |
1616
| `netlify.toml` | Netlify deployment config with SPA redirect rules |
17+
| `vercel.json` | Vercel deployment config with SPA rewrite rules for one-click deploy |
18+
| `ONE-CLICK-DEPLOY.md`| Post-deploy checklist for users who one-click deployed to Vercel or Netlify |
1719
| `README.md` | Project documentation with Ecosystem table (official + community plugins including codex-sync) |
1820
| `install.md` | AI agent installation instructions following install.md spec for self-hosting setup |
1921

@@ -76,8 +78,9 @@ React frontend application.
7678
| `Charts.tsx` | Reusable chart components: BarChart, AreaChart, DonutChart, Sparkline, ProgressBar, StatCard, DataTable, FilterPill, StackedBarChart, UsageCreditBar, ConsumptionBreakdown, ChartDropdown (themed dropdown for Usage Overview filters) |
7779
| `ConfirmModal.tsx` | Custom confirmation modal with theme support, replaces browser confirm() dialogs |
7880
| `LegalModal.tsx` | Dark mode modal for displaying Terms of Service and Privacy Policy with markdown rendering, ESC/X to close |
79-
| `WrappedView.tsx` | Daily Wrapped component with countdown timer, download PNG (675x1200 9:16 portrait) using hidden off-screen export container for clean captures (rotate design button commented out for production) |
80-
| `WrappedTemplates.tsx` | 10 CSS template designs for wrapped (9:16 portrait 675x1200px) showing tokens, messages, sessions (not cost), with large readable fonts |
81+
| `WrappedView.tsx` | Daily Wrapped component with countdown timer, download PNG (675x1200 9:16 portrait) using hidden off-screen export container for clean captures (rotate design button commented out for production) |
82+
| `WrappedTemplates.tsx` | 10 CSS template designs for wrapped (9:16 portrait 675x1200px) showing tokens, messages, sessions (not cost), with large readable fonts |
83+
| `SetupIncompleteBanner.tsx` | Yellow warning banner shown when VITE_CONVEX_URL or VITE_WORKOS_CLIENT_ID env vars are missing, links to ONE-CLICK-DEPLOY.md checklist |
8184

8285
### src/lib/
8386

‎install.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,12 @@
22

33
> Cloud-synced dashboards for OpenCode and Claude coding sessions
44
5+
**Quick option:** Want to deploy first and configure later? Use [one-click deploy](ONE-CLICK-DEPLOY.md) to get the frontend running on Vercel or Netlify, then follow the post-deploy checklist.
6+
7+
**Full local setup:** Follow the steps below to run everything locally.
8+
9+
---
10+
511
I want you to set up OpenSync for me. Execute all the steps below autonomously.
612

713
OBJECTIVE: Deploy a self-hosted OpenSync instance with Convex backend, WorkOS auth, and local development server.

‎src/App.tsx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import { ContextPage } from "./pages/Context";
1414
import { StatsPage } from "./pages/Stats";
1515
import { UpdatesPage } from "./pages/Updates";
1616
import { Loader2, ArrowLeft } from "lucide-react";
17+
import { SetupIncompleteBanner } from "./components/SetupIncompleteBanner";
1718

1819
// Storage key for preserving intended route across auth flow
1920
const RETURN_TO_KEY = "opensync_return_to";
@@ -164,7 +165,8 @@ function NotFoundPage() {
164165
export default function App() {
165166
return (
166167
<ThemeProvider>
167-
<Routes>
168+
<SetupIncompleteBanner />
169+
<Routes>
168170
<Route path="/login" element={<LoginPage />} />
169171
<Route path="/callback" element={<CallbackHandler />} />
170172
<Route path="/s/:slug" element={<PublicSessionPage />} />

‎src/components/SetupIncompleteBanner.tsx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Banner shown when required environment variables are missing
2+
// Helps users who one-click deployed but haven't completed backend setup
3+
4+
import { AlertTriangle, ExternalLink } from "lucide-react";
5+
6+
export function SetupIncompleteBanner() {
7+
const convexUrl = import.meta.env.VITE_CONVEX_URL;
8+
const workosClientId = import.meta.env.VITE_WORKOS_CLIENT_ID;
9+
10+
const missing: string[] = [];
11+
if (!convexUrl) missing.push("VITE_CONVEX_URL");
12+
if (!workosClientId) missing.push("VITE_WORKOS_CLIENT_ID");
13+
14+
// All required env vars are set, don't show banner
15+
if (missing.length === 0) return null;
16+
17+
return (
18+
<div className="bg-yellow-500/10 border-b border-yellow-500/20 px-4 py-2">
19+
<div className="max-w-7xl mx-auto flex items-center justify-center gap-2 text-sm">
20+
<AlertTriangle className="h-4 w-4 text-yellow-500 flex-shrink-0" />
21+
<span className="text-yellow-500">
22+
Setup incomplete: Missing {missing.join(", ")}.
23+
</span>
24+
<a
25+
href="https://github.com/waynesutton/opensync/blob/main/ONE-CLICK-DEPLOY.md"
26+
className="inline-flex items-center gap-1 text-yellow-500 hover:text-yellow-400 underline underline-offset-2"
27+
target="_blank"
28+
rel="noopener noreferrer"
29+
>
30+
Complete setup
31+
<ExternalLink className="h-3 w-3" />
32+
</a>
33+
</div>
34+
</div>
35+
);
36+
}

‎task.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,19 @@ OpenSync supports two AI coding tools: **OpenCode** and **Claude Code**.
88

99
- [ ] (add next task here)
1010
- [ ] fix write conflicts
11-
- [ ] add one click deploy
1211
- [ ] workos domain updates
1312
- [ ] models untitled
1413
- [ ] let users change session name
1514

15+
## Recently Completed (One-Click Deploy)
16+
17+
- [x] Added one-click deploy buttons for Vercel and Netlify
18+
- Created vercel.json with SPA rewrite rules
19+
- Created ONE-CLICK-DEPLOY.md post-deploy checklist
20+
- Created SetupIncompleteBanner component for missing env vars
21+
- Added deploy buttons to README Self-hosting section
22+
- Updated install.md with quick link to one-click deploy
23+
1624
## Recently Completed (Cursor Source Normalization)
1725

1826
- [x] Fixed duplicate "cursor" and "Cursor" entries in source filter dropdown

‎vercel.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
3+
}

0 commit comments

Comments
 (0)