Setup & Installation

PropertyPro is a complete property management application built with Next.js 16, React 19, and MongoDB. Version 3.0 adds a public marketing website with online rental applications. This documentation covers everything from your first install to deploying in production.

Fresh install? Skip this section entirely. Upgrading from any 2.x version? v3.0 replaces NextAuth with Better Auth and needs a one-time database migration. Until it has run nobody can sign in — not even an administrator with the right password — and the app refuses to serve requests.

1. 1

   Back up first

   Settings → Backups → Create backup, or run mongodump. This is the entire rollback plan — do not skip it.

   bashCopy

   mongodump --uri="$MONGODB_URI" --archive=pre-v3-upgrade.archive --gzip

2. 2

   Copy the v3.0 files and install

   Preserve .env.local and your local ./uploads directory.

   bashCopy

   pnpm install

3. 3

   Leave your environment alone

   No change is required. v3.0 reads BETTER_AUTH_SECRET first and falls back to AUTH_SECRET, then NEXTAUTH_SECRET. If you switch to the new names, copy the same value across — a new secret signs everyone out.

4. 4

   Run the migration

   Additive and safe to re-run: it copies password hashes rather than moving them, and skips anything already migrated. If it is interrupted, just run it again.

   bashCopy

   pnpm db:migrate-better-auth --dry-run   # preview
   pnpm db:migrate-better-auth             # apply

5. 5

   Rebuild and verify

   Sign in with an existing account and its existing password, check that Settings → Security lists your session, and confirm terminating a session signs that device out.

   bashCopy

   pnpm build
   pnpm start

6. 6

   Run the optional migrations

   Not required to boot, but each fixes something. db:migrate-email-index lets you re-create a tenant whose account was deleted; db:backfill-coordinates puts pre-3.0 properties on the new maps.

   bashCopy

   pnpm db:migrate-email-index
   pnpm db:backfill-coordinates

# 1. Preview — writes nothing
pnpm db:migrate-better-auth --dry-run

# 2. Run it
pnpm db:migrate-better-auth

If you're already comfortable with Node, pnpm, and MongoDB, this is the express path. Each step is expanded later in the docs.

1. 1

   Install dependencies

   From the unzipped folder, install all packages with pnpm.

   bashCopy

   cd propertypro
   pnpm install

2. 2

   Copy env file

   Duplicate the example env, then set MONGODB_URI and generate an auth secret. Everything else has a working default.

   bashCopy

   cp .env.example .env.local
   openssl rand -base64 32   # paste as BETTER_AUTH_SECRET

3. 3

   Load sample data (optional)

   Seeds demo properties, units, and tenants so the dashboard isn't empty. It creates no login.

   bashCopy

   pnpm db:seed

4. 4

   Start the dev server

   Runs on http://localhost:3000. Leave it running for the next step.

   bashCopy

   pnpm dev

5. 5

   Create your first administrator

   Add SETUP_SECRET to .env.local, restart, then call the one-time bootstrap endpoint. Remove the secret afterwards.

   bashCopy

   curl -X POST http://localhost:3000/api/setup/create-admin \
     -H "Content-Type: application/json" \
     -H "x-setup-secret: $SETUP_SECRET" \
     -d '{"email":"you@example.com","password":"<strong password>","firstName":"Your","lastName":"Name"}'

PropertyPro runs anywhere Node.js does. These versions are tested in CI — older versions may work but aren't supported.

Download from CodeCanyon, unzip, and install. PropertyPro ships as a ready-to-run Next.js project — no build steps required to start dev.

1. 1

   Download from CodeCanyon

   Sign in to CodeCanyon → Downloads → PropertyPro. Choose 'All files & documentation'.

2. 2

   Unzip the package

   Extract the archive to a permanent location. The main folder is /propertypro.

   bashCopy

   unzip propertypro-v3.0.0.zip -d ~/projects/
   cd ~/projects/propertypro

3. 3

   Install dependencies

   We use pnpm for fast, deterministic installs. Run this once after every download or update.

   bashCopy

   pnpm install

