diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..347d3c9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,22 @@ +# Contributing + +Feel free to open an issue or create a pull request at any time. If you do not know what can be done, here is a list of +ideas in no particular order. + +- [ ] Improve testing. Everything, besides the login, is untested at the moment. +- [ ] Allow continuation from a saved file. It would be helpful for long-running tasks if the account was flagged during the process. +- [ ] Allow the use of multiple accounts at the same time to reduce the impact of Instagram's rate limit. +- [ ] Make the tool cloud-native-ready. The required requests are already in a queue, which could be used for it. +- [ ] Improve error handling. There are still a few cases where the tool crashes without saving the current state to disk. +- [ ] Improve visualization performance. Currently, [D3.js](https://d3js.org/) is really struggling with large data sets. + +## Tests + +Tests are written with [Jest](https://jestjs.io/). Run them via + +``` +npm run test +``` + +If you want to an IDE like [Webstorm](https://www.jetbrains.com/webstorm/) to run them, make sure to enable +[ECMAScript Module support](https://jestjs.io/docs/ecmascript-modules) by setting `--experimental-vm-modules`. diff --git a/README.md b/README.md index 40eef51..125441b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,16 @@ -## Getting started +# Insta(nt)-Graph -Install [Node.js](https://nodejs.org/) on your system. Then install the project dependencies via +A tool to create a visual representation how accounts are following each other on [Instagram](https://instagram.com). + +![An example of the visual representation](./example-graph.png) + +**NOTE: THIS TOOL IS NOT ASSOCIATED OR ENDORSED BY INSTAGRAM OR META. USE AT YOUR OWN RISK.** + +## Usage + +Make sure [Node.js >= v20.x](https://nodejs.org/) is installed on your system. + +Download or clone this repository on your machine. Then install the project dependencies via ``` npm install @@ -12,11 +22,34 @@ To compile and run the program use npm run cli ``` -Tests are written with [Jest](https://jestjs.io/). Run them via +The result will be stored in a JSON file. Additionally, an interactive visualization is generated as a single HTML file, +which can be viewed in any modern Browser. The tool will stop early if it receives an `SIGINT`-Signal (when pressing +`CTRL+C` for example) and create the output for the current state. -``` -npm run test -``` +### Options + +| Name | Description | Default value | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| +| Session ID | The session ID used by Instagram to authenticate the user. It can be attained either by logging in via the tool or through the data stored by the official Instagram web app. | +| Root account | The account from which the graph generation should start. | | +| Generations | The distance between the root account and the current user. It is defined by the number of accounts between them. Generation 0, therefor, only includes the root account. | 1 | +| Maximal follower count | Maximum amount of followers to fetch for each account. If more followers are over-fetched, they will be included but not further queried. It also applies to the followed accounts. | 250 | +| Include following | Also fetch the accounts are followed by an account, not only their followers. | Yes | + +### Handling of errors and Instagram's rate limits + +To not be flagged as automated behaviour, the tool needs to pause for a while after retrieving a lot of followers. The +tool will output the current state in the meanwhile. + +Also, if an error occurs, the tool will try to output the current state. This might fail if the error is unhandled. + +### Running the tool on a VPS + +If you wish to run this tool on a VPS due to its long-running nature, you may be unable to use the login functionality +of this +tool as captchas are not handled. -If you want to an IDE like [Webstorm](https://www.jetbrains.com/webstorm/) to run them, make sure to enable -[ECMAScript Module support](https://jestjs.io/docs/ecmascript-modules) by setting `--experimental-vm-modules`. +Another issue you might run into is Node.js running out of memory if your VPS does not have an adequate amount of RAM. +To +work around this, you enable SWAP within your VPS and explicitly allow Node.js to use more memory via +[`--max-old-space-size`](https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-megabytes). diff --git a/example-graph.png b/example-graph.png new file mode 100644 index 0000000..dc83b84 Binary files /dev/null and b/example-graph.png differ diff --git a/package.json b/package.json index 2a403ca..a8b359f 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { - "name": "my-webpack-project", + "name": "dhbw-web2", "version": "1.0.0", - "description": "My webpack project", + "description": "A tool to create a visual representation how accounts are following each other on Instagram.", "private": true, "scripts": { "precli": "webpack --mode=production --node-env=production",