Scout Properties

A modern full-stack real estate platform

📋 Table of Contents

1. 🤖 Introduction
2. 🏗 Architecture
3. 🛠️ Tech Stack
4. 🚀 Features
5. 🤸 Quick Start
6. 🚢 Deployment
7. 👏 Credits

🤖 Introduction

Scoutproperties is a real estate application where property agents or owners can register and post properties for rent or sale. Users can search for houses, apartments, condos or land and contact the agent or owner to buy or rent the property.

🏗 Architecture

Scout Properties uses a modern container-based architecture:

• Client: React app built with Vite and served via Nginx
• Server: Node.js + Express API running in Docker
• Database: MongoDB with replica set (Docker)
• CI/CD: GitHub Actions builds Docker images and deploys to a VPS

🛠️ Tech Stack

• React
• TypeScript
• TailwindCSS
• Cloudinary
• Node.js
• Express
• MongoDB (Replica Set)
• Docker & Docker Compose
• GitHub Actions (CI/CD)
• OpenAPI

🚀 Features

👉 Register: Users can sign up and create a personal profile.

👉 Login: Users can login into their account.

👉 Update Profile: Users can update their profile.

👉 View Properties: Users can view all properties without being logged in.

👉 Search and filter Properties: Users can search and filter for properties without being logged in.

👉 Create property listings: Logged in users(property owners or agents) can create property listings.

👉 Image Upload Widget using Cloudinary: Users can upload profile avatars or images for a property listing within the app using Cloudinary Image Upload Widget.

👉 Send Email: Users can send an email to the property owner or agent to buy or rent property.

👉 Fully Responsive UI: The application works seamlessly on all device types and screen sizes.

🤸 Quick Start

Follow these steps to set up the project locally on your machine.

Prerequisites

Make sure you have the following installed on your machine:

• Git
• Node.js
• yarn

Cloning the Repository

git clone https://github.com/Mupa1/scoutproperties.git
cd scoutproperties

Installation

Install the project dependencies using yarn:

Client

cd client
yarn install

Server

cd server
yarn install

Set Up Environment Variables

Client

cd client

Create a new file named .env.local in the root of your client directory and add the following content:

VITE_API_BASE_URL='http://localhost:3000'

Server

cd server

Create a new file named .env in the root of your server directory and add the following content including your MongoDB database URL and any JWT secret key:

DATABASE_URL=
JWT_SECRET_KEY=

Running the Project

Ensure both client and server are running.

Client

cd client
yarn dev

Server

cd server
yarn dev

Open http://localhost:4173 in your browser to view the project.

Testing the API Endpoint

• Through OpenAPI Documentation:

  Open http://localhost:3000/api-docs in your browser to view the API documentation and test the API endpoints.

• Through Postman:

  Open http://localhost:3000 in Postman to test the various API endpoints.

🚢 Deployment

This project uses Docker-based CI/CD with GitHub Actions and GitHub Container Registry (GHCR).

Deployment Flow

1. Push to main or master
2. GitHub Actions:
   • runs tests
   • builds Docker images
   • pushes images to GHCR
3. VPS:
   • pulls latest images
   • restarts containers
   • runs database migrations

No builds or dependency installation happen on the VPS.

⚠ Data Persistence Warning

Running the following command will permanently delete all database data:

docker compose down -v

🧠 Deployment Mental Model

Keep this in mind when working on Scout Properties:

Concern	Where it happens
Build images	GitHub Actions
Store images	GitHub Container Registry (GHCR)
Run containers	VPS
Database	Docker volume (persistent)
Migrations	VPS (inside server container)
Safety	Code + database constraints

Docker images are disposable.
The database is not.

---

VPS Requirements

• Docker
• Docker Compose
• Access to GitHub Container Registry

---

Required GitHub Secrets

Add the following under
Repository → Settings → Secrets and variables → Actions:

VPS_HOST
VPS_USER
VPS_SSH_KEY
VPS_APP_PATH
VITE_API_BASE_URL

👏 Credits

The listings images are from Unsplash.