Browse Source

Updated readme, fix incorrect newline in docker start.sh, add example usage (#53)

1. Line 23 in `start.sh` (Docker) contained an erroneous newline that would cause the container to constantly restart.  Removed that.

2. Updated the README.md to contain the current usage (0.0.7 + commits) of golinks.
    * Added an updated compose/docker section **NOTE** I am using my repo `brokenscripts/golinks` on DockerHub to align with 0.0.7 until your latest version is pushed.
    * Updated the configuration section to show the actual variables used in the current release.

3. Added a small gif to show usage.

---

Files Updated:
* `README.md`
* `start.sh`

Files Added:
* `golinks.gif/golinks.gif`

Co-authored-by: brokenscripts <brokenscripts@protonmail.com>
Reviewed-on: #53
Co-authored-by: brokenscripts <brokenscripts@noreply@mills.io>
Co-committed-by: brokenscripts <brokenscripts@noreply@mills.io>
master
brokenscripts 3 days ago committed by James Mills
parent
commit
ef007105dd
  1. 3
      .dockerfiles/start.sh
  2. 173
      README.md
  3. BIN
      golinks.gif/golinks.gif

3
.dockerfiles/start.sh

@ -20,6 +20,5 @@ echo " -dbpath=$DBPATH"
echo " -title=$TITLE"
echo " -searchURL=$SEARCHURL"
echo " -suggestURL=$SUGGESTURL"
exec golinks -bind="$BIND" -baseURL="$BASEURL" -dbpath="$DBPATH" -title="$TITLE" -searchURL="$SEARCHURL" -suggestURL
="$SUGGESTURL"
exec golinks -bind="$BIND" -baseURL="$BASEURL" -dbpath="$DBPATH" -title="$TITLE" -searchURL="$SEARCHURL" -suggestURL="$SUGGESTURL"
fi

173
README.md

@ -26,134 +26,127 @@ brew install golinks
recent unreleased version from master you'll have to clone the repository
and build yourself.
### Docker
## Initial Setup (required)
Set your browser's default custom search engine to your golinks hosted location, such as `http://localhost:8000/?q=%s`. Replacing localhost with wherever you host golinks from.
To startup a container with an image from docker hub, run the following:
```
docker run -it -d -p 8000:8000 prologic/golinks
```
* [Instructions for Chrome](https://support.google.com/chrome/answer/95426)
* [Instructions for Firefox](https://support.mozilla.org/en-US/kb/add-or-remove-search-engine-firefox#w_add-a-search-engine-from-the-address-bar)
Or use the following docker-compose configuration:
Then type `help` to view the main help page, `g foo bar` to perform a Google search for "foo bar" or `list` to list all available commands.
## Usage (Standalone)
If using the binary `golinks`, then run it as follows, specifying the parameters individually or by specifying a configuration file
```
golinks:
image: 'prologic/golinks:latest'
container_name: golinks
ports:
- "8000:8000"
golinks -bind 0.0.0.0:8000 -baseURL http://localhost:8000
```
You can also specify command line arguments as described in [configuration](#configuration) and make docker container persistent with volumes:
Or using a configuration file:
```
golinks:
image: 'prologic/golinks:latest'
container_name: golinks
command:
- "-dbpath=/path/to/container/search.db"
- "-title=Dave's Search"
- "-fqdn=localhost:8000"
- "-url=https://www.google.com/search?q=%s&btnK"
- "-suggest=https://suggestqueries.google.com/complete/search?client=firefox&q=%s"
volumes:
- "./path/to/local/search.db:/path/to/container/search.db"
golinks -config ~/.config/golinks/config.cfg
```
## Usage
When using the binary, it supports any of the parameters specified in the **Example Config File** section.
**NOTE**: They are case sensitive and must be used, exactly as shown in the config file section such as `baseURL`.
Run golinks:
## Docker
To startup a container with an image from docker hub, run the following:
```bash
$ golinks -bind 127.0.0.1:8000 -fqdn localhost:8000
docker run -it -d -p 8000:8000 brokenscripts/golinks
```
This will start up the server on port 8000.
Set your browser's default golinks engine to http://localhost:8000/?q=%s
## Docker Compose
Or use the following docker-compose configuration that creates a bind mount from a golinks folder in the current user's home directory to where the environment variable `DBPATH` is pointed at in the container.
- [Instructions for Chrome](https://support.google.com/chrome/answer/95426)
- [Instructions for Firefox](https://support.mozilla.org/en-US/kb/add-or-remove-search-engine-firefox#w_add-a-search-engine-from-the-address-bar)
> Note: The latest version of golinks, used in this docker image, uses `environment` variables instead of the old `command` variables.
Then type `help` to view the main help page, `g foo bar` to perform a [Google](https://google.com) search for "foo bar" or `list` to list all available commands.
```yaml
version: "3.9"
### Custom bookmarks
services:
golinks:
image: brokenscripts/golinks
container_name: golinks
restart: unless-stopped
volumes:
- "${HOME}/golinks:/search.db"
environment:
BIND: "0.0.0.0:8000"
BASEURL: "https://golinks.domain.net" # Using an internal proxy that will make this resolve correctly
DBPATH: "/search.db"
TITLE: "GoLinks"
SEARCHURL: "https://www.google.com/search?q=%s&btnK"
SUGGESTURL: "https://suggestqueries.google.com/complete/search?client=firefox&q=%s"
```
| FLAG | DEFAULT | Description |
|---|---|---|
| `BIND` | `0.0.0.0:8000` | Must be in IP:PORT format. Where the container listens at. |
| `BASEURL` | `http://localhost:8000` | **Must** start with `http://` or `https://` and can optionally have a port following the domain name. If using a proxy, ensure that this matches what your clients will visit. |
| `DBPATH` | `/search.db` | Where in the container you want the bookmarks stored |
| `TITLE` | `Search` | The OpenSearch service title (i.e. what your browser will call golinks' search) |
| `SEARCHURL` | `https://www.google.com/search?q=%s&btnK` | The URL golinks will redirect searches to by default (if no custom bookmark matches) |
| `SUGGESTURL` | `https://suggestqueries.google.com/complete/search?client=firefox&q=%s` | URL of autosuggest service to retrieve search suggestions from |
---
| FLAG | DEFAULT | Description |
|------|---------|-------------|
| `CONFIG` | | Path to an **optional** config file containing the below golinks variables |
See `Configuration File` below for more information.
## Custom Bookmarks
To add a bookmark (or overwrite an existing one), enter `add [name] [url]` as your search query, where `name` is the shortcut for the bookmark and `url` the URL:
```
add imdb https://www.imdb.com
```
Now you can just enter `imdb` in your search bar to go straight to imdb.com.
Now you can just enter imdb in your search bar to go straight to `imdb.com`.
You can also add `%s` to your URL, which will be replaced with your search query:
```
add ddg https://duckduckgo.com/?q=%s
```
Now you can use `ddg [query]` to search via DuckDuckGo, e.g. `ddg free stuff` to find yourself some free stuff.
To remove a search, use `remove [name]`, so `remove ddg` will remove the above search.
### Other commands
To remove a search, use `remove [name]`, so `remove ddg` will remove the above search.
Use `list` to see all your bookmarks and commands (golinks comes with several useful built-ins) and `help` to view the online help page.
## Commands
`help` to view the online help page
`list` to see all your bookmarks and commands
`add` to create a new bookmark
`remove` to remove a bookmark
`date` to get the current container date (UTC default)
`time` to get the current container time (UTC default)
`ping` to get the current UNIX timestamp (epoch)
## Configuration
## Configuration File
golinks can also use a configuration file (specified via `CONFIG=/path/to/file`) with a very simple format. Each line of the file should contain one option, specified in the same way as the corresponding CLI flag but without the leading `-`. Empty lines and lines beginning with `#`are ignored.
golinks comes with sensible defaults, so it will run out-of-the box without any configuration (just run `golinks` and it will be available at `http://localhost:8000`, and save your custom bookmarks to `search.db` in the working directory), but there are several knobs you can tweak.
> Note: If using a config file, do not specify the environment variables shown above
All configuration options can be specified via command-line flag, environment variable or a configuration file.
### Example Config File
Save the variables shown below as `config.cfg` (example filename) and bind mount into the container and specify the environment `CONFIG` variable pointing to where this is mounted at.
```plain
bind 0.0.0.0:8000
baseURL http://localhost:8000
dbpath /search.db
title GoLinks
searchURL https://www.google.com/search?q=%s&btnK
suggestURL https://suggestqueries.google.com/complete/search?client=firefox&q=%s
```
The available CLI flags are (as shown via `golinks -h`):
| Flag | Default | Description |
|------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| `-bind` | `0:0:0:0:8000` | IP and port to bind server to. |
| `-fqdn` | `localhost:8000` | Web address that corresponds to bind address. |
| `-dbpath` | `search.db` | Database to save your custom bookmarks to. |
| `-suggest` | `https://suggestqueries.google.com/complete/search?client=firefox&q=%s` | URL of autosuggest service to retrieve search suggestions from. |
| `-title` | `Search` | The OpenSearch service title (i.e. what your browser will call golinks' search). |
| `-url` | `https://www.google.com/search?q=%s&btnK` | The URL golinks will redirect searches to by default (if no custom bookmark matches). |
| `-config` | | Path to the optional configuration file (see below). |
| `-h` | | Show CLI help and exit. |
| `-v` | | Show golinks version number and exit. |
## In Action!
Here is a quick example of having Chrome's search engine change the **keyword** `go` to point to my golinks.
### Environment variables
After using `go` you can see the bar change to **Search GoLinks**.
Typing `help` (so.. `go help`) does a redirect to the defined `help` URL contained in `golinks`.
All the above flags can also be specified via environment variable with the same name as the flag, but in uppercase. So `BIND=127.0.0.1:8081 FQDN=localhost:8081 golinks` is equivalent to `golinks -bind 127.0.0.1:8081 -fqdn localhost:8081`.
### Configuration file
golinks can also use a configuration file (specified via `-config /path/to/file` or `CONFIG=/path/to/file`) with a very simple format. Each line of the file should contain one option, specified in the same way as the corresponding CLI flag but without the leading `-`. Empty lines and lines beginning with `#` are ignored:
```
# with a space
bind 127.0.0.1:8081
# with equals
fqdn=localhost:8081
```
### Example
So, assuming your name is "Dave", a Linux user and fan of DuckDuckGo, you might run golinks like this:
```
golinks -config ~/.config/golinks/config.cfg
```
where `/home/dave/.config/golinks/config.cfg` looks like this:
```
bind 127.0.0.1:3456
fqdn localhost:3456
dbpath /home/dave/.config/golinks/search.db
title Dave's Search
url https://duckduckgo.com/?q=%s
suggest https://duckduckgo.com/ac/?type=list&q=%s
```
![GoLinks Example](./golinks.gif/golinks.gif)
## Stargazers over time

BIN
golinks.gif/golinks.gif

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

Loading…
Cancel
Save