From d8568c06e952a0523d704dc30a9df04bc92784ce Mon Sep 17 00:00:00 2001 From: Renan Bernordi Date: Wed, 29 Jan 2025 21:23:41 -0300 Subject: [PATCH] =?UTF-8?q?revis=C3=A3o=20dos=20readmes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.en.md | 142 +++++++++++++++++++++++---------------------------- README.md | 104 +++++++++++++++++-------------------- 2 files changed, 111 insertions(+), 135 deletions(-) diff --git a/README.en.md b/README.en.md index ffd17e1..55e49e6 100644 --- a/README.en.md +++ b/README.en.md @@ -7,43 +7,34 @@ [![Stars](https://img.shields.io/github/stars/manualdousuario/marreta)](https://github.com/manualdousuario/marreta/stargazers) [![Issues](https://img.shields.io/github/issues/manualdousuario/marreta)](https://github.com/manualdousuario/marreta/issues) -Marreta is a tool that removes access barriers and visual distractions! +Marreta is a tool that breaks access barriers and elements that hinder reading! ![Before and after Marreta](https://github.com/manualdousuario/marreta/blob/main/screen.en.png?raw=true) Public instance at [marreta.pcdomanual.com](https://marreta.pcdomanual.com)! -## ✨ Features +## ✨ What's cool about it? -- Automatically cleans and fixes URLs +- Cleans and corrects URLs automatically - Removes annoying tracking parameters - Forces HTTPS to keep everything secure -- Changes user agent to avoid blocks -- Smart DNS -- Keeps HTML clean and optimized -- Fixes relative URLs automatically -- Allows custom styles +- Changes user agent to avoid blockages +- Leaves the HTML clean and optimized +- Fixes relative URLs on its own +- Allows you to put your own styles and scripts - Removes unwanted elements - Cache, cache! - Blocks domains you don't want -- Allows custom headers and cookies configuration -- Everything with SSL/TLS -- PHP-FPM -- OPcache enabled -- Direct sharing via PWA on Chrome on Android +- Allows you to configure headers and cookies your way +- PHP-FPM and OPcache -## 🐳 Docker +## 🐳 Installing with Docker -### Prerequisites - -You only need: -- Docker and docker compose - -### Production +Install Docker and Docker Compose `curl -o ./docker-compose.yml https://raw.githubusercontent.com/manualdousuario/marreta/main/docker-compose.yml` -If needed +Now modify it with your settings: `nano docker-compose.yml` @@ -61,54 +52,16 @@ services: ``` - `SITE_NAME`: Your Marreta's name -- `SITE_DESCRIPTION`: Tell what it's for -- `SITE_URL`: Where it will run, full address with `https://`. If you change the port in docker-compose (e.g., 8080:80), you must also include the port in SITE_URL (e.g., https://yoursite:8080) +- `SITE_DESCRIPTION`: What it's for +- `SITE_URL`: Where it will run, complete address with `https://`. If you change the port in docker-compose (e.g. 8080:80), you must also include the port in SITE_URL (e.g. https://yoursite:8080) - `DNS_SERVERS`: Which DNS servers to use `1.1.1.1, 8.8.8.8` -- `SELENIUM_HOST`: Selenium host server:PORT (e.g., selenium-hub:4444) +- `SELENIUM_HOST`: Selenium host server:PORT (e.g. selenium-hub:4444) Now you can run `docker compose up -d` -#### Development - -1. First, clone the project: -```bash -git clone https://github.com/manualdousuario/marreta/ -cd marreta -``` - -2. Create the configuration file: -```bash -cp app/.env.sample app/.env -``` - -3. Configure it your way in `app/.env`: -```env -SITE_NAME="Marreta" -SITE_DESCRIPTION="Paywall hammer!" -SITE_URL=http://localhost -DNS_SERVERS=1.1.1.1,8.8.8.8 -LOG_LEVEL=WARNING -SELENIUM_HOST=selenium-hub:4444 -LANGUAGE=pt-br -``` - -4. Web Service: Use `default.conf` as the base for NGINX or point your webservice to `app/` - -## ⚙️ Customization - -The configurations are organized in `data/`: - -- `domain_rules.php`: Site-specific rules -- `global_rules.php`: Rules that apply to all sites -- `blocked_domains.php`: List of blocked sites - -### Translations - -- `/languages/`: Each language is in its ISO id (`pt-br, en, es or de-de`) and can be defined in the `LANGUAGE` environment - ### S3 Cache -Cache storage support in S3. Configure the following variables in your `.env`: +Support for cache storage in S3. Configure the following variables in your `.env`: ```env S3_CACHE_ENABLED=true @@ -146,7 +99,7 @@ S3_ACL=private ### Selenium Integration -Selenium integration for processing websites that require javascript or have more advanced protection barriers. To use this functionality, you need to set up a Selenium environment with Firefox. Add the following configuration to your `docker-compose.yml`: +Integration with Selenium allows processing sites that require JavaScript or have some more advanced protection barriers. To use this feature, you need to set up a Selenium environment with Firefox. Add the following configuration to your `docker-compose.yml`: ```yaml services: @@ -182,14 +135,53 @@ services: Important settings: - `shm_size`: Sets the shared memory size for Firefox (2GB recommended) - `SE_NODE_MAX_SESSIONS`: Maximum number of concurrent sessions per node -- `GRID_MAX_SESSION`: Maximum number of concurrent sessions in the hub +- `GRID_MAX_SESSION`: Maximum number of concurrent sessions on the hub - `GRID_BROWSER_TIMEOUT` and `GRID_TIMEOUT`: Timeouts in seconds -After setting up Selenium, make sure to set the `SELENIUM_HOST` variable in your environment to point to the Selenium hub (typically `selenium-hub:4444`). +After configuring Selenium, make sure to set the `SELENIUM_HOST` variable in your environment to point to the Selenium hub (usually `selenium-hub:4444`). + +## Development + +1. First, clone the project: +```bash +git clone https://github.com/manualdousuario/marreta/ +cd marreta/app +``` + +2. Install the project dependencies: +```bash +composer install +npm install +``` + +3. Create the configuration file: +```bash +cp .env.sample .env +``` + +4. Configure the environment variables in `.env` + +5. Use the `default.conf` as a base for NGINX or point your webservice to `app/` + +Gulp is used to compile Sass to CSS, minify JavaScript, use: `gulp` + +### ⚙️ Customizing + +The settings are organized in `data/`: + +- `domain_rules.php`: Specific rules for each site +- `global_rules.php`: Rules that apply to all sites +- `blocked_domains.php`: List of blocked sites + +### Translations + +- `/languages/`: Each language is in its ISO id (`pt-br, en, es or de-de`) and can be defined in the environment `LANGUAGE` + +## 🛠️ Maintenance ### Logging System -Logs are stored in `app/logs/*.log` with automatic 7-day rotation. +Logs are stored in `app/logs/*.log` with automatic rotation every 7 days. Log settings available in `.env` or docker: @@ -199,16 +191,12 @@ LOG_LEVEL=WARNING Available log levels: - DEBUG: Detailed information for debugging -- INFO: General operational information +- INFO: General information about operations - WARNING: Warnings that deserve attention (default) -- ERROR: Errors that don't stop operation +- ERROR: Errors that do not interrupt operation - CRITICAL: Critical errors that need immediate attention -## 🛠️ Maintenance - -### Logs - -View application logs: +View the application logs: ```bash docker-compose logs app # or directly from the log file @@ -228,13 +216,13 @@ docker-compose exec app rm -rf /app/cache/* - 🦊 **Firefox**: Extension by [Clarissa Mendes](https://claromes.com/pages/whoami) - [Download](https://addons.mozilla.org/pt-BR/firefox/addon/marreta/) | [Source Code](https://github.com/manualdousuario/marreta-extensao) - 🌀 **Chrome**: Extension by [Clarissa Mendes](https://claromes.com/pages/whoami) - [Download](https://chromewebstore.google.com/detail/marreta/ipelapagohjgjcgpncpbmaaacemafppe) | [Source Code](https://github.com/manualdousuario/marreta-extensao) - 🦋 **Bluesky**: Bot by [Joselito](https://bsky.app/profile/joseli.to) - [Profile](https://bsky.app/profile/marreta.pcdomanual.com) | [Source Code](https://github.com/manualdousuario/marreta-bot) -- 🍎 **Apple**: [Shortcuts](https://www.icloud.com/shortcuts/3594074b69ee4707af52ed78922d624f) integration +- 🍎 **Apple**: Integration with [Shortcuts](https://www.icloud.com/shortcuts/3594074b69ee4707af52ed78922d624f) --- -Made with ❤️! If you have questions or suggestions, open an issue and we'll help! 😉 +Made with ❤️! If you have any questions or suggestions, open an issue and we'll help! 😉 -Thanks to the project [https://github.com/burlesco/burlesco](Burlesco) and [https://github.com/nang-dev/hover-paywalls-browser-extension/](Hover) which was used as a basis for several rules! +Thanks to the [https://github.com/burlesco/burlesco](Burlesco) and [https://github.com/nang-dev/hover-paywalls-browser-extension/](Hover) projects that served as the basis for several rules! ## Star History diff --git a/README.md b/README.md index e1b6c19..6c03428 100644 --- a/README.md +++ b/README.md @@ -15,35 +15,26 @@ Instancia publica em [marreta.pcdomanual.com](https://marreta.pcdomanual.com)! ## ✨ O que tem de legal? -- Limpa e arruma URLs automaticamente +- Limpa e corrige URLs automaticamente - Remove parâmetros chatos de rastreamento - Força HTTPS pra manter tudo seguro - Troca de user agent pra evitar bloqueios -- DNS esperto - Deixa o HTML limpinho e otimizado - Conserta URLs relativas sozinho -- Permite colocar seus próprios estilos +- Permite colocar seus próprios estilos e scripts - Remove elementos indesejados - Cache, cache! - Bloqueia domínios que você não quer - Permite configurar headers e cookies do seu jeito -- Tudo com SSL/TLS -- PHP-FPM -- OPcache ligado -- Compartilhamento direto via PWA no Chrome do Android +- PHP-FPM e OPcache -## 🐳 Docker +## 🐳 Instalando em Docker -### Antes de começar - -Só precisa ter instalado: -- Docker e docker compose - -### Produção +Instale Docker e Docker Compose `curl -o ./docker-compose.yml https://raw.githubusercontent.com/manualdousuario/marreta/main/docker-compose.yml` -Se necessario +Agora modifique com suas configurações: `nano docker-compose.yml` @@ -68,44 +59,6 @@ services: - Agora pode rodar `docker compose up -d` -#### Desenvolvimento - -1. Primeiro, clone o projeto: -```bash -git clone https://github.com/manualdousuario/marreta/ -cd marreta -``` - -2. Cria o arquivo de configuração: -```bash -cp app/.env.sample app/.env -``` - -3. Configura do seu jeito no `app/.env`: -```env -SITE_NAME="Marreta" -SITE_DESCRIPTION="Chapéu de paywall é marreta!" -SITE_URL=http://localhost -DNS_SERVERS=1.1.1.1,8.8.8.8 -LOG_LEVEL=WARNING -SELENIUM_HOST=selenium-hub:4444 -LANGUAGE=pt-br -``` - -4. Web Service: Utilize o `default.conf` como base do NGINX ou aponte seu webservice para `app/` - -## ⚙️ Personalizando - -As configurações estão organizadas em `data/`: - -- `domain_rules.php`: Regras específicas para cada site -- `global_rules.php`: Regras que se aplicam a todos os sites -- `blocked_domains.php`: Lista de sites bloqueados - -### Traduções - -- `/languages/`: Cada lingua está em seu ISO id (`pt-br, en, es ou de-de`) e pode ser definida no environment `LANGUAGE` - ### Cache S3 Suporte de armazenamento do cache em S3. Configure as seguintes variáveis no seu `.env`: @@ -146,7 +99,7 @@ S3_ACL=private ### Integração com Selenium -Integração com Selenium para processar sites que requerem javascript ou têm algumas barreiras de proteção mais avançadas. Para usar esta funcionalidade, você precisa configurar um ambiente Selenium com Firefox. Adicione a seguinte configuração ao seu `docker-compose.yml`: +Integração com Selenium permite processar sites que requerem javascript ou têm algumas barreiras de proteção mais avançadas. Para usar esta funcionalidade, você precisa configurar um ambiente Selenium com Firefox. Adicione a seguinte configuração ao seu `docker-compose.yml`: ```yaml services: @@ -187,6 +140,45 @@ Configurações importantes: Após configurar o Selenium, certifique-se de definir a variável `SELENIUM_HOST` no seu ambiente para apontar para o hub do Selenium (geralmente `selenium-hub:4444`). +## Desenvolvimento + +1. Primeiro, clone o projeto: +```bash +git clone https://github.com/manualdousuario/marreta/ +cd marreta/app +``` + +2. Instale as dependências do projeto: +```bash +composer install +npm install +``` + +3. Cria o arquivo de configuração: +```bash +cp .env.sample .env +``` + +4. Configure as variáveis de ambiente no `.env` + +5. Utilize o `default.conf` como base do NGINX ou aponte seu webservice para `app/` + +O Gulp é usado para compilar Sass para CSS, minificar JavaScript, utilize: `gulp` + +### ⚙️ Personalizando + +As configurações estão organizadas em `data/`: + +- `domain_rules.php`: Regras específicas para cada site +- `global_rules.php`: Regras que se aplicam a todos os sites +- `blocked_domains.php`: Lista de sites bloqueados + +### Traduções + +- `/languages/`: Cada lingua está em seu ISO id (`pt-br, en, es ou de-de`) e pode ser definida no environment `LANGUAGE` + +## 🛠️ Manutenção + ### Sistema de Logs Os logs são armazenados em `app/logs/*.log` com rotação automática a cada 7 dias. @@ -204,10 +196,6 @@ Níveis de log disponíveis: - ERROR: Erros que não interrompem a operação - CRITICAL: Erros críticos que precisam de atenção imediata -## 🛠️ Manutenção - -### Logs - Ver os logs da aplicação: ```bash docker-compose logs app