Document environment variables (#143)
Adds documentation for all available envirnrment variables to the README Co-authored-by: Ben Busby <benbusby@protonmail.com>main
parent
f88d1fbb66
commit
4447cb682a
41
README.md
41
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
|
||||
|
||||
|
|
45
app.json
45
app.json
|
@ -3,6 +3,47 @@
|
|||
"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"
|
||||
"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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue