Skip to content

Commit 9596a6d

Browse files
Copilotyash-pouranik
Copilot
and
yash-pouranik
committed
docs: add DEPLOYMENT.md guide for Render + Vercel raw deployment
Co-authored-by: yash-pouranik <172860064+yash-pouranik@users.noreply.github.com>
1 parent 71ae202 commit 9596a6d

2 files changed

Lines changed: 261 additions & 0 deletions

File tree

‎DEPLOYMENT.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# 🚀 Deployment Guide — Render (Backend) + Vercel (Frontend)
2+
3+
This guide walks you through deploying a self-hosted instance of **urBackend** from scratch using **free-tier** cloud services — no Docker required.
4+
5+
| Layer | Platform | Cost |
6+
| :--- | :--- | :--- |
7+
| Node.js API | [Render](https://render.com) | Free tier |
8+
| MongoDB | [MongoDB Atlas](https://www.mongodb.com/atlas) | Free (M0 cluster) |
9+
| Redis | [Upstash](https://upstash.com) | Free tier |
10+
| React/Vite dashboard | [Vercel](https://vercel.com) | Free tier |
11+
12+
---
13+
14+
## 📋 Table of Contents
15+
16+
1. [Prerequisites](#1-prerequisites)
17+
2. [Set up MongoDB Atlas](#2-set-up-mongodb-atlas)
18+
3. [Set up Upstash Redis](#3-set-up-upstash-redis)
19+
4. [Deploy the Backend to Render](#4-deploy-the-backend-to-render)
20+
5. [Deploy the Frontend to Vercel](#5-deploy-the-frontend-to-vercel)
21+
6. [Link the Frontend to the Backend](#6-link-the-frontend-to-the-backend)
22+
7. [Verify your deployment](#7-verify-your-deployment)
23+
24+
---
25+
26+
## 1. Prerequisites
27+
28+
Before you start, make sure you have:
29+
30+
- A [GitHub](https://github.com) account with a fork of this repository.
31+
- A [MongoDB Atlas](https://www.mongodb.com/atlas) account (free).
32+
- An [Upstash](https://upstash.com) account (free).
33+
- A [Render](https://render.com) account (free).
34+
- A [Vercel](https://vercel.com) account (free).
35+
36+
> **Tip:** You only need to complete steps 2 and 3 once — the same Atlas cluster and Upstash database can be reused across multiple deployments.
37+
38+
---
39+
40+
## 2. Set up MongoDB Atlas
41+
42+
1. Go to [cloud.mongodb.com](https://cloud.mongodb.com) and sign in.
43+
2. Click **"Build a Database"** → choose the **Free (M0)** shared tier.
44+
3. Select a cloud provider and region closest to your Render deployment region.
45+
4. Enter a cluster name (e.g. `urbackend`) and click **"Create"**.
46+
5. Under **Security → Database Access**, create a database user:
47+
- Username: `urbackend-user`
48+
- Password: generate a strong password and **copy it**.
49+
- Role: **"Read and write to any database"**.
50+
6. Under **Security → Network Access**, click **"Add IP Address"** → select **"Allow Access from Anywhere"** (`0.0.0.0/0`).
51+
52+
> This is required because Render uses dynamic IP addresses.
53+
54+
7. Go to **Database → Connect** → **"Drivers"** and copy the **connection string**. It looks like:
55+
56+
```
57+
mongodb+srv://urbackend-user:<password>@urbackend.xxxxx.mongodb.net/?retryWrites=true&w=majority
58+
```
59+
60+
Replace `<password>` with the password you copied in step 5, and append the database name before the query string:
61+
62+
```
63+
mongodb+srv://urbackend-user:<password>@urbackend.xxxxx.mongodb.net/urbackend?retryWrites=true&w=majority
64+
```
65+
66+
**Save this URL** — you will need it in step 4.
67+
68+
---
69+
70+
## 3. Set up Upstash Redis
71+
72+
1. Go to [console.upstash.com](https://console.upstash.com) and sign in.
73+
2. Click **"Create Database"**.
74+
3. Enter a name (e.g. `urbackend-redis`), choose the region closest to your Render region, and leave the type as **Regional**.
75+
4. Click **"Create"**.
76+
5. On the database details page, scroll to **"REST API"** or **"Connect"** and copy the **Redis URL**. It looks like:
77+
78+
```
79+
rediss://default:<password>@<host>.upstash.io:6379
80+
```
81+
82+
**Save this URL** — you will need it in step 4.
83+
84+
---
85+
86+
## 4. Deploy the Backend to Render
87+
88+
### 4.1 Create a new Web Service
89+
90+
1. Go to [dashboard.render.com](https://dashboard.render.com) and click **"New +"** → **"Web Service"**.
91+
2. Connect your GitHub account and select your fork of `urBackend`.
92+
3. Fill in the service settings:
93+
94+
| Setting | Value |
95+
| :--- | :--- |
96+
| **Name** | `urbackend-api` (or any name you prefer) |
97+
| **Region** | Choose the region closest to your Atlas & Upstash region |
98+
| **Branch** | `main` |
99+
| **Root Directory** | `backend` |
100+
| **Runtime** | `Node` |
101+
| **Build Command** | `npm install` |
102+
| **Start Command** | `npm start` |
103+
| **Instance Type** | Free |
104+
105+
4. Click **"Advanced"** to expand the environment variable section.
106+
107+
### 4.2 Configure environment variables
108+
109+
Add **each** of the following environment variables one by one using the **"Add Environment Variable"** button:
110+
111+
```env
112+
# Server
113+
PORT=1234
114+
NODE_ENV=production
115+
116+
# Database & Cache
117+
MONGO_URL=<your MongoDB Atlas connection string from step 2>
118+
REDIS_URL=<your Upstash Redis URL from step 3>
119+
120+
# Authentication — generate strong random strings (min 32 chars)
121+
JWT_SECRET=<at_least_32_random_characters>
122+
ENCRYPTION_KEY=<exactly_32_character_string>
123+
API_KEY_SALT=<random_string_for_api_key_hashing>
124+
125+
# External Storage (Supabase) — required for file uploads
126+
SUPABASE_URL=https://your-project.supabase.co
127+
SUPABASE_KEY=your-supabase-anon-key
128+
129+
# Email (Resend) — required for OTP / email verification
130+
RESEND_API_KEY=re_your_resend_api_key
131+
EMAIL_FROM=onboarding@resend.dev
132+
133+
# Frontend URL — update after deploying the frontend (step 5)
134+
FRONTEND_URL=https://your-frontend.vercel.app
135+
```
136+
137+
> **Security note:** Never commit real secrets to your repository. Always use the Render environment variable panel or a secrets manager.
138+
139+
> **Generating secrets:** You can run `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"` locally to generate a strong random string for `JWT_SECRET`, `ENCRYPTION_KEY`, and `API_KEY_SALT`.
140+
141+
### 4.3 Deploy
142+
143+
1. Click **"Create Web Service"**.
144+
2. Render will pull your code, run `npm install`, and start the server. The first deploy usually takes 2–3 minutes.
145+
3. Once the status shows **"Live"**, copy the service URL — it looks like:
146+
147+
```
148+
https://urbackend-api.onrender.com
149+
```
150+
151+
**Save this URL** — you will need it when deploying the frontend.
152+
153+
### 4.4 Verify the backend
154+
155+
Open your browser (or use `curl`) and visit:
156+
157+
```
158+
https://urbackend-api.onrender.com/health
159+
```
160+
161+
You should see a `200 OK` response confirming the API is running.
162+
163+
> **Free tier cold starts:** Render's free tier spins down services after 15 minutes of inactivity. The first request after a cold start may take 30–60 seconds.
164+
165+
---
166+
167+
## 5. Deploy the Frontend to Vercel
168+
169+
### 5.1 Import the project
170+
171+
1. Go to [vercel.com/new](https://vercel.com/new) and sign in with GitHub.
172+
2. Click **"Add New… → Project"** and import your fork of `urBackend`.
173+
3. In the project configuration screen:
174+
175+
| Setting | Value |
176+
| :--- | :--- |
177+
| **Root Directory** | `frontend` |
178+
| **Framework Preset** | Vite (auto-detected) |
179+
| **Build Command** | `npm run build` (default) |
180+
| **Output Directory** | `dist` (default) |
181+
182+
### 5.2 Configure the environment variable
183+
184+
Under **"Environment Variables"**, add:
185+
186+
```env
187+
VITE_API_URL=https://urbackend-api.onrender.com
188+
```
189+
190+
Replace the value with the actual Render service URL you copied in step 4.3.
191+
192+
> This variable tells the React app where your backend API lives. Without it, the frontend will default to `http://localhost:1234` and will not work in production.
193+
194+
### 5.3 Deploy
195+
196+
1. Click **"Deploy"**.
197+
2. Vercel will install dependencies and build the Vite project. This usually takes under a minute.
198+
3. Once the deployment is complete, Vercel will give you a URL like:
199+
200+
```
201+
https://ur-backend.vercel.app
202+
```
203+
204+
---
205+
206+
## 6. Link the Frontend to the Backend
207+
208+
After the frontend is deployed, you must go back to Render and update the `FRONTEND_URL` environment variable:
209+
210+
1. In the [Render dashboard](https://dashboard.render.com), open your `urbackend-api` service.
211+
2. Go to **"Environment"** and update:
212+
213+
```env
214+
FRONTEND_URL=https://ur-backend.vercel.app
215+
```
216+
217+
3. Click **"Save Changes"**. Render will automatically redeploy the backend with the updated CORS origin.
218+
219+
---
220+
221+
## 7. Verify your deployment
222+
223+
1. Open your Vercel frontend URL in the browser.
224+
2. Create a new account and log in — this exercises the Auth API against your live backend.
225+
3. Create a project and insert a document — this confirms the MongoDB Atlas connection is working.
226+
4. Check the Render logs (**Logs** tab on the service page) if anything is not working.
227+
228+
### Common issues
229+
230+
| Symptom | Likely cause | Fix |
231+
| :--- | :--- | :--- |
232+
| Frontend shows network error | `VITE_API_URL` is wrong or missing | Re-deploy frontend with correct env var |
233+
| Backend returns 500 on any request | `MONGO_URL` is wrong | Check Atlas connection string & network access rules |
234+
| Login emails not arriving | `RESEND_API_KEY` is missing/invalid | Add a valid key from [resend.com](https://resend.com) |
235+
| File uploads fail | `SUPABASE_URL` / `SUPABASE_KEY` missing | Add valid Supabase credentials |
236+
| Frontend CORS errors | `FRONTEND_URL` not updated on backend | Update and redeploy the Render service |
237+
238+
---
239+
240+
## 🔁 Re-deploying after code changes
241+
242+
- **Render** automatically redeploys when you push to the `main` branch of your GitHub fork (if auto-deploy is enabled in the Render dashboard).
243+
- **Vercel** automatically redeploys on every push and even creates preview deployments for pull requests.
244+
245+
---
246+
247+
## 📚 Further reading
248+
249+
- [MongoDB Atlas documentation](https://www.mongodb.com/docs/atlas/)
250+
- [Upstash Redis documentation](https://upstash.com/docs/redis/overall/getstarted)
251+
- [Render Web Services documentation](https://docs.render.com/web-services)
252+
- [Vercel deployment documentation](https://vercel.com/docs/deployments/overview)
253+
- [urBackend Contributing Guide](CONTRIBUTING.md)

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,14 @@ graph LR
7474

7575
Explore our [Architecture Diagram](ARCHITECTURE_DIAGRAM.md) to understand the system design, core components, and data flow in detail.
7676

77+
---
78+
79+
## 🏠 Self-Hosting
80+
81+
Want to run your own instance? Follow the step-by-step guide to deploy urBackend to **Render** (backend) and **Vercel** (frontend) using free-tier services — no Docker required.
82+
83+
👉 **[DEPLOYMENT.md](DEPLOYMENT.md)**
84+
7785
---
7886
## 🤝 Community
7987

0 commit comments

Comments
 (0)