# Deploying My Apartments — a complete guide for beginners This guide assumes you've never deployed a website with a database before. Every step is spelled out — nothing is assumed. It will take somewhere between 45 minutes and 2 hours the first time, mostly waiting for things to install. **Read this whole page once before doing anything.** It'll make more sense as a plan than as a list of commands you're typing blind. --- ## 1. What you're actually deploying Most of this app is a single Node.js program. When it runs, it does two things at once: - Serves the website itself (the HTML/CSS/JS pages you've been looking at) - Answers the app's data requests (logging in, saving a payment, loading a report — anything that needs the database) Alongside it sits one **MySQL database** — the actual storage for every flat, resident, payment, and everything else. That's the whole picture: **one small program + one database.** You don't need to host the website and the "backend" separately — they're the same thing. This matters because it's exactly the combination most web hosts sell as a single, named package: "Node.js hosting with MySQL," or sometimes just "Node.js App" inside a control panel that already includes MySQL. --- ## 2. Choosing where to host it You have two realistic paths. Read both descriptions, then pick one — you don't need both. ### Path A — A modern app host (Railway, Render, or similar) **Best if:** this is your first time deploying anything, and you want the fewest possible steps. These are newer hosting services built around a very simple idea: you connect your code, click a few buttons, and it handles the server setup for you — no command-line server administration, no manually installing Node.js, no configuring a web server program. They also give you a MySQL database with a few clicks, and HTTPS (the padlock icon) is automatic and free. The trade-off: these usually aren't free forever for a real, always-on app — expect a small monthly cost (often starting around $5–10/month once any free trial credit runs out). For a small building's resident portal, that's normal and low. ### Path B — Traditional web hosting with cPanel (GoDaddy, Hostinger, Namecheap, Bluehost, etc.) **Best if:** you already have hosting like this, or specifically want the classic "web hosting" setup with a control panel. This is what most people mean by "web hosting." The trade-off going the other way: not every cPanel plan supports Node.js — you specifically need one that lists **"Node.js" or "Node.js Selector"** as a feature (check before you buy, or check your existing plan's feature list). If your plan doesn't have it, upgrading to one that does, or switching to Path A, will be far less frustrating than trying to force it to work without that feature. **If you're genuinely unsure which to pick, choose Path A.** It has fewer places to get stuck. --- ## 3. Path A — Deploying on Railway (step by step) Render, and platforms like it, follow this same shape — the exact button labels differ, but every step below has an equivalent. ### Step 1 — Get your code online Railway deploys from GitHub, so your project needs to live there first. 1. Go to [github.com](https://github.com) and create a free account if you don't have one. 2. Click the **+** in the top right → **New repository**. Name it `my-apartments`. Leave everything else at its default. Click **Create repository**. 3. On the new repository's page, click **uploading an existing file** (a link partway down the empty-repo page). 4. Drag your entire unzipped `my-apartments` project folder in, or use "choose your files" to select everything inside it. Wait for the upload to finish, then scroll down and click **Commit changes**. ### Step 2 — Create your database 1. Go to [railway.app](https://railway.app) and sign up (you can use your GitHub account). 2. Click **New Project** → **Provision MySQL**. Wait about a minute for it to spin up. 3. Click on the MySQL box that appears → the **Variables** tab. You'll see values named `MYSQLHOST`, `MYSQLPORT`, `MYSQLUSER`, `MYSQLPASSWORD`, `MYSQLDATABASE` (or similar names). **Keep this tab open** — you'll copy these in Step 4. ### Step 3 — Load the database structure This one step needs a MySQL client on your own computer — everything else in this guide doesn't. 1. Download **[MySQL Workbench](https://dev.mysql.com/downloads/workbench/)** (free) or **[TablePlus](https://tableplus.com/)** (free tier is enough) and install it. 2. Open it, create a new connection using the `MYSQLHOST`/`MYSQLPORT`/`MYSQLUSER`/`MYSQLPASSWORD` values from Railway's Variables tab. 3. Once connected, open the file `backend/src/schema.sql` from your project (File → Open SQL Script, or the equivalent), and run it. This creates all the empty tables — no data yet. ### Step 4 — Deploy the app 1. Back in your Railway project, click **New** → **GitHub Repo** → select `my-apartments`. 2. Railway will ask for a **Root Directory** — set it to `backend`. This tells Railway "the app lives in this subfolder," since your repository also contains the `frontend` folder alongside it (which the backend serves itself — see Section 1). 3. Click on the new service → **Variables** tab → **Raw Editor**, and paste this in, replacing the placeholder values with the real ones from your MySQL service's Variables tab (Step 2): ``` DB_HOST= DB_PORT= DB_USER= DB_PASSWORD= DB_NAME= JWT_SECRET= ADMIN_EMAIL=your-real-email@example.com CORS_ORIGIN=* ``` **Generating `JWT_SECRET`:** this needs to be a long, random, unguessable string — think of it as the master key that makes login sessions trustworthy. Go to [randomkeygen.com](https://randomkeygen.com), copy any one of the "CodeIgniter Encryption Keys" or "504-bit WPA Key" values, and paste it as the value. Don't reuse a password you use anywhere else, and don't leave this as the example text from `.env.example`. 4. Click **Deploy**. Watch the **Deployments** tab — after a couple of minutes it should say **Success**. 5. Railway → **Settings** tab → **Networking** → **Generate Domain**. This gives you a free `something.up.railway.app` web address — click it to open your site. ### Step 5 — Load demo data (so you can see it working) 1. On your computer, open a terminal in your project's `backend` folder. 2. Create a file named `.env` there (copy `.env.example` and rename it), and paste in the exact same values you used in Step 4's Railway Variables. 3. Run: ``` npm install npm run seed ``` 4. Visit your Railway URL from Step 4 again — you should now see real-looking demo data throughout the site. Log in with `admin` / `Admin@123` (change this immediately — see Section 5). **Connecting your own domain instead of `*.up.railway.app`:** Settings → Networking → Custom Domain, then follow Railway's on-screen instructions for pointing your domain's DNS at it. This part varies by domain registrar, so Railway's own instructions (shown right there) are more current than anything written here. --- ## 4. Path B — Deploying on cPanel hosting (step by step) Exact menu names vary a little between hosts, but every cPanel with Node.js support has these same pieces, usually under headings very close to these names. ### Step 1 — Create the database 1. Log into cPanel → **MySQL® Databases**. 2. Under "Create New Database," name it `my_apartments` (your host may prefix it automatically, e.g. `youraccount_my_apartments` — that's normal, just note the full name). 3. Scroll to "MySQL Users" → create a new user with a strong password (write it down somewhere safe — you'll need it in Step 4). 4. Scroll to "Add User to Database," select the user and database you just made, and check **All Privileges**. ### Step 2 — Upload your files 1. cPanel → **File Manager** → navigate to a folder outside `public_html` — many hosts use `nodeapp` or you can create a folder called `my-apartments` at the same level as `public_html`. (Node apps in cPanel don't live in `public_html` the way plain HTML sites do — the Node.js feature you'll use in Step 3 handles making it reachable from the web.) 2. Upload your project as a `.zip` (use File Manager's Upload button), then right-click it → **Extract**. ### Step 3 — Set up the Node.js app 1. cPanel → **Setup Node.js App** → **Create Application**. 2. **Node.js version:** pick 18 or higher. 3. **Application root:** the folder from Step 2, plus `/backend` (e.g. `my-apartments/backend`). 4. **Application URL:** choose your domain (or a subdomain, if you'd rather keep it separate from an existing site). 5. **Application startup file:** `server.js`. 6. Click **Create**. The page will reload showing your new app with a **Run NPM Install** button — click it and wait for it to finish (this downloads the packages the app needs to run). ### Step 4 — Configure environment variables Still on the Setup Node.js App page for your application, scroll to **Environment Variables** and add each of these one at a time (Add Variable → name → value → Save): | Name | Value | |---|---| | `DB_HOST` | `localhost` (almost always, for cPanel) | | `DB_PORT` | `3306` | | `DB_USER` | the database user you created in Step 1 | | `DB_PASSWORD` | that user's password | | `DB_NAME` | the full database name from Step 1 | | `JWT_SECRET` | a long random string — see the box in Path A, Step 4 | | `ADMIN_EMAIL` | your real email address | | `CORS_ORIGIN` | `*` | ### Step 5 — Load the database structure 1. cPanel → **phpMyAdmin** → select your database on the left. 2. Click the **Import** tab → **Choose File** → select `backend/src/schema.sql` from your computer → **Go**. This creates all the tables. ### Step 6 — Load demo data and start the app 1. Back on the **Setup Node.js App** page, find the **Run JS Script** option (or similar — some hosts call it "Execute Command"), and run: `src/seed.js` — if your host doesn't offer that, use its **Terminal** feature instead (cPanel → Terminal), navigate into your app folder, and run `node src/seed.js` directly. 2. On the Setup Node.js App page, click **Restart** (or **Start App**, if it isn't already running). 3. Visit your domain — you should see the site, with demo data throughout. Log in with `admin` / `Admin@123` (change this immediately — see Section 5). --- ## 5. Before you tell anyone the site exists Do these regardless of which path you took: 1. **Change the demo admin password.** Log in as `admin`, go to Profile, change the password to something real. Do the same for `guard1` and `cashier1` if you'll use those accounts, or, if you won't, sign in as Super Admin (`superadmin` / `Admin@123`, also change this password) and reassign them to a harmless role from the Roles & Permissions page — there's currently no "delete a user" option in the app, only reassigning what a user can access. 2. **Confirm `JWT_SECRET` isn't the placeholder text.** If you skipped that step, go back — this is the one setting that's a genuine security problem if left unset. 3. **Decide what to do about the demo data.** Everything you're seeing right now — 200 flats, residents named Pooja Chatterjee and Rohan Sharma, sample payments — is realistic-looking *sample* data generated by `npm run seed`, not your real building. See Section 6 below before treating this as production-ready for actual residents. --- ## 6. Important: about the demo data (read this before going live with real residents) This app currently ships with one way to load data in bulk: `npm run seed`, which fills the database with **200 fictional flats and fictional residents** so every feature has something real-looking to show. There is currently no admin screen for bulk-importing your actual building's real flat list, block names, or resident details — that's a genuine gap, not a step you're missing. Two honest paths forward, depending on your building: - **If your building's structure (block names, number of flats per block) happens to be close to the demo's 6 blocks / 200 flats**, an administrator familiar with basic SQL could edit the `apartments` and `users` tables directly (via phpMyAdmin or MySQL Workbench) to replace the fictional names and details with real ones, flat by flat. - **If your building's structure is meaningfully different**, someone comfortable with the code would need to adjust `backend/src/seed.js`'s building definition (block names, flats per block) to match your real building before running `npm run seed` — or a proper "add my real building's data" admin feature would need to be built. That's a reasonable next feature to ask for, not something to attempt by hand at 3am the night before residents start using this. Whichever path you take, **do not run `npm run seed` again once real data is in the database** — it truncates every table and starts over from the fictional demo set. --- ## 7. Troubleshooting **"Application Error" / site won't load at all** Check your host's Node.js logs (cPanel: Setup Node.js App → your app → **Errors** section; Railway: your service → **Deployments** → click the latest one → **View Logs**). The most common causes are a typo in an environment variable, or `npm install` not having finished before the app tried to start. **Site loads, but logging in fails / pages show no data** This almost always means the app can't reach the database. Double-check `DB_HOST`, `DB_USER`, `DB_PASSWORD`, and `DB_NAME` are exactly right — a single wrong character is the most common cause. If you're on cPanel and just changed a variable, remember to click **Restart**. **Pages load but look unstyled (plain black text, no colors or layout)** The CSS/JS files aren't being found. Confirm the `frontend` folder sits directly alongside `backend` — not inside it, not one level higher — matching the structure your project came in. **"Can't reach database" right after first deploying** Some hosts' databases take a minute to fully start after creation. Wait 60 seconds and try again before assuming something's wrong. --- ## 8. Keeping it running - **Backups:** ask your host how to schedule automatic MySQL backups — this is usually a checkbox or a small add-on, not something to build yourself. Do this before real residents start using the app, not after something goes wrong. - **Updates:** if you make changes to the code later, redeploying is: upload the new files (Path B) or push to GitHub again (Path A, which redeploys automatically) — you do **not** need to recreate the database or run the schema/seed steps again for a normal code update.