mirror of
https://github.com/orangecoding/fredy.git
synced 2026-06-16 12:31:07 +00:00
Compare commits
10 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
bed0843f30 | ||
|
|
947e895de6 | ||
|
|
da848fcca1 | ||
|
|
74c3edd635 | ||
|
|
154043bed1 | ||
|
|
1854b421af | ||
|
|
b29fc4b183 | ||
|
|
47afa5659e | ||
|
|
f8e0376ddd | ||
|
|
29026ccad8 |
241
README.md
241
README.md
@@ -1,102 +1,159 @@
|
||||
# Fredy 🏡 – Your Self-Hosted Real Estate Finder for Germany
|
||||
|
||||
Finding an apartment or house in Germany can be stressful and
|
||||
time-consuming.\
|
||||
**Fredy** makes it easier: it automatically scrapes **ImmoScout24,
|
||||
Immowelt, Immonet, eBay Kleinanzeigen, and WG-Gesucht** and notifies you
|
||||
instantly via **Slack, Telegram, Email, ntfy, and more** when new
|
||||
listings appear.
|
||||
|
||||
With a modern architecture, Fredy provides a **clean Web UI**, removes
|
||||
duplicates across platforms, and stores results so you never see the
|
||||
same listing twice.
|
||||
|
||||
<img src="https://github.com/orangecoding/fredy/blob/master/doc/logo.png" width="400">
|
||||
|
||||
 [](https://github.com/orangecoding/fredy/actions/workflows/docker.yml) 
|
||||
|
||||
[](https://github.com/orangecoding/fredy/actions/workflows/docker.yml)
|
||||
|
||||
|
||||
Searching an apartment in Germany can be a frustrating task. Not any longer though, as _Fredy_ will take over and will only notify you once new listings have been found that match your requirements.
|
||||
------------------------------------------------------------------------
|
||||
|
||||
_Fredy_ scrapes multiple services (Immonet, Immowelt etc.) and send new listings to you once they become available. The list of available services can easily be extended. For your convenience, _Fredy_ has a UI to help you configure your search jobs.
|
||||
## ✨ Key Features
|
||||
|
||||
If _Fredy_ finds matching results, it will send them to you via Slack, Email, Telegram etc. (More adapters can be configured.) As _Fredy_ stores the listings it has found, new results will not be sent to you twice (and as a side-effect, _Fredy_ can show some statistics). Furthermore, _Fredy_ checks duplicates per scraping so that the same listings are not being sent twice or more when posted on various platforms (which happens more often than one might think).
|
||||
- 🏠 Scrapes **ImmoScout24, Immowelt, Immonet, eBay Kleinanzeigen,
|
||||
WG-Gesucht**
|
||||
- ⚡ Instant notifications: Slack, Telegram, Email (SendGrid,
|
||||
Mailjet), ntfy
|
||||
- 🔎 Uses the **ImmoScout Mobile API** (reverse engineered)
|
||||
- 🌍 Runs anywhere: Docker, Node.js, self-hosted
|
||||
- 🖥️ Intuitive **Web UI** to manage searches
|
||||
- 🎯 Easy to use thanks to a user-friendly Web UI
|
||||
- 🔄 Deduplication across platforms
|
||||
- ⏱️ Customizable search intervals
|
||||
|
||||
# Sponsorship [](https://github.com/sponsors/orangecoding)
|
||||
------------------------------------------------------------------------
|
||||
|
||||
If you like my work, consider becoming a sponsor. I'm not expecting anybody to pay for _Fredy_ or any other Open Source Project I'm maintaining, however keep in mind, I'm doing all of this in my spare time :) Thanks.
|
||||
## 🤝 Sponsorship [](https://github.com/sponsors/orangecoding)
|
||||
|
||||
[](https://jb.gg/OpenSourceSupport)
|
||||
I maintain Fredy and other open-source projects in my free time.\
|
||||
If you find it useful, consider supporting the project 💙
|
||||
|
||||
_Fredy_ is supported by JetBrains under Open Source Support Program
|
||||
[<img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg" alt="JetBrains" width="120"/>](https://jb.gg/OpenSourceSupport)
|
||||
|
||||
## Demo
|
||||
Fredy is proudly supported by the **JetBrains Open Source Support
|
||||
Program**.
|
||||
|
||||
If you want to try out _Fredy_, you can access the demo version [here](https://fredy.orange-coding.net) 🤘
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Usage
|
||||
## 🚀 Quick Start
|
||||
|
||||
- Make sure to use Node.js 20 or above
|
||||
- Run the following commands:
|
||||
### With Docker
|
||||
|
||||
```ssh
|
||||
``` bash
|
||||
docker pull ghcr.io/orangecoding/fredy:master
|
||||
docker create --name fredy -v /path/to/your/conf/:/conf -p 9998:9998 fredy/fredy
|
||||
docker start fredy
|
||||
```
|
||||
|
||||
Logs:
|
||||
|
||||
``` bash
|
||||
docker logs fredy -f
|
||||
```
|
||||
|
||||
### Manual (Node.js)
|
||||
|
||||
- Requirement: **Node.js 20 or higher**
|
||||
- Install dependencies and start:
|
||||
|
||||
``` bash
|
||||
yarn
|
||||
yarn run start:backend
|
||||
yarn run start:frontend
|
||||
yarn run start:backend # in one terminal
|
||||
yarn run start:frontend # in another terminal
|
||||
```
|
||||
|
||||
_Fredy_ will start with the default port, set to `9998`. You can access _Fredy_ by opening your browser at `http://localhost:9998`. The default login is `admin`, both for username and password. You should change the password as soon as possible when you plan to run Fredy on a server.
|
||||
👉 Open <http://localhost:9998>
|
||||
|
||||
<p align="center">
|
||||
<img alt="Job Configuration" src="https://github.com/orangecoding/fredy/blob/master/doc/screenshot1.png" width="30%">
|
||||
|
||||
<img alt="Job Analytics" src="https://github.com/orangecoding/fredy/blob/master/doc/screenshot_2.png" width="30%">
|
||||
|
||||
<img alt="Job Overview" width="30%" src="https://github.com/orangecoding/fredy/blob/master/doc/screenshot_3.png">
|
||||
</p>
|
||||
**Default Login:**
|
||||
- Username: `admin`
|
||||
- Password: `admin`
|
||||
|
||||
## Understanding the fundamentals
|
||||
------------------------------------------------------------------------
|
||||
|
||||
There are 3 important parts in Fredy, that you need to understand to leverage the full power of _Fredy_.
|
||||
## 📸 Screenshots
|
||||
|
||||
#### Provider
|
||||
| Job Configuration | Job Analytics | Job Overview |
|
||||
|-------------------|--------------|--------------|
|
||||
|  |  |  |
|
||||
|
||||
_Fredy_ supports multiple services. Immonet, Immowelt and Ebay are just a few examples. Those services are called providers within _Fredy_. When creating a new job, you can choose one or more providers.
|
||||
A provider contains the URL that points to the search results for the respective service. If you go to immonet.de and search for something, the displayed URL in the browser is what the provider needs to do its magic.
|
||||
**It is important that you order the search results by date, so that _Fredy_ always picks the latest results first!**
|
||||
------------------------------------------------------------------------
|
||||
|
||||
#### Adapter
|
||||
## 🧩 Core Concepts
|
||||
|
||||
_Fredy_ supports multiple adapters, such as Slack, SendGrid, Telegram etc. A search job can have as many adapters as supported by _Fredy_. Each adapter needs different configuration values, which you have to provide when using them. An adapter dictates how the frontend renders by telling the frontend what information it needs in order to send listings to the user.
|
||||
Fredy is built around three simple concepts:
|
||||
|
||||
#### Jobs
|
||||
### Provider 🌐
|
||||
|
||||
A Job wraps adapters and providers. _Fredy_ runs the configured jobs in a specific interval (can be configured in `/conf/config.json`).
|
||||
A **provider** is a real-estate platform (e.g. ImmoScout24, Immowelt,
|
||||
Immonet, eBay Kleinanzeigen, WG-Gesucht).\
|
||||
When you create a job, you paste the search URL from the platform into
|
||||
Fredy.\
|
||||
⚠️ Always make sure the search results are sorted by **date**, so Fredy
|
||||
picks up the newest listings first.
|
||||
|
||||
## Creating your first job
|
||||
### Adapter 📡
|
||||
|
||||
To create your first job, click on the button "Create New Job" on the job table. The job creation dialog should be self-explanatory, however there is one important thing.
|
||||
When configuring providers, before copying the URL from your browser, make sure that you have sorted the results by date to make sure _Fredy_ always picks the latest results first.
|
||||
An **adapter** is the channel through which Fredy notifies you (Slack,
|
||||
Telegram, Email, ntfy, ...).\
|
||||
Each adapter has its own configuration (e.g. API keys, webhook URLs).\
|
||||
You can use multiple adapters at once --- Fredy will send new listings
|
||||
through all of them.
|
||||
|
||||
## User management
|
||||
### Job 📅
|
||||
|
||||
As an administrator, you can create, edit and remove users from _Fredy_. Be careful, each job is connected to the user that has created the job. If you remove the user, their jobs will also be removed.
|
||||
A **job** combines providers and adapters.\
|
||||
Example: "Search apartments on ImmoScout24 + Immowelt and send results
|
||||
to Slack + Telegram."\
|
||||
Jobs run automatically at the interval you configure (see
|
||||
`/conf/config.json`).
|
||||
|
||||
# Development
|
||||
------------------------------------------------------------------------
|
||||
|
||||
### Running Fredy in development mode
|
||||
## Immoscout
|
||||
|
||||
Start the backend with:
|
||||
Immoscout has implemented advanced bot detection. In order to work around this, we are using a reversed engineered version of their mobile api. See [Immoscout Reverse Engineering Documentation](https://github.com/orangecoding/fredy/blob/master/reverse-engineered-immoscout.md)
|
||||
|
||||
```shell
|
||||
## Analytics
|
||||
|
||||
Fredy is completely free (and will always remain free). However, it would be a huge help if you’d allow me to collect some analytical data.
|
||||
Before you freak out, let me explain...
|
||||
If you agree, Fredy will send a ping to my Mixpanel project each time it runs.
|
||||
The data includes: names of active adapters/providers, OS, architecture, Node version, and language. The information is entirely anonymous and helps me understand which adapters/providers are most frequently used.</p>
|
||||
|
||||
**Thanks**🤘
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### Development Mode
|
||||
|
||||
``` bash
|
||||
yarn run start:backend:dev
|
||||
```
|
||||
|
||||
For the frontend, run:
|
||||
|
||||
```shell
|
||||
yarn run start:frontend:dev
|
||||
```
|
||||
|
||||
You should now be able to access _Fredy_ from your browser. Check your Terminal to see what port the frontend is running on.
|
||||
|
||||
### Running Tests
|
||||
### Run Tests
|
||||
|
||||
To run the tests, run
|
||||
|
||||
```shell
|
||||
``` bash
|
||||
yarn run test
|
||||
```
|
||||
|
||||
# Architecture
|
||||
------------------------------------------------------------------------
|
||||
|
||||
```mermaid
|
||||
## 📐 Architecture
|
||||
|
||||
``` mermaid
|
||||
flowchart TD
|
||||
subgraph Jobs["Jobs"]
|
||||
A1["Job 1"]
|
||||
@@ -109,80 +166,38 @@ flowchart TD
|
||||
C3["Provider 3"]
|
||||
end
|
||||
subgraph NotificationAdapters["Notification Adapters"]
|
||||
F1["Notification Adapter 1"]
|
||||
F2["Notification Adapter 2"]
|
||||
F1["Adapter 1"]
|
||||
F2["Adapter 2"]
|
||||
end
|
||||
|
||||
A1 --> B["FredyRuntime"]
|
||||
A2 --> B
|
||||
A3 --> B
|
||||
B --> C1 & C2 & C3
|
||||
C1 --> D["Similarity-Check"]
|
||||
C1 --> D["Similarity Check"]
|
||||
C2 --> D
|
||||
C3 --> D
|
||||
D --> E{"Found<br>similarity?"}
|
||||
D --> E{"Duplicate?"}
|
||||
E -- No --> F1
|
||||
F1 --> F2
|
||||
|
||||
style A1 fill:#fde9a0,stroke:#333333,color:#333333
|
||||
style A2 fill:#fde9a0,stroke:#333333,color:#333333
|
||||
style A3 fill:#fde9a0,stroke:#333333,color:#333333
|
||||
style C1 fill:#c4c9f1,stroke:#333333,color:#333333
|
||||
style C2 fill:#c4c9f1,stroke:#333333,color:#333333
|
||||
style C3 fill:#c4c9f1,stroke:#333333,color:#333333
|
||||
style F1 fill:#d2edba,stroke:#333333,color:#333333
|
||||
style F2 fill:#d2edba,stroke:#333333,color:#333333
|
||||
style B fill:#abd8f9,stroke:#333333,color:#333333
|
||||
style D fill:#fab4a8,stroke:#333333,color:#333333
|
||||
style E fill:#fffbb4,stroke:#333333,color:#333333
|
||||
```
|
||||
|
||||
### Immoscout
|
||||
------------------------------------------------------------------------
|
||||
|
||||
Immoscout has implemented advanced bot detection. In order to work around this, we are using a reversed engineered version of their mobile api. See [Immoscout Reverse Engineering Documentation](https://github.com/orangecoding/fredy/blob/master/reverse-engineered-immoscout.md)
|
||||
## 👐 Contributing
|
||||
|
||||
# Analytics
|
||||
Thanks to everyone who has contributed!
|
||||
|
||||
Fredy is completely free (and will always remain free). However, it would be a huge help if you’d allow me to collect some analytical data.
|
||||
Before you freak out, let me explain...
|
||||
If you agree, Fredy will send a ping to my Mixpanel project each time it runs.
|
||||
The data includes: names of active adapters/providers, OS, architecture, Node version, and language. The information is entirely anonymous and helps me understand which adapters/providers are most frequently used.</p>
|
||||
**Thanks**🤘
|
||||
`<a href="https://github.com/orangecoding/fredy/graphs/contributors">`{=html}
|
||||
`<img src="https://contrib.rocks/image?repo=orangecoding/fredy" />`{=html}
|
||||
`</a>`{=html}
|
||||
|
||||
# Docker
|
||||
See the [Contributing
|
||||
Guide](https://github.com/orangecoding/fredy/blob/master/CONTRIBUTING.md).
|
||||
|
||||
Use the Dockerfile in this repository to build an image.
|
||||
------------------------------------------------------------------------
|
||||
|
||||
Example: `docker build -t fredy/fredy /path/to/your/Dockerfile`
|
||||
## ⭐ Star History
|
||||
|
||||
Or use docker-compose:
|
||||
|
||||
Example `docker-compose build`
|
||||
|
||||
Or use the container that will be built automatically.
|
||||
|
||||
`docker pull ghcr.io/orangecoding/fredy:master`
|
||||
|
||||
## Create & run a container
|
||||
|
||||
Put your config.json into a path of your choice, such as `/path/to/your/conf/`.
|
||||
|
||||
Example: `docker create --name fredy -v /path/to/your/conf/:/conf -p 9998:9998 fredy/fredy`
|
||||
|
||||
## Logs
|
||||
|
||||
You can browse the logs with `docker logs fredy -f`.
|
||||
|
||||
### 👐 Contributing
|
||||
|
||||
Thanks to all the people who already contributed!
|
||||
|
||||
<a href="https://github.com/orangecoding/fredy/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=orangecoding/fredy" />
|
||||
</a>
|
||||
|
||||
See [Contributing](https://github.com/orangecoding/fredy/blob/master/CONTRIBUTING.md)
|
||||
|
||||
## Star History
|
||||
|
||||
[](https://www.star-history.com/#orangecoding/fredy&Date)
|
||||
[](https://www.star-history.com/#orangecoding/fredy&Date)
|
||||
|
||||
@@ -1 +1 @@
|
||||
{"interval":"60","port":9998,"workingHours":{"from":"","to":""},"demoMode":false,"analyticsEnabled":false}
|
||||
{"interval":"60","port":9998,"workingHours":{"from":"","to":""},"demoMode":false,"analyticsEnabled":null}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "fredy",
|
||||
"version": "11.5.0",
|
||||
"version": "11.5.1",
|
||||
"description": "[F]ind [R]eal [E]states [d]amn eas[y].",
|
||||
"scripts": {
|
||||
"prepare": "husky",
|
||||
@@ -11,7 +11,7 @@
|
||||
"build:frontend": "vite build",
|
||||
"format": "prettier --write \"**/*.js\"",
|
||||
"format:check": "prettier --check \"**/*.js\"",
|
||||
"test": "mocha --loader=esmock --timeout 60000 test/**/*.test.js",
|
||||
"test": "node --import ./test/esmock-loader.mjs ./node_modules/mocha/bin/mocha.js --timeout 60000 test/**/*.test.js",
|
||||
"lint": "eslint .",
|
||||
"lint:fix": "yarn lint --fix"
|
||||
},
|
||||
@@ -59,6 +59,7 @@
|
||||
"@rematch/loading": "2.1.2",
|
||||
"@sendgrid/mail": "8.1.5",
|
||||
"@visactor/react-vchart": "^2.0.4",
|
||||
"@visactor/vchart": "^2.0.4",
|
||||
"@visactor/vchart-semi-theme": "^1.12.2",
|
||||
"@vitejs/plugin-react": "5.0.2",
|
||||
"better-sqlite3": "^12.2.0",
|
||||
@@ -75,7 +76,7 @@
|
||||
"node-mailjet": "6.0.9",
|
||||
"p-throttle": "^8.0.0",
|
||||
"package-up": "^5.0.0",
|
||||
"puppeteer": "^24.18.0",
|
||||
"puppeteer": "^24.19.0",
|
||||
"puppeteer-extra": "^3.3.6",
|
||||
"puppeteer-extra-plugin-stealth": "^2.11.2",
|
||||
"query-string": "9.2.2",
|
||||
|
||||
4
test/esmock-loader.mjs
Normal file
4
test/esmock-loader.mjs
Normal file
@@ -0,0 +1,4 @@
|
||||
import { register } from 'node:module';
|
||||
import { pathToFileURL } from 'node:url';
|
||||
|
||||
register('esmock', pathToFileURL('./'));
|
||||
32
yarn.lock
32
yarn.lock
@@ -1754,7 +1754,7 @@
|
||||
resolved "https://registry.yarnpkg.com/@visactor/vchart-theme-utils/-/vchart-theme-utils-1.12.2.tgz#bad0035e79dabbe80890bbd6196668551a12c874"
|
||||
integrity sha512-PkgSAivtUZukCWVUGCXxKcbTzI/oMj1Ky22VYcVs/KM4VFmmCywU2xjBBe1du0LUey6CAKB7bMlj5bL2jctG0A==
|
||||
|
||||
"@visactor/vchart@2.0.4":
|
||||
"@visactor/vchart@2.0.4", "@visactor/vchart@^2.0.4":
|
||||
version "2.0.4"
|
||||
resolved "https://registry.yarnpkg.com/@visactor/vchart/-/vchart-2.0.4.tgz#36770240ae6ffd84fa285b7610192f2e06a56299"
|
||||
integrity sha512-/NWBQFYd5A52I8Bkp+iod2LAhBo4cQcxt+xazrmJ/5L17Gk/LdUqCRpnF5dk3XncHb4ls+SRNGkH4kf0rNH2Mg==
|
||||
@@ -2860,10 +2860,10 @@ devlop@^1.0.0, devlop@^1.1.0:
|
||||
dependencies:
|
||||
dequal "^2.0.0"
|
||||
|
||||
devtools-protocol@0.0.1475386:
|
||||
version "0.0.1475386"
|
||||
resolved "https://registry.yarnpkg.com/devtools-protocol/-/devtools-protocol-0.0.1475386.tgz#5378401a2c5698ab68c3482c9b7816ff62ec652b"
|
||||
integrity sha512-RQ809ykTfJ+dgj9bftdeL2vRVxASAuGU+I9LEx9Ij5TXU5HrgAQVmzi72VA+mkzscE12uzlRv5/tWWv9R9J1SA==
|
||||
devtools-protocol@0.0.1495869:
|
||||
version "0.0.1495869"
|
||||
resolved "https://registry.yarnpkg.com/devtools-protocol/-/devtools-protocol-0.0.1495869.tgz#f68daef77a48d5dcbcdd55dbfa3265a51989c91b"
|
||||
integrity sha512-i+bkd9UYFis40RcnkW7XrOprCujXRAHg62IVh/Ah3G8MmNXpCGt1m0dTFhSdx/AVs8XEMbdOGRwdkR1Bcta8AA==
|
||||
|
||||
diff@^7.0.0:
|
||||
version "7.0.0"
|
||||
@@ -5984,15 +5984,15 @@ punycode@^2.1.0:
|
||||
resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.3.1.tgz#027422e2faec0b25e1549c3e1bd8309b9133b6e5"
|
||||
integrity sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==
|
||||
|
||||
puppeteer-core@24.18.0:
|
||||
version "24.18.0"
|
||||
resolved "https://registry.yarnpkg.com/puppeteer-core/-/puppeteer-core-24.18.0.tgz#444388d619de422f1d325b313942f46fa2925d96"
|
||||
integrity sha512-As0BvfXxek2MbV0m7iqBmQKFnfSrzSvTM4zGipjd4cL+9f2Ccgut6RvHlc8+qBieKHqCMFy9BSI4QyveoYXTug==
|
||||
puppeteer-core@24.19.0:
|
||||
version "24.19.0"
|
||||
resolved "https://registry.yarnpkg.com/puppeteer-core/-/puppeteer-core-24.19.0.tgz#038f5229b9910f5daf717d5aaff3b63228afbf6c"
|
||||
integrity sha512-qsEys4OIb2VGC2tNWKAs4U0mnjkIAxueMOOzk2nEFM9g4Y8QuvYkEMtmwsEdvzNGsUFd7DprOQfABmlN7WBOlg==
|
||||
dependencies:
|
||||
"@puppeteer/browsers" "2.10.8"
|
||||
chromium-bidi "8.0.0"
|
||||
debug "^4.4.1"
|
||||
devtools-protocol "0.0.1475386"
|
||||
devtools-protocol "0.0.1495869"
|
||||
typed-query-selector "^2.12.0"
|
||||
ws "^8.18.3"
|
||||
|
||||
@@ -6043,16 +6043,16 @@ puppeteer-extra@^3.3.6:
|
||||
debug "^4.1.1"
|
||||
deepmerge "^4.2.2"
|
||||
|
||||
puppeteer@^24.18.0:
|
||||
version "24.18.0"
|
||||
resolved "https://registry.yarnpkg.com/puppeteer/-/puppeteer-24.18.0.tgz#7bb2668b219fed4f23aa98ac1650766f4306b743"
|
||||
integrity sha512-Ke8oL/87GhzKIM2Ag6Yj49t5xbGc4rspGIuSuFLFCQBtYzWqCSanvqoCu08WkI78rbqcwnHjxiTH6oDlYFrjrw==
|
||||
puppeteer@^24.19.0:
|
||||
version "24.19.0"
|
||||
resolved "https://registry.yarnpkg.com/puppeteer/-/puppeteer-24.19.0.tgz#86cef2d1cc45066c9f5ed9edabf93b2d3b206eb3"
|
||||
integrity sha512-gUWgHX36m9K6yUbvNBEA7CXElIL92yXMoAVFrO8OpZkItqrruLVqYA8ikmfgwcw/cNfYgkt0n2+yP9jd9RSETA==
|
||||
dependencies:
|
||||
"@puppeteer/browsers" "2.10.8"
|
||||
chromium-bidi "8.0.0"
|
||||
cosmiconfig "^9.0.0"
|
||||
devtools-protocol "0.0.1475386"
|
||||
puppeteer-core "24.18.0"
|
||||
devtools-protocol "0.0.1495869"
|
||||
puppeteer-core "24.19.0"
|
||||
typed-query-selector "^2.12.0"
|
||||
|
||||
qs@^6.14.0:
|
||||
|
||||
Reference in New Issue
Block a user