prehistoric-systems/FilterLists
1
0
Fork 0
mirror of https://github.com/collinbarrett/FilterLists.git synced 2026-03-11 09:04:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(readme): 📃 update README

Browse source
This commit is contained in:
Collin M. Barrett 2020-09-07 15:11:47 -05:00
parent 7727d70d2a
commit c7feed1643
1 changed files with 6 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
.github/README.md vendored
View file

@ -27,11 +27,11 @@
# Background
FilterLists helps to protect your privacy and security when using the internet. It provides a comprehensive directory of subscription lists to block advertisements, malware, trackers, and other general annoyances. First, install one of the [software tools](https://github.com/collinbarrett/FilterLists/blob/master/data/Software.json) that supports these lists. Then, you can subscribe to a set of these lists inside of that software. If you need help or have a comment/question, open an [Issue](https://github.com/collinbarrett/FilterLists/issues).
FilterLists helps to protect your privacy and security when using the internet. It provides a comprehensive directory of subscription lists to block advertisements, malware, trackers, and other general annoyances. First, install one of the software tools that supports these lists. Then you can subscribe to a set of these lists inside of that software. If you need help or have a comment/question, open an [Issue](https://github.com/collinbarrett/FilterLists/issues).
Using a software firewall or adblocker has become a key tool in protecting one's privacy online. While the current business model of the "free" internet relies upon advertising revenue, publishers have become too flippant about tracking users without their consent. Advertising networks track users' browsing habits around the internet building lucrative profiles to exploit for targeted marketing or big data research. Until internet publishers develop more transparency or a new business model, we must continue to take the protection of our privacy into our hands.
Typical adblockers run as an extension in popular web browsers. As we browse the internet, they compare HTTP requests to their list of hosts and filters to selectively block advertisements, trackers, and malware. This filtering helps to protect the surfer's privacy, prevents [malvertising attacks](http://www.wired.com/insights/2014/11/malvertising-is-cybercriminals-latest-sweet-spot/ "Why Malvertising Is Cybercriminals' Latest Sweet Spot - Wired"), and [reduces bandwidth requirements](http://venturebeat.com/2015/07/08/blocking-ads-can-cut-network-traffic-25-to-40-study-shows/ "Blocking Ads Can Cut Network Traffic 25% to 40%, Study Shows - VentureBeat"). Thousands of contributors work hard to maintain these FilterLists for anyone to use. Locating and selecting these lists, however, has not historically been very easy. This project aims to solve that problem.
Typical adblockers run as an extension in popular web browsers. As we browse the internet, they compare HTTP requests to their list of hosts and filters to selectively block advertisements, trackers, and malware. This filtering helps to protect the surfer's privacy, prevents [malvertising attacks](http://www.wired.com/insights/2014/11/malvertising-is-cybercriminals-latest-sweet-spot/ "Why Malvertising Is Cybercriminals' Latest Sweet Spot - Wired"), and [reduces bandwidth requirements](http://venturebeat.com/2015/07/08/blocking-ads-can-cut-network-traffic-25-to-40-study-shows/ "Blocking Ads Can Cut Network Traffic 25% to 40%, Study Shows - VentureBeat"). Thousands of contributors work hard to maintain these FilterLists for anyone to use. Locating and selecting these lists, however, has not historically been very easy. This project was launched in 2015 to solve that problem.
# Contributing
@ -39,11 +39,11 @@ Typical adblockers run as an extension in popular web browsers. As we browse the
<a href="https://hub.filterlists.com"><img alt="Discourse posts" src="https://img.shields.io/discourse/https/hub.filterlists.com/posts.svg"></a>
Check out the <a href="https://hub.filterlists.com">FilterLists Hub</a>, a place for discussing how to write rules, maintain FilterLists, and chat about the state of the adblocking community.
Check out the <a href="https://hub.filterlists.com">FilterLists Hub</a>, a forum for discussing how to write rules, maintain FilterLists, and chat about the state of the adblocking community.
## Adding or Updating Lists
To submit a new list or update data about an existing list, please submit a pull request to [data](https://github.com/collinbarrett/FilterLists/tree/master/data) in conjunction with the data model described [here](https://github.com/collinbarrett/FilterLists/wiki/Data-Model_sidebar). Once you open the pull request, our [Migrate bot](https://github.com/collinbarrett/FilterLists/blob/master/server/azure-pipelines.migrate.yaml) will create an [Entity Framework Core migration](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/?tabs=dotnet-core-cli) with your changes and test them. Please ensure to [grant the bot permissions to push to your pull request branch](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
To submit a new list or update data about an existing list, please submit a pull request to [data](https://github.com/collinbarrett/FilterLists/tree/master/services/directory/data) in conjunction with the data model described [here](https://github.com/collinbarrett/FilterLists/wiki/Data-Model_sidebar). Once you open the pull request, our [Migrate bot](https://github.com/collinbarrett/FilterLists/blob/master/services/directory/azure-pipelines.migrate.yaml) will create an [Entity Framework Core migration](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/?tabs=dotnet-core-cli) with your changes and test them. Please ensure to [grant the bot permissions to push to your pull request branch](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
Alternatively, you can [open a new issue](https://github.com/collinbarrett/FilterLists/issues/new) providing information for all of the fields described in the [data model](https://github.com/collinbarrett/FilterLists/wiki/Data-Model_sidebar).
@ -60,61 +60,7 @@ We have containerized FilterLists to make it as easy as possible for contributer
1. Install Docker CE for your computer's operating system. [Docs](https://docs.docker.com/install/)
2. Clone the FilterLists git repository to your computer. [Docs](https://help.github.com/en/articles/cloning-a-repository)
3. Navigate to the root directory of your locally cloned FilterLists git repository in a command-line interface.
4. Execute `docker-compose up`. (Optionally, include the `-d` flag to launch in [detached mode](https://docs.docker.com/compose/reference/up/).)
5. After a minute or so, visit the locally running version of FilterLists in a web browser at `http://localhost/`.
### Configuration
The `appsettings*.json` files are only used when debugging in Visual Studio outside of Docker ([they are not copied into the built runtime images](https://github.com/collinbarrett/FilterLists/blob/e6ac3da26ea44174795fbaa400def14c537c22b8/.dockerignore#L33)). When running any of the projects in containers via Docker/Docker Compose, the configuration is passed in as environment variables configured in [`.env`](https://github.com/collinbarrett/FilterLists/blob/master/.env) and `docker-compose*.yml` files.
### Testing changes to the data (.json files)
To validate that your changes to the data are valid and supported by the FilterLists API, just open a pull request and validate that the Migrate bot check is successful. [See Adding or Updating Lists](#adding-or-updating-lists).
### Testing changes to the `Api`, `Services`, or `Data` projects
#### Automated
- To run `FilterLists.Services.Tests`:
`docker volume create test-services-results && docker-compose -f docker-compose.services.tests.yml build api && docker-compose -p test-services -f docker-compose.services.tests.yml run --rm api`
- To run `FilterLists.Data.Tests`:
`docker volume create test-data-results && docker-compose -p test-data -f docker-compose.data.tests.yml down -v && docker-compose -f docker-compose.data.tests.yml build api && docker-compose -p test-data -f docker-compose.data.tests.yml run --rm api`
#### Manual
1. Execute `docker-compose up -d --build api`.
2. Verify your changes are properly reflected at `http://localhost/api`.
### Testing changes to the `Web` project
1. Execute `docker-compose up -d --build web`.
2. Verify your changes are properly reflected at `http://localhost/`.
### Testing changes to the `Agent` project
The Agent takes the following command line arguments:
- `-a` Archive copies of all lists in a git repository.
- `-c` Validate all URLs in the FilterLists database.
#### Automated
- To run `FilterLists.Agent.Tests`:
`docker volume create test-agent-results && docker-compose -f docker-compose.agent.tests.yml build agent && docker-compose -p test-agent -f docker-compose.agent.tests.yml run --rm agent`
#### Manual
1. Execute `docker-compose build agent && docker-compose run agent [-c] [-v]` (don't include the square brackets, they indicate optional command line arguments).
2. Verify your changes are properly reflected in the console logger.
### Debugging
1. Execute `docker container ls -a` to find the `CONTAINER ID` of the container in question.
2. Execute `docker logs [CONTAINER ID]` replacing `[CONTAINER ID]` with the hash from step 1 to view the logs from that container.
4. TBD...
# Acknowledgements
@ -135,11 +81,9 @@ We respect your privacy. That is the whole point of this project. The only minor
- [GitHub](https://help.github.com/articles/github-privacy-statement/)
- [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/organizations/security/data-protection?view=azure-devops)
- [Docker Hub](https://www.docker.com/legal/docker-privacy-policy)
- [DigitalOcean](https://www.digitalocean.com/legal/privacy-policy/)
- [Application Insights](https://docs.microsoft.com/en-us/azure/application-insights/app-insights-data-retention-privacy)
- [Cloudflare](https://www.cloudflare.com/analytics/)
## Internet Explorer
FilterLists does not support Internet Explorer. To view a smaller, TPL-only archive with subscribable links, visit [this page](https://raw.githack.com/collinbarrett/FilterLists/master/data/TPLSubscriptionAssistant.html).
FilterLists does not support Internet Explorer. See [this page](https://filterlists.com/tpl.html) for a small archive of Tracking Protection Lists for Internet Explorer.