Skip to content
This repository has been archived by the owner on Sep 16, 2021. It is now read-only.

Commit

Permalink
update project documentation
Browse files Browse the repository at this point in the history 
update readme, installation, examples
require a venv in the repository to run the bot
  • Loading branch information
@das7pad
das7pad committed Jul 17, 2017
1 parent 883e422 commit 62069bb
Show file tree
Hide file tree
Showing 4 changed files with 161 additions and 176 deletions.
193 changes: 98 additions & 95 deletions INSTALL.md
View file
Original file line number Diff line number Diff line change
@@ -1,128 +1,131 @@
# Preparing your Environment

This section describes the most common way to prepare a system for Hangoutsbot and
get it up and running.

**Docker Users:** See the the end of this file for the **Docker Usage** section.

1. Ensure that your system has Python 3.4.2 or newer - we recommend Python 3.5. It's
most likely already installed on your system if you are using a fairly new Linux
distribution. The Python package manager `pip3` is also required and is usually
shipped with whatever version of Python your system comes with.
* To check for the existence and versions of both the language and package manager,
you can run the following commands at your terminal:
* `python3 --version`
* `pip3 --version`
* For systems that don't have Python 3 pre-installed, it is usually available as a
package that you can install
(e.g. `sudo apt-get install python3 python3-pip` on Debian/Ubuntu).
We do not provide any further guidance for installation as this is beyond the
scope of the Hangoutsbot documentation and there are plenty of online resources
which can cover more use-cases and OSes than we can ;)
2. Clone the repository:

```
git clone <repository url>
```

3. Install the Python module dependencies that Hangoutsbot requires:

```
cd hangoutsbot
pip3 install -r requirements.txt
```

4. Run the program interactively for the first time - this topic is covered in the next
section, so please go through it carefully.
5. Set up the bot to be run as a daemon/service so that it can run unattended and
survive system reboots. This is an opiniated topic with plenty of different
implementation methods. When you're ready, some scripts are available at the
following links:
* https://github.com/hangoutsbot/hangoutsbot/tree/master/examples
* https://github.com/hangoutsbot/hangoutsbot/issues/69
This section describes the most common way to prepare a system for Hangoutsbot
and get it up and running.

