octoleo/telegram-bot-bash
1
1
Fork 0
mirror of https://github.com/octoleo/telegram-bot-bash.git synced 2025-01-15 02:13:44 +00:00
Code Issues Projects Releases Wiki Activity

doc: adjust installation / update instructions

Browse Source
This commit is contained in:
Kay Marquardt (Gnadelwartz) 2021-01-04 20:51:13 +01:00
parent 0d678f4234
commit 53c107d4ee
2 changed files with 39 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
doc/0_install.md
View File

@ -2,7 +2,7 @@
## Check bash installation ## Check bash installation
There may systems where bash seems to be installed but it is not, e.g. embedded systems, or where bash is to old. There may systems where bash seems to be installed but it is not (e.g. embedded systems_) or where bash is to old.
Bashbot has some builtin checks but it may better to check before installing bashbot. Bashbot has some builtin checks but it may better to check before installing bashbot.
Run the following commands to see if your bash looks ok ... Run the following commands to see if your bash looks ok ...
@ -15,7 +15,7 @@ if which bash; then echo "bash seems available..."; else echo "NO bash"; fi
bash -c 'if eval "a[1]=1"; then echo "Shell support arrays..."; else echo "Shell has NO arrays"; fi' bash -c 'if eval "a[1]=1"; then echo "Shell support arrays..."; else echo "Shell has NO arrays"; fi'
# check for bash version by feature # check for bash version by feature
bash -c 'if [ "$(echo -e "\u1111")" != "\u1111" ]; then echo "Bash version ok ..."; else echo "Bash version may to old ..."; fi' bash -c 'if [ "$(LANG=C.UTF-8 echo -e "\u1111")" != "\u1111" ]; then echo "Bash version ok ..."; else echo "Bash version may to old ..."; fi'
# display bash version, must be greater than 4.3 # display bash version, must be greater than 4.3
bash --version | grep "bash" bash --version | grep "bash"
@ -23,58 +23,59 @@ bash --version | grep "bash"
## Install bashbot ## Install bashbot
1. Go to the directory you want to install bashbot, e.g. Installing bashbot is very simple: Download and extract the installation archive.
* your $HOME directory (install and run with your user-ID)
* /usr/local if you want to run as service 1. Choose a directory to install bashbot (_e.g.your HOME or /usr/local_)
2. [Download latest release zip / tar archive from github](https://github.com/topkecleon/telegram-bot-bash/releases/latest) and extract all files. 2. Download [latest release zip / tar archive] (https://github.com/topkecleon/telegram-bot-bash/releases/latest) and extract all files.
3. Change into the directory `telegram-bot-bash` 3. Change into the directory `telegram-bot-bash`
4. Copy `mycommands.sh.dist` or `mycommands.sh.clean` to `mycommands.sh` 4. Copy `mycommands.sh.dist` or `mycommands.sh.clean` to `mycommands.sh`
5. Run `./bashbot.sh init` to setup the environment and enter your Bots token given by botfather. 5. Run `./bashbot.sh init`\* to setup the environment and enter your Bots token given by botfather.
Edit `mycommands.sh` to fit your needs. Edit `mycommands.sh` to fit your needs.
Now your Bot is ready to start ... Now your Bot is ready to start ...
**If you are new to Bot development read [Bots: An introduction for developers](https://core.telegram.org/bots)** *If you are new to Bot development read [Bots: An introduction for developers](https://core.telegram.org/bots)*
\* _Run with sudo if you want to run bashbot from different user, e.g. from `bashbot.rc`._
### Update bashbot ### Update bashbot
**Important: all files including `mycommands.sh` may overwritten, make a backup!** Update bashbot is almost identical to installing bashbot: Download and extract the installation archive.
1. Go to the directory where you have installed bashbot, e.g. **Important: All files may overwritten, make a backup!**
* your $HOME directory
* /usr/local 1. Go to the directory where bashbot is installed (_e.g.$HOME/telegram-bot-bash or /usr/local/telegram-bot-bash_)
2. [Download latest release zip / tar archive from github](https://github.com/topkecleon/telegram-bot-bash/releases/latest) 2. Download [latest release zip / tar archive](https://github.com/topkecleon/telegram-bot-bash/releases/latest)
3. Stop all running instances of bashbot `./bashbot.sh stop` 3. Stop all running instances of bashbot `./bashbot.sh stop`
4. Extract all files to your existing bashbot dir 4. Change to parent directory of bashbot installation and extract all files from archive.
5. Run `sudo ./bashbot.sh init` to setup your environment after the update 5. Run `./bashbot.sh init`\* to setup your environment after the update
6. Restart your bot `./bashbot.sh start`
If you modified `commands.sh` move your changes to `mycommands.sh`, this avoids overwriting your commands on every update. `mycommands.sh` will not overwritten, this avoids losing your bot commands on updates.
Now you can restart your bashbot instances.
*Note*: If you are updating from a pre-1.0 version, update to [Version 1.20](https://github.com/topkecleon/telegram-bot-bash/releases/tags/v1.20) first! *Note*: If you are updating from a pre-1.0 version, update to [Version 1.20](https://github.com/topkecleon/telegram-bot-bash/releases/tags/v1.20) first!
### Use JSON.awk (beta) ### Use JSON.awk
[JSON.awk](https://github.com/step-/JSON.awk) is an awk port of `JSON.sh`, it provides the same functionality but is 5 times faster. [JSON.awk](https://github.com/step-/JSON.awk) is an awk port of `JSON.sh`, it provides the same functionality but is 5 times faster.
Most systems with awk can use `JSON.awk` as drop in replacement On most systems you can use `JSON.awk` with system default awk installation.
( [gnu awk, posix awk, mawk, busybox akw](https://github.com/step-/JSON.awk#compatibility-with-awk-implementations) ). ( [gnu awk, posix awk, mawk, busybox akw](https://github.com/step-/JSON.awk#compatibility-with-awk-implementations) ).
After you have checked that `JSON.awk.dist` is working on your system copy it to `JSON.awk` and (re)start bashbot.
BSD and MacOS users must install `gnu awk` and adjust the shebang, see below BSD and MacOS users must install `gnu awk` and adjust the shebang, see below
After you have checked that `JSON.awk.dist` is working correct on your system copy it to `JSON.awk` and (re)start bashbot. *Note*: To install or update `JSON.awk` manually execute the following commands in the directory `JSON.sh/`:
Note: If you are not using the zip / tar archive, you must install `JSON.awk` manually into the same directory as `JSON.sh`:
wget https://cdn.jsdelivr.net/gh/step-/JSON.awk/JSON.awk wget https://cdn.jsdelivr.net/gh/step-/JSON.awk/JSON.awk
wget https://cdn.jsdelivr.net/gh/step-/JSON.awk/tool/patch-for-busybox-awk.sh wget https://cdn.jsdelivr.net/gh/step-/JSON.awk/tool/patch-for-busybox-awk.sh
bash patch-for-busybox-awk.sh bash patch-for-busybox-awk.sh
chmod +x JSON.awk
### Install bashbot from git repo ### Install bashbot from git repo
Installation and Updates should be done using the zip / tar archives provided on github to avoid Installation and updates should be done using the zip / tar archives provided on github to avoid
problems and not overwriting your bot config and `mycommands.sh`. problems and not overwriting your bot config and `mycommands.sh`.
Nevertheless you can install or update bashbot from a git repo, see next chapter ... Nevertheless you can install or update bashbot from a git repo, see next chapter ...
@ -82,7 +83,8 @@ Nevertheless you can install or update bashbot from a git repo, see next chapter
### Create Installation / Update archives ### Create Installation / Update archives
To install or update bashbot from git repo execute `dev/make-distribution.sh`, this creates the archives and set up bashbot to run in `DIST/telegram.bot-bash`. To install or update bashbot from git repo execute `dev/make-distribution.sh`.
This creates the installation archives in `DIST/` and a ready to run test installation in `DIST/telegram.bot-bash`.
*Note:* You should be familiar with `git`. *Note:* You should be familiar with `git`.
@ -92,10 +94,12 @@ To install or update bashbot from git repo execute `dev/make-distribution.sh`, t
4. Run ` dev/make-distribution.sh` (_add --notest to skip tests_) 4. Run ` dev/make-distribution.sh` (_add --notest to skip tests_)
5. Change to dir `DIST/` 5. Change to dir `DIST/`
Use the archives created in `DIST/` to install or update bashbot as described above. Use the installation archives to install or update bashbot as described above.
To run a test bot, e.g. while development or testing latest changes, you can use the bashbot installation provided in `DIST/telegram-bot-bash`. To run a test bot, e.g. while development or testing latest changes, you can use the bashbot installation provided in `DIST/telegram-bot-bash`.
To update the test installation, e.g. after git pull, local changes or switch master/develop, run `dev/make-distrubition.sh` again. To update\* the test installation (_after git pull, local changes or switch master/develop_) run `dev/make-distrubition.sh` again.
\* _`mycommands.sh` and `bashbot.rc` will be overwritten._
### Note for BSD and MacOS ### Note for BSD and MacOS
@ -104,18 +108,14 @@ To update the test installation, e.g. after git pull, local changes or switch ma
see e.g. [Install Bash on Mac](http://macappstore.org/bash/) see e.g. [Install Bash on Mac](http://macappstore.org/bash/)
**On BSD and MacOS** I recommend to install gnu coreutils and include them in your PATH **On BSD and MacOS** I recommend to install gnu coreutils and include them in your PATH
environment variable before running bashbot, e.g. the gnu versions of sed, grep, find ... environment variable before running bashbot, e.g. the gnu versions of sed, grep, find, awk ...
On BSD and MacOS you must adjust the shebang line of the scripts ```bashbot.sh``` and ```json.sh``` to point to to the correct bash On BSD and MacOS you must adjust the shebang line of the scripts `bashbot.sh` and `json.sh` to point to to the correct bash
or use the script: ```examples/bash2env *.sh */*.sh``` to convert them for you. or use the script: `examples/bash2env *.sh */*.sh` to convert them for you.
Bashbot will stay with /bin/bash shebang, as using a fixed path is more secure than the portable /usr/bin/env variant, see Bashbot will stay with `#!/bin/bash` shebang, as using a fixed path is IMHO more secure than the portable '!/usr/bin/env bash` variant.
[Security Considerations](../README.md#Security-Considerations)
I considered to make bashbot BSD sed compatible, but much of the bashbot "magic" relies on Compatibility with BSD/MacOS will result in a rewrite of all grep/sed commands with an uncertain outcome,
(gnu) sed features, e.g. alternation ```|```, non printables ```\n\t\<``` or repeat ```?+``` pattern, not supported by BSD sed.
BSD/MacOS sed compatibility will result in a rewrite of all grep/sed commands with an uncertain outcome,
see [BSD/MacOS vs. GNU sed](https://riptutorial.com/sed/topic/9436/bsd-macos-sed-vs--gnu-sed-vs--the-posix-sed-specification) see [BSD/MacOS vs. GNU sed](https://riptutorial.com/sed/topic/9436/bsd-macos-sed-vs--gnu-sed-vs--the-posix-sed-specification)
to get an impression how different they are. to get an impression how different they are.
@ -127,9 +127,7 @@ to get an impression how different they are.
From Version 1.21 on updating from a pre-1.0 version (_no \*.jssh config_) is no more supported! From Version 1.21 on updating from a pre-1.0 version (_no \*.jssh config_) is no more supported!
You must update to [Version 1.20](https://github.com/topkecleon/telegram-bot-bash/releases/tags/v1.20) first! You must update to [Version 1.20](https://github.com/topkecleon/telegram-bot-bash/releases/tags/v1.20) first!
#### [Next Create Bot](1_firstbot.md) #### [Next Create Bot](1_firstbot.md)
#### $$VERSION$$ v1.21-0-gc85af77 #### $$VERSION$$ v1.25-dev-2-g0d678f4

4
doc/4_expert.md
View File

@ -50,7 +50,7 @@ If you don't know what locales are installed on your sytsem use `locale -a` to d
##### Character classes ##### Character classes
In ASCII times it was clear `[:lower:]` and `[a-z]` means ONLY the lowercase letters `[abcd...xyz]`. In ASCII times it was clear `[:lower:]` and `[a-z]` means ONLY the lowercase letters `[abcd...xyz]`.
With introdution of localesi, character classes and ranges contains all charatcers fitting the class definition. With introdution of locales, character classes and ranges contains all characters fitting the class definition.
This means with a Latin UTF-8 locale `[:lower:]` and `[a-z]` contains also e.g. `á ø ü` etc, This means with a Latin UTF-8 locale `[:lower:]` and `[a-z]` contains also e.g. `á ø ü` etc,
see [Unicode Latin lowercase letters](https://www.fileformat.info/info/unicode/category/Ll/list.htm) see [Unicode Latin lowercase letters](https://www.fileformat.info/info/unicode/category/Ll/list.htm)
@ -434,5 +434,5 @@ for every poll until the maximum of BASHBOT_SLEEP ms.
#### [Prev Advanced Use](3_advanced.md) #### [Prev Advanced Use](3_advanced.md)
#### [Next Best Practice](5_practice.md) #### [Next Best Practice](5_practice.md)
#### $$VERSION$$ v1.25-dev-1-g8162695 #### $$VERSION$$ v1.25-dev-2-g0d678f4