Document environment variables (#143)

Adds documentation for all available envirnrment variables to the README

Co-authored-by: Ben Busby <benbusby@protonmail.com>

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=<whoogle_directory>
@@ -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
 

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
+    }
+  }
 }

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