From 4447cb682aa235d4ea962f753bcea8edf43ecb3a Mon Sep 17 00:00:00 2001 From: Paolo Basso Date: Tue, 3 Nov 2020 22:28:42 +0100 Subject: [PATCH] Document environment variables (#143) Adds documentation for all available envirnrment variables to the README Co-authored-by: Ben Busby --- README.md | 41 ++++++++++++++++++++++++++++++++++- app.json | 53 ++++++++++++++++++++++++++++++++++++++++------ docker-compose.yml | 9 ++++++++ 3 files changed, 96 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 699d613..4b76586 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,20 @@ If using Heroku Quick Deploy, **you can skip this section**. - Ubuntu: `sudo apt-get install -y libcurl4-openssl-dev libssl-dev` - Arch: `pacman -S curl openssl` +## Environment Variables +There are a few optional environment variables available for customizing a Whoogle instance: + +| Variable | Description | +| ------------------ | -------------------------------------------------------------- | +| WHOOGLE_USER | The username for basic auth. WHOOGLE_PASS must also be set if used. | +| WHOOGLE_PASS | The password for basic auth. WHOOGLE_USER must also be set if used. | +| WHOOGLE_PROXY_USER | The username of the proxy server. | +| WHOOGLE_PROXY_PASS | The password of the proxy server. | +| WHOOGLE_PROXY_TYPE | The type of the proxy server. Can be "socks5", "socks4", or "http". | +| WHOOGLE_PROXY_LOC | The location of the proxy server (host or ip). | +| EXPOSE_PORT | The port where Whoogle will be exposed. | +| HTTPS_ONLY | Enforce HTTPS. (See [here](https://github.com/benbusby/whoogle-search#https-enforcement)) | + ## Install There are a few different ways to begin using the app, depending on your preferences: @@ -97,6 +111,7 @@ optional arguments: --debug Activates debug mode for the server (default False) --https-only Enforces HTTPS redirects for all requests (default False) ``` +You may want to set the environment variables in the host OS. ### E) Manual Clone the repo and run the following commands to start the app in a local-only environment: @@ -109,6 +124,7 @@ source venv/bin/activate pip install -r requirements.txt ./run ``` +You may want to set the environment variables in the host OS. #### systemd Configuration After building the virtual environment, you can add the following to `/lib/systemd/system/whoogle.service` to set up a Whoogle Search systemd service: @@ -118,6 +134,14 @@ After building the virtual environment, you can add the following to `/lib/syste Description=Whoogle [Service] +# Basic auth configuration, remove to disable +Environment=WHOOGLE_USER=username +Environment=WHOOGLE_PASS=password +# Proxy configuration, remove to disable +Environment=WHOOGLE_PROXY_USER=username +Environment=WHOOGLE_PROXY_PASS=password +Environment=WHOOGLE_PROXY_TYPE=socks5 +Environment=WHOOGLE_PROXY_LOC=ip Type=simple User=root WorkingDirectory= @@ -167,6 +191,19 @@ docker build --tag whoogle-search:1.0 . docker run --publish 5000:5000 --detach --name whoogle-search whoogle-search:1.0 ``` +Optionally, you can also enable some of the following environment variables to further customize your instance: + +```bash +docker run --publish 5000:5000 --detach --name whoogle-search \ + -e WHOOGLE_USER=username \ + -e WHOOGLE_PASS=password \ + -e WHOOGLE_PROXY_USER=username \ + -e WHOOGLE_PROXY_PASS=password \ + -e WHOOGLE_PROXY_TYPE=socks5 \ + -e WHOOGLE_PROXY_LOC=ip \ + whoogle-search:1.0 +``` + And kill with: `docker rm --force whoogle-search` #### Using [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) @@ -182,6 +219,7 @@ heroku open ``` This series of commands can take a while, but once you run it once, you shouldn't have to run it again. The final command, `heroku open` will launch a tab in your web browser, where you can test out Whoogle and even [set it as your primary search engine](https://github.com/benbusby/whoogle#set-whoogle-as-your-primary-search-engine). +You may also edit environment variables from your app’s Settings tab in the Heroku Dashboard. #### Using your own server, or alternative container deployment There are other methods for deploying docker containers that are well outlined in [this article](https://rollout.io/blog/the-shortlist-of-docker-hosting/), but there are too many to describe set up for each here. Generally it should be about the same amount of effort as the Heroku deployment. @@ -257,7 +295,8 @@ Only needed if your setup requires Flask to redirect to HTTPS on its own -- gene Note: You should have your own domain name and [an https certificate](https://letsencrypt.org/getting-started/) in order for this to work properly. - Heroku: Ensure that the `Root URL` configuration on the home page begins with `https://` and not `http://` -- Docker: Add `--build-arg use_https=1` to your run command +- Docker build: Add `--build-arg use_https=1` to your run command +- Docker image: Set the environment variable HTTPS_ONLY=1 - Pip/Pipx: Add the `--https-only` flag to the end of the `whoogle-search` command - Default `run` script: Modify the script locally to include the `--https-only` flag at the end of the python run command diff --git a/app.json b/app.json index 76b58a1..7482c98 100644 --- a/app.json +++ b/app.json @@ -1,8 +1,49 @@ { - "name": "Whoogle Search", - "description": "A lightweight, privacy-oriented, containerized Google search proxy for desktop/mobile that removes Javascript, AMP links, tracking, and ads/sponsored content", - "repository": "https://github.com/benbusby/whoogle-search", - "logo": "https://raw.githubusercontent.com/benbusby/whoogle-search/master/app/static/img/favicon/ms-icon-150x150.png", - "keywords": ["search", "metasearch", "flask", "docker", "heroku", "adblock", "degoogle", "privacy"], - "stack": "container" + "name": "Whoogle Search", + "description": "A lightweight, privacy-oriented, containerized Google search proxy for desktop/mobile that removes Javascript, AMP links, tracking, and ads/sponsored content", + "repository": "https://github.com/benbusby/whoogle-search", + "logo": "https://raw.githubusercontent.com/benbusby/whoogle-search/master/app/static/img/favicon/ms-icon-150x150.png", + "keywords": [ + "search", + "metasearch", + "flask", + "docker", + "heroku", + "adblock", + "degoogle", + "privacy" + ], + "stack": "container", + "env": { + "WHOOGLE_USER": { + "description": "The username for basic auth. WHOOGLE_PASS must also be set if used. Leave empty to disable.", + "value": "", + "required": false + }, + "WHOOGLE_PASS": { + "description": "The password for basic auth. WHOOGLE_USER must also be set if used. Leave empty to disable.", + "value": "", + "required": false + }, + "WHOOGLE_PROXY_USER": { + "description": "The username of the proxy server. Leave empty to disable.", + "value": "", + "required": false + }, + "WHOOGLE_PROXY_PASS": { + "description": "The password of the proxy server. Leave empty to disable.", + "value": "", + "required": false + }, + "WHOOGLE_PROXY_TYPE": { + "description": "The type of the proxy server. For example \"socks5\". Leave empty to disable.", + "value": "", + "required": false + }, + "WHOOGLE_PROXY_LOC": { + "description": "The location of the proxy server (host or ip). Leave empty to disable.", + "value": "", + "required": false + } + } } diff --git a/docker-compose.yml b/docker-compose.yml index 479b7f3..94a07fd 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -4,6 +4,15 @@ services: whoogle-search: image: benbusby/whoogle-search container_name: whoogle-search + environment: + # Basic auth configuration, remove to disable + - WHOOGLE_USER=username + - WHOOGLE_PASS=password + # Proxy configuration, remove to disable + - WHOOGLE_PROXY_USER=username + - WHOOGLE_PROXY_PASS=password + - WHOOGLE_PROXY_TYPE=socks5 + - WHOOGLE_PROXY_LOC=ip ports: - 5000:5000 restart: unless-stopped