4. 4

   Verify the install

   A quick smoke test confirms everything resolved correctly.

   bashCopy

   npx tsc --noEmit
   pnpm lint

All secrets live in .env.local. The included .env.example documents every key — only the core block is needed to boot. Payment gateways, SMTP, and maps are normally configured in the admin panel and stored in the database; the matching env values are used only as a fallback when the admin field is empty.

# ---- Required: core --------------------------------------------------
# MongoDB Atlas
MONGODB_URI=mongodb+srv://username:password@cluster0.kbnje.mongodb.net/propertypro
# Self-hosted alternative
# MONGODB_URI=mongodb://mongo:password@your_ip_address:27017/propertypro
# MONGODB_DB=propertypro

# Public base URL, no trailing slash
BETTER_AUTH_URL=http://localhost:3000
# Generate with: openssl rand -base64 32
BETTER_AUTH_SECRET=replace-with-a-long-random-string

# Upgrading from v2.x? The old names are still read as a fallback
# (BETTER_AUTH_SECRET -> AUTH_SECRET -> NEXTAUTH_SECRET). Keep the SAME
# value — changing the secret signs everyone out.
# NEXTAUTH_SECRET=

# ---- First admin (delete after use) ----------------------------------
# Unlocks POST /api/setup/create-admin. Generate: openssl rand -hex 32
# SETUP_SECRET=

# ---- Application -----------------------------------------------------
APP_NAME=PropertyPro
APP_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
SUPPORT_EMAIL=support@example.com

# ---- File storage ----------------------------------------------------
# "local" (default, ./uploads) or "cloud" (Cloudflare R2)
UPLOAD_STORAGE_PROVIDER=local
# R2_ACCOUNT_ID=
# R2_ACCESS_KEY_ID=
# R2_SECRET_ACCESS_KEY=
# R2_BUCKET_NAME=
# R2_PUBLIC_URL=https://files.example.com
# NEXT_PUBLIC_R2_PUBLIC_URL=https://files.example.com

# ---- Maps (normally set in Settings -> Maps) -------------------------
# "leaflet" (OpenStreetMap, free, no key — default), "google", "disabled"
# MAPS_PROVIDER=leaflet
# Browser key: Maps JavaScript API + Places API, restrict by HTTP referrer
# NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=
# Server key for db:backfill-coordinates: Geocoding API, restrict by IP
# GOOGLE_GEOCODING_API_KEY=

# ---- Stripe (fallback for the admin panel) ---------------------------
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# ---- Email / SMTP (fallback for the admin panel) ---------------------
# EMAIL_SERVER_HOST=smtp.gmail.com
# EMAIL_SERVER_PORT=587
# EMAIL_SERVER_USER=you@example.com
# EMAIL_SERVER_PASSWORD=your-app-password
# EMAIL_FROM=PropertyPro <noreply@example.com>
ENABLE_EMAIL_NOTIFICATIONS=true

# ---- Web Push (VAPID) ------------------------------------------------
# npx web-push generate-vapid-keys
# NEXT_PUBLIC_VAPID_PUBLIC_KEY=
# VAPID_PRIVATE_KEY=
# VAPID_SUBJECT=mailto:support@example.com

# ---- Encryption ------------------------------------------------------
# Required before storing SSNs. 32+ chars, keep stable across deploys.
# DATA_ENCRYPTION_KEY=

PropertyPro stores application data in MongoDB. Create a MongoDB Atlas cluster or self-hosted database, then point MONGODB_URI at it before starting the app.

1. 1

   Create a MongoDB database

   Create a MongoDB Atlas cluster and database named propertypro, or prepare a self-hosted MongoDB instance.

   bashCopy

   # MongoDB Atlas example
   MONGODB_URI=mongodb+srv://username:password@cluster0.kbnje.mongodb.net/propertypro

2. 2

   Allow network access

   In MongoDB Atlas, add your local IP address for development and your hosting provider's outbound IPs for production.

   txtCopy

   Atlas → Network Access → Add IP Address