**Docker Users:** See the [**Docker Usage**](#docker-usage) section.

1. Ensure that your system has Python 3.5.0 or newer. It's most likely already
installed on your system if you are using a fairly new Linux distribution.

* To check for the existence and version of the language, you can run the
following commands at your terminal:
* `python3 --version`
* For systems that don't have Python 3 pre-installed, it is usually
available as a package that you can install
(e.g. `sudo apt-get install python3 python3-pip` on Debian/Ubuntu).
We do not provide any further guidance for installation as this is beyond
the scope of the Hangoutsbot documentation and there are plenty of online
resources which can cover more use-cases and OSes than we can.

2. Clone the repository:

```
git clone https://github.com/das7pad/hangoutsbot.git hangoutsbot
cd hangoutsbot
```
3. Create a Virtual Environment to ensure that no other packages change the
versions of packages we require:
```
python3 -m venv venv
```
3. Install the Python module dependencies that Hangoutsbot requires:
```
./venv/bin/pip3 install -r requirements.txt
```
4. Run the program interactively for the first time - this topic is covered in
the next section, so please go through it carefully.
5. Set up the bot to be run as a daemon/service so that it can run unattended
and survive system reboots. This is an opiniated topic with plenty of
different implementation methods. When you're ready, some scripts are
available at the following links:
* [/examples](/examples)
* https://github.com/hangoutsbot/hangoutsbot/issues/69
# First-Run
You need to **run the bot for the first time**. You will need at least
two gmail accounts: one is your actual account, the other will be your
bot account.
You need to **run the bot for the first time**. You will need at least two gmail
accounts: one is your actual account, the other will be your bot account.
The basic syntax for running the bot (assuming you are in the root
of the cloned repository) is:
The basic syntax for running the bot (assuming you are in the root of the cloned
repository) is:
```
python3 hangupsbot/hangupsbot.py
./venv/bin/python3 hangupsbot/hangupsbot.py
```
See https://github.com/tdryer/hangups/issues/260#issuecomment-246578670 for getting auth code
If you are having problems starting the bot, appending a `-d` at the
end will dump more details into the bot logs e.g.
`python3 hangupsbot/hangupsbot.py -d` - more configuration
directives can be found at the end of the README file.
You will be prompted for your gmail username and password. Use your bot account
credentials. If the login is sucessful, you will see additional logs about
plugins being loaded. The credentials will be saved in an access token so that
running the bot again will not prompt you for username and password again.
You will be prompted for your gmail username and password. Use your
bot account credentials. If the login is sucessful, you will see
additional logs about plugins being loaded. The credentials will be
saved so that running the bot again will not prompt you for username
and password again.
To quit the bot from the console, press `CTRL+C`
To quit the bot from the console, press CTRL-C
If you are having problems starting the bot, see
[Troubleshooting](#troubleshooting) or [Debugging](README.md#debugging).
# Initial Configuration
DO NOT EDIT the `config.json` supplied with the bot. It is the
reference file used to generate the actual config file, which
is located elsewhere. Please see the next section on
**Additional Configuration** to get the location of the
actual configuration file if you need to edit it manually.
DO NOT EDIT the `config.json` supplied with the repository. It is the reference
file used to generate the actual config file, which is located elsewhere.
Please see the next section on **Additional Configuration** to get the
location of the actual configuration file if you need to edit it manually.
You will need to add your actual Hangouts user as a bot administrator.
This will be accomplished using the supplied **starter** plugin with
the default supplied configuration.
This will be accomplished using the supplied **starter** plugin with the default
supplied configuration.
1. Using a hangouts client and your actual gmail account, open a
hangout with the bot account.
2. Send any message to the bot from your own gmail account.
3. On a browser, login into the bot's gmail account and ensure chat
is activated. Accept the invite (and message) from your own gmail
account.
4. Back on your hangouts client, send the following message:
`/bot iamspartacus`
5. The bot should reply with "configuring first admin" or a similar
message.
1. Using a hangouts client and your actual gmail account, open a hangout with
the bot account.
2. Send any message to the bot from your own gmail account.
3. On a browser, login into the bot's gmail account and ensure chat
is activated. Accept the invite (and message) from your own gmail account.
4. Back on your hangouts client, send the following message:
`/bot iamspartacus`
5. The bot should reply with "configuring first admin" or a similar
message.
# Additional Configuration
After the first successful run of the bot, it should generate a
After the first successful run of the bot, it should generate a
`config.json` somewhere in your user directory.
You should be able to find it in:
`/<username>/.local/share/hangupsbot/`, where <username> is your
operating system username.
You should be able to find it in:
`/<username>/.local/share/hangupsbot/`, where `<username>` is your operating
system username.
You can edit this file and restart the bot to load any new configs.
You can edit this file and reload any new configs by
* sending the message `/bot reload` in a hangout with the bot account
* restarting the bot
For further information, please see the README file and wiki.
For further information, please see the [README file](README.md) and wiki.
# Troubleshooting
* For console output when the bot is starting, errors messages always
start in ALLCAPS e.g. "EXCEPTION in ..."
* Additional logs can be found in:
`/<username>/.local/share/hangupsbot/hangupsbot.log` -
* Check the console output and search the Issue lists
* [upstream](https://github.com/hangoutsbot/hangoutsbot/issues?q=is%3Aissue)
* [local](https://github.com/das7pad/hangoutsbot/issues?q=is%3Aissue)
* Additional logs can be found in:
`/<username>/.local/share/hangupsbot/hangupsbot.log`
note: this file is more useful for developers and may be quite verbose
* You can verify the location of your active `config.json` by sending
the following command to the bot via hangouts: `/bot files` (with
the **starter** plugin active)
* You can verify the location of your active `config.json` by sending the
following command to the bot via hangouts: `/bot files` (with the
**starter** plugin active)
# Docker Usage
The bot can be run inside a docker container if desired.
You will need to create a directory outside the container to contain
configuration and storage data, and if you are using sinks, you may
need to change the ports we expose from the container (the defaults
are 9000, 9001, and 9002):
The bot can be run inside a docker container if desired. You will need to create
a directory outside the container to contain configuration and storage data, and
if you are using sinks, you may need to change the ports we expose from the
container (the defaults are 9000, 9001, and 9002):
You will first need to build the image:
Expand All @@ -134,11 +137,11 @@ If you need to change ports add `--build-arg PORTS="new port list"`, for
example:
```
docker build -t hangoutsbot/hangoutsbot --build-arg PORTS="9000 9001 9002 9003 9004" .
docker build -t hangoutsbot/hangoutsbot --build-arg PORTS="9003 9004 9005" .
```
Then you can run the image, any arguments starting with a "-" will be passed after
the image name will be passed on to the bot (e.g. `-d` for debug):
Then you can run the image, any arguments starting with a "-" after the image
name will be passed on to the bot (e.g. `-d` for debug):
To run interactively, and in debug mode:
Expand Down
Loading

0 comments on commit 62069bb

Please sign in to comment.