3. 3

   Seed demo data (optional)

   Loads demo properties, units, and tenants so the dashboard isn't empty. It creates no login — use the setup endpoint for that.

   bashCopy

   pnpm db:seed

4. 4

   Run migrations when upgrading

   Fresh installs need none of these. Upgrading from v2.x requires the Better Auth migration — the app returns 503 on every request until it has run. Preview any of them with --dry-run.

   bashCopy

   pnpm db:migrate-better-auth --dry-run   # preview, writes nothing
   pnpm db:migrate-better-auth             # required, v2.x -> v3.0
   pnpm db:migrate-email-index             # allows re-creating deleted tenants
   pnpm db:backfill-coordinates            # puts pre-3.0 properties on the map

5. 5

   Inspect with MongoDB Compass

   Use MongoDB Compass or the Atlas Data Explorer to browse collections and verify seeded records.

   txtCopy

   mongodb+srv://username:password@cluster0.kbnje.mongodb.net/propertypro

Two scripts cover 99% of dev work: dev and build. The PWA service worker is disabled in dev to keep iteration fast.

1. 1

   Start in development

   Hot-reload, fast refresh, and source maps. Defaults to port 3000.

   bashCopy

   pnpm dev

2. 2

   Run a production build

   Compiles, treeshakes, and runs Next.js production server. Use this to validate before deploying.

   bashCopy

   pnpm build
   pnpm start

3. 3

   Visit the public site and the dashboard

   The site root is now the public marketing homepage, not a redirect to sign-in. The dashboard lives behind /auth/signin.

   txtCopy

   Public site:  http://localhost:3000
   Properties:   http://localhost:3000/properties
   Dashboard:    http://localhost:3000/dashboard

PropertyPro uses Cloudflare R2 for property images, tenant documents, and other uploaded files. Configure one private write path through R2 API credentials and one public read URL for displaying saved files.

1. 1

   Create an R2 bucket

   In Cloudflare, open Storage & databases -> R2 and create a bucket for PropertyPro uploads. Use a lowercase bucket name with numbers and hyphens only, then place that exact bucket name in R2_BUCKET_NAME.

   bashCopy

   R2_BUCKET_NAME=your-r2-bucket-name

2. 2

   Create a scoped R2 API token

   From the R2 overview, open Manage API Tokens, create an API token with Object Read & Write permission, and scope it to the PropertyPro bucket. Copy the Access Key ID, Secret Access Key, and account ID before leaving the confirmation screen.

   bashCopy

   R2_ACCOUNT_ID=your-r2-account-id
   R2_ACCESS_KEY_ID=your-r2-access-key-id
   R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
   R2_BUCKET_NAME=your-r2-bucket-name

3. 3

   Enable public file delivery

   For production, connect a custom domain such as assets.yourdomain.com to the bucket. For local testing only, you may enable the Cloudflare-managed r2.dev public development URL. Set both public URL variables to the exact origin with no trailing slash.

   bashCopy

   # Production custom domain
   R2_PUBLIC_URL=https://your-custom-domain.com
   NEXT_PUBLIC_R2_PUBLIC_URL=https://your-custom-domain.com
   
   # Local or staging with R2 public development URL
   # R2_PUBLIC_URL=https://pub-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.dev
   # NEXT_PUBLIC_R2_PUBLIC_URL=https://pub-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.dev

4. 4

   Allow the image host in Next.js

   The bundled next.config.ts already allows r2.dev and r2.cloudflarestorage.com image hosts. If you use a custom R2 domain and render uploaded images through next/image, add that hostname to images.remotePatterns, then rebuild.

   next.config.ts

   tsCopy

   images: {
     remotePatterns: [
       {
         protocol: "https",
         hostname: "assets.yourdomain.com",
         port: "",
         pathname: "/**",
         search: "",
       },
     ],
   }

5. 5

   Verify uploads

   Restart the app after changing environment variables, upload a property image or tenant document, then open the saved file URL. If the upload succeeds but previews fail, check the public bucket URL and image remote pattern first.

https://<ACCOUNT_ID>.r2.cloudflarestorage.com

PropertyPro uses Stripe Checkout for one-time invoices and Stripe Customer Portal for tenant self-service. Both work with test keys out of the box.

1. 1

   Get your API keys

   Stripe Dashboard → Developers → API keys. Copy the secret and publishable keys into .env.local.

2. 2

   Create a webhook endpoint

   Point Stripe at /api/webhooks/stripe on your deployed URL. Subscribe to checkout.session.completed and invoice.payment_succeeded.

   bashCopy

   # Webhook URL
   https://yourdomain.com/api/webhooks/stripe

3. 3

   Test webhooks locally

   Use the Stripe CLI to forward events to your dev server while developing.

   bashCopy

   stripe listen --forward-to localhost:3000/api/webhooks/stripe

4. 4

   Switch to live mode

   When ready, swap test keys (sk_test_*, pk_test_*) for live keys (sk_live_*, pk_live_*) and re-create the webhook in live mode.

Lease reminders, payment receipts, password resets, and tenant invites all go through one SMTP transport. We've tested Resend, SendGrid, Postmark, and standard SMTP servers.

Push notifications use the Web Push API with VAPID keys. Tenants and admins get instant alerts for payments, requests, and chats.

1. 1

   Generate VAPID keys

   Run the bundled generator. Copy both keys into .env.local.

   bashCopy

   pnpm gen:vapid

2. 2

   Set NEXT_PUBLIC_VAPID_PUBLIC_KEY

   The client uses this public key to subscribe browsers to the push service.

3. 3

   Set VAPID_PRIVATE_KEY

   The server uses this to sign push payloads. Never expose it to the browser.

4. 4

   Test from the dashboard

   Sign in, allow notifications when prompted, then go to Settings → Notifications → Send test.

All brand assets live under /public and the color palette is defined as Tailwind CSS variables. No code changes required for a basic rebrand.

1. 1

   Replace the logo

   Drop your SVG logo at /public/logo.svg. The dashboard reads from this path automatically.

2. 2

   Update the favicon & PWA icons

   Replace /public/favicon.ico and the icons under /public/icons/ (sizes 192, 256, 384, 512).

3. 3

   Tweak brand colors

   Edit the --brand-* tokens in app/globals.css. Tailwind picks them up across the app.

   app/globals.css

   cssCopy

   :root {
     --brand-50:  oklch(0.97 0.02 230);
     --brand-500: oklch(0.62 0.18 230);
     --brand-700: oklch(0.45 0.18 230);
   }

4. 4

   Update site metadata

   Edit app/layout.tsx to change the default title, description, and OG image.

PropertyPro ships with English, Arabic, French, Spanish, and Bengali. Locales live as JSON files under /messages and are loaded with next-intl.

1. 1

   Edit existing strings

   Open /messages/<locale>.json and edit values directly. Changes hot-reload in dev.

2. 2

   Add a new language

   Copy /messages/en.json to /messages/<your-locale>.json and translate values. Then register it in lib/i18n.ts.

   lib/i18n.ts

   tsCopy

   export const locales = ["en", "ar", "fr", "es", "bn", "de"] as const;
   export const defaultLocale = "en";

3. 3

   RTL support

   Arabic is enabled by default and switches the layout direction automatically. Add other RTL locales in lib/i18n.ts → rtlLocales.

Vercel is the fastest path to production. The whole flow takes under 10 minutes once your environment variables are ready.

1. 1

   Push to a GitHub repo

   Create a private GitHub repo and push the source. Vercel will pull from it.

   bashCopy

   git init
   git add .
   git commit -m "Initial PropertyPro setup"
   git remote add origin git@github.com:you/propertypro.git
   git push -u origin main

2. 2

   Import the repo into Vercel

   vercel.com → New Project → Import. Vercel auto-detects Next.js — no build config needed.

3. 3

   Add environment variables

   Project Settings → Environment Variables. Paste every key from your .env.local. Set APP_URL, NEXTAUTH_URL, and AUTH_URL to your Vercel URL.

4. 4

   Connect MongoDB Atlas

   Add Vercel's outbound access to MongoDB Atlas Network Access, then set MONGODB_URI in Vercel before deploying.

   bashCopy

   MONGODB_URI=mongodb+srv://username:password@cluster0.kbnje.mongodb.net/propertypro

5. 5

   Add your custom domain

   Project Settings → Domains. SSL is provisioned automatically.

If you'd rather run on a VPS, PropertyPro ships with a production-ready Dockerfile and a sample docker-compose.yml that can run MongoDB alongside the app.

1. 1

   Build & start the stack

   From the project root, build the images and run them in the background.

   bashCopy

   docker compose up -d --build

2. 2

   Seed demo data inside the container

   Load demo records only when you are setting up a test or evaluation instance.

   bashCopy

   docker compose exec app pnpm db:seed

3. 3

   Front with nginx + SSL

   Use nginx (or Caddy) to terminate TLS and proxy to localhost:3000. Caddy will provision Let's Encrypt automatically.

   Caddyfile

   nginxCopy

   propertypro.yourdomain.com {
     reverse_proxy localhost:3000
   }

services:
  app:
    build: .
    ports: ["3000:3000"]
    env_file: .env.local
    environment:
      MONGODB_URI: mongodb://propertypro:change-me@mongo:27017/propertypro?authSource=admin
    depends_on: [mongo]
  mongo:
    image: mongo:7
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: propertypro
      MONGO_INITDB_ROOT_PASSWORD: change-me
    volumes:
      - mongodata:/data/db
    ports: ["27017:27017"]

volumes:
  mongodata:

Once your app is live, route a custom domain to it. Both Vercel and Caddy provision SSL certificates for free.

1. 1

   Add an A or CNAME record

   For Vercel, add a CNAME pointing to cname.vercel-dns.com. For your VPS, point an A record at the server IP.

2. 2

   Verify in Vercel / Caddy

   Vercel auto-verifies once DNS propagates. Caddy reissues the certificate on the next request.

3. 3

   Update application URLs

   Switch APP_URL, NEXTAUTH_URL, and AUTH_URL to https://yourdomain.com and redeploy. These are used in emails and auth callbacks.

PropertyPro ships with no accounts at all. Create the first administrator through the one-time bootstrap endpoint, then invite your team with scoped permissions.

1. 1

   Create the first administrator

   Add SETUP_SECRET to your environment and restart, then POST once to the bootstrap endpoint. It is disabled while the secret is unset and refuses to run once any administrator exists, so it cannot be replayed.

   bashCopy

   openssl rand -hex 32   # use as SETUP_SECRET
   
   curl -X POST https://your-domain.com/api/setup/create-admin \
     -H "Content-Type: application/json" \
     -H "x-setup-secret: $SETUP_SECRET" \
     -d '{"email":"you@example.com","password":"<strong password>","firstName":"Your","lastName":"Name"}'

2. 2

   Remove the setup secret

   Delete SETUP_SECRET from your environment and redeploy. Its job is done.

3. 3

   Invite your team

   Settings → Team → Invite. Each invitee gets an email with a one-time setup link and chooses their own password — minimum 8 characters as of 3.0.

4. 4

   Assign roles

   Built-in roles are Admin, Manager, and Tenant. Manager and Tenant are now editable; Admin stays locked because it is the only guaranteed holder of role_management. Create custom roles under Settings → Roles.

5. 5

   Grant delete rights explicitly

   New in 3.0: lease_delete, tenant_delete, payment_delete, document_delete, property_delete, and user_delete are separate permissions and are never implied by the matching edit grant. The built-in Manager ships without them, so managers cannot delete until you grant them. Bulk deletes also need bulk_operations.

6. 6

   Audit log

   Every sensitive action is recorded, including public-site edits. Review under Settings → Activity.

PropertyPro ships minor updates monthly. Your data survives every release. v3.0 is the one upgrade that needs a database migration — the bundled UPGRADE.md covers it in full, including rollback.

1. 1

   Back up first

   Settings → Backups → Create backup, or run mongodump. On the v3.0 upgrade this is the entire rollback plan.

2. 2

   Download the latest build

   From your CodeCanyon downloads. Compare the version against the Changelog to plan the update.

3. 3

   Diff and merge

   Use git or your favorite diff tool to merge the new files, preserving .env.local and your local ./uploads directory.

4. 4

   Install and rebuild

   Install dependencies and run a production build after merging each release.

   bashCopy

   pnpm install
   pnpm build

5. 5

   v2.x → v3.0 only: run the auth migration

   v3.0 replaces NextAuth with Better Auth. Passwords, properties, leases, payments, and tenants are untouched, but every user is signed out once because the old JWT logins have no server-side record to convert. The migration is additive and safe to re-run.

   bashCopy

   pnpm db:migrate-better-auth --dry-run   # preview
   pnpm db:migrate-better-auth

6. 6

   v2.x → v3.0 only: verify

   Sign in with an existing account and its existing password, confirm Settings → Security lists your session, and check that terminating a session signs that device out.

7. 7

   Schedule database backups

   Use MongoDB Atlas automated backups or set up nightly mongodump on a VPS.

   bashCopy

   # Cron: nightly backup at 02:00
   0 2 * * * mongodump --uri="$MONGODB_URI" --archive=/backups/propertypro-$(date +\%F).archive --gzip

New in 3.0. Maps are a pluggable provider chosen in the app, not in a build step — the database setting wins over the environment, so switching provider needs no redeploy.

1. 1

   Pick a provider

   Dashboard → Settings → Maps offers OpenStreetMap, Google Maps, or no maps. The same form is embedded in Public Site → Settings; both write the same setting.

2. 2

   OpenStreetMap — the default, no setup

   Works on a fresh install with no API key, no Google Cloud account, and no credit card. Address search uses Nominatim, debounced and limited to queries of 3 characters or more to respect the OSM usage policy.

3. 3

   Google Maps — optional

   Reveals an API key field. Enable Maps JavaScript API and Places API on the key, and restrict it by HTTP referrer. Google Maps requires a Cloud billing account.

   bashCopy

   # Fallback only — Settings -> Maps takes precedence
   MAPS_PROVIDER=google
   NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your-browser-key

4. 4

   Geocode your existing properties

   Properties created before 3.0 have no coordinates and stay off the maps until you backfill them. Dry run by default: it lists what it would do, makes no API calls, and writes nothing.

   bashCopy

   pnpm db:backfill-coordinates
   
   # Apply for real
   GEOCODE_APPLY=1 GEOCODE_CONFIRM=BACKFILL_COORDINATES \
     GOOGLE_GEOCODING_API_KEY=your-server-key \
     pnpm db:backfill-coordinates

New in 3.0. PropertyPro serves a public home page, properties browser, property and unit detail pages, and a contact page from the same install — all of it switchable and editable from Dashboard → Public Site.

1. 1

   Switch pages on or off

   A master toggle plus per-page switches for Home, Properties, Property detail, and Contact. A page is live only when both its own switch and the master switch are on, and toggles save the moment you flip them.

2. 2

   Edit the copy

   Five editors cover Brand & navigation, Home, Properties, Contact, and FAQ — wordmark, logo, header and footer links, hero headline and background, feature cards, how-it-works steps, FAQ categories, contact methods, and per-page SEO and social share metadata.

3. 3

   Accept rental applications

   With Property detail on, visitors can apply for a unit through the checkout: lease terms, occupants, income, and screening consent, filed as a rental application. No payment is taken. Switch that page off and both checkout URLs redirect instead of accepting applications.

4. 4

   Grant access to the module

   The new public_site_management permission controls it. Built-in Admin has it, and existing custom admin roles holding system_settings keep access without any change.

5. 5

   Reset to defaults

   Public Site → Module settings restores any single section, or the whole public site, to the copy the app shipped with, behind a confirmation dialog.

Most install problems fall into the same handful of buckets. Walk through these before opening a support ticket.