riscritta documentazione
This commit is contained in:
Enrico Fasoli
parent
483dab09ce
commit
b8a938f1f6
233
README.md
233
README.md
@ -1,214 +1,63 @@
|
|||||||
# asjon
|
# Asjon ROBOT
|
||||||
|
|
||||||
asjon is a chat bot built on the [Hubot][hubot] framework. It was
|
Asjon è un chat bot creato usando l'[Hubot][hubot] framework.
|
||||||
initially generated by [generator-hubot][generator-hubot], and configured to be
|
|
||||||
deployed on [Heroku][heroku] to get you up and running as quick as possible.
|
|
||||||
|
|
||||||
This README is intended to help get you started. Definitely update and improve
|
|
||||||
to talk about your own instance, how to use and deploy, what functionality he
|
|
||||||
has, etc!
|
|
||||||
|
|
||||||
[heroku]: http://www.heroku.com
|
|
||||||
[hubot]: http://hubot.github.com
|
[hubot]: http://hubot.github.com
|
||||||
[generator-hubot]: https://github.com/github/generator-hubot
|
|
||||||
|
|
||||||
### Running asjon Locally
|
## Usare Asjon
|
||||||
|
|
||||||
You can test your hubot by running the following, however some plugins will not
|
Asjon è sempre online su Telegram con l'username `Asjon ROBOT`
|
||||||
behave as expected unless the [environment variables](#configuration) they rely
|
|
||||||
upon have been set.
|
|
||||||
|
|
||||||
You can start asjon locally by running:
|
## Sviluppare Asjon
|
||||||
|
|
||||||
% bin/hubot
|
Puoi testare asjon seguendo queste istruzioni, però alcuni componenti necessitano
|
||||||
|
di [variabili d'ambiente](#configuration) particolari per essere configurati
|
||||||
|
correttamente (ad esempio i dati di accesso al registro elettronico per l'agenda)
|
||||||
|
|
||||||
You'll see some start up output and a prompt:
|
### Dipendenze
|
||||||
|
|
||||||
|
Asjon necessita di:
|
||||||
|
|
||||||
|
- `node` e `npm`
|
||||||
|
- `redis` se si vuole salvare la sua memoria in maniera persistente
|
||||||
|
- `phantomjs` per utilizzare il modulo agenda/compiti
|
||||||
|
|
||||||
|
### Installazione
|
||||||
|
|
||||||
|
1. installare le dipendenze. Su arch linux: `pacman -S python2 nodejs phantomjs redis`
|
||||||
|
1. clonare questa repo
|
||||||
|
1. lanciare `npm install` (__Attenzione:__ usare `PYTHON=python2 npm install` su arch linux!) per installare tutte le dipendenze npm
|
||||||
|
1. se vuoi che Asjon conservi i ricordi tra una sessione e l'altra, avvia redis (su arch linux: `systemctl start redis`)
|
||||||
|
1. lanciare `bin/hubot` per testare il bot. Per usare le variabili d'ambiente usare
|
||||||
|
la sintassi di bash `VARIABILE=valore VAR2=valore2 bin/hubot`.
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
|
||||||
|
Puoi avviare asjon eseguendo
|
||||||
|
|
||||||
|
$ bin/hubot
|
||||||
|
|
||||||
|
Se tutto va bene dovrebbe comparire una cosa del genere:
|
||||||
|
|
||||||
[Sat Feb 28 2015 12:38:27 GMT+0000 (GMT)] INFO Using default redis on localhost:6379
|
[Sat Feb 28 2015 12:38:27 GMT+0000 (GMT)] INFO Using default redis on localhost:6379
|
||||||
asjon>
|
asjon>
|
||||||
|
|
||||||
Then you can interact with asjon by typing `asjon help`.
|
Puoi interagire con asjon scrivendo `asjon help` o qualsiasi altro suo comando.
|
||||||
|
|
||||||
asjon> asjon help
|
|
||||||
asjon animate me <query> - The same thing as `image me`, except adds [snip]
|
|
||||||
asjon help - Displays all of the help commands that asjon knows about.
|
|
||||||
...
|
|
||||||
|
|
||||||
### Configuration
|
|
||||||
|
|
||||||
A few scripts (including some installed by default) require environment
|
|
||||||
variables to be set as a simple form of configuration.
|
|
||||||
|
|
||||||
Each script should have a commented header which contains a "Configuration"
|
|
||||||
section that explains which values it requires to be placed in which variable.
|
|
||||||
When you have lots of scripts installed this process can be quite labour
|
|
||||||
intensive. The following shell command can be used as a stop gap until an
|
|
||||||
easier way to do this has been implemented.
|
|
||||||
|
|
||||||
grep -o 'hubot-[a-z0-9_-]\+' external-scripts.json | \
|
|
||||||
xargs -n1 -i sh -c 'sed -n "/^# Configuration/,/^#$/ s/^/{} /p" \
|
|
||||||
$(find node_modules/{}/ -name "*.coffee")' | \
|
|
||||||
awk -F '#' '{ printf "%-25s %s\n", $1, $2 }'
|
|
||||||
|
|
||||||
How to set environment variables will be specific to your operating system.
|
|
||||||
Rather than recreate the various methods and best practices in achieving this,
|
|
||||||
it's suggested that you search for a dedicated guide focused on your OS.
|
|
||||||
|
|
||||||
### Scripting
|
### Scripting
|
||||||
|
|
||||||
An example script is included at `scripts/example.coffee`, so check it out to
|
Gli script di Asjon sono nella cartella `scripts`.
|
||||||
get started, along with the [Scripting Guide](scripting-docs).
|
La [Scripting Guide](scripting-docs) di hubot è molto utile per imparare come funzionano
|
||||||
|
|
||||||
For many common tasks, there's a good chance someone has already one to do just
|
|
||||||
the thing.
|
|
||||||
|
|
||||||
[scripting-docs]: https://github.com/github/hubot/blob/master/docs/scripting.md
|
[scripting-docs]: https://github.com/github/hubot/blob/master/docs/scripting.md
|
||||||
|
|
||||||
### external-scripts
|
### Hosting
|
||||||
|
|
||||||
There will inevitably be functionality that everyone will want. Instead of
|
Asjon può essere hostato come un qualsiasi Hubot, ma richiede phantomjs per alcune funzioni.
|
||||||
writing it yourself, you can use existing plugins.
|
|
||||||
|
|
||||||
Hubot is able to load plugins from third-party `npm` packages. This is the
|
Il ramo `master` di Asjon è sempre hostato online ed è accessibile tramite telegram all'username
|
||||||
recommended way to add functionality to your hubot. You can get a list of
|
Asjon ROBOT.
|
||||||
available hubot plugins on [npmjs.com](npmjs) or by using `npm search`:
|
|
||||||
|
|
||||||
% npm search hubot-scripts panda
|
## Licenza
|
||||||
NAME DESCRIPTION AUTHOR DATE VERSION KEYWORDS
|
|
||||||
hubot-pandapanda a hubot script for panda responses =missu 2014-11-30 0.9.2 hubot hubot-scripts panda
|
|
||||||
...
|
|
||||||
|
|
||||||
|
Hubot e Asjon sono distribuiti sotto la MIT License
|
||||||
To use a package, check the package's documentation, but in general it is:
|
|
||||||
|
|
||||||
1. Use `npm install --save` to add the package to `package.json` and install it
|
|
||||||
2. Add the package name to `external-scripts.json` as a double quoted string
|
|
||||||
|
|
||||||
You can review `external-scripts.json` to see what is included by default.
|
|
||||||
|
|
||||||
##### Advanced Usage
|
|
||||||
|
|
||||||
It is also possible to define `external-scripts.json` as an object to
|
|
||||||
explicitly specify which scripts from a package should be included. The example
|
|
||||||
below, for example, will only activate two of the six available scripts inside
|
|
||||||
the `hubot-fun` plugin, but all four of those in `hubot-auto-deploy`.
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"hubot-fun": [
|
|
||||||
"crazy",
|
|
||||||
"thanks"
|
|
||||||
],
|
|
||||||
"hubot-auto-deploy": "*"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Be aware that not all plugins support this usage and will typically fallback
|
|
||||||
to including all scripts.**
|
|
||||||
|
|
||||||
[npmjs]: https://www.npmjs.com
|
|
||||||
|
|
||||||
### hubot-scripts
|
|
||||||
|
|
||||||
Before hubot plugin packages were adopted, most plugins were held in the
|
|
||||||
[hubot-scripts][hubot-scripts] package. Some of these plugins have yet to be
|
|
||||||
migrated to their own packages. They can still be used but the setup is a bit
|
|
||||||
different.
|
|
||||||
|
|
||||||
To enable scripts from the hubot-scripts package, add the script name with
|
|
||||||
extension as a double quoted string to the `hubot-scripts.json` file in this
|
|
||||||
repo.
|
|
||||||
|
|
||||||
[hubot-scripts]: https://github.com/github/hubot-scripts
|
|
||||||
|
|
||||||
## Persistence
|
|
||||||
|
|
||||||
If you are going to use the `hubot-redis-brain` package (strongly suggested),
|
|
||||||
you will need to add the Redis to Go addon on Heroku which requires a verified
|
|
||||||
account or you can create an account at [Redis to Go][redistogo] and manually
|
|
||||||
set the `REDISTOGO_URL` variable.
|
|
||||||
|
|
||||||
% heroku config:add REDISTOGO_URL="..."
|
|
||||||
|
|
||||||
If you don't need any persistence feel free to remove the `hubot-redis-brain`
|
|
||||||
from `external-scripts.json` and you don't need to worry about redis at all.
|
|
||||||
|
|
||||||
[redistogo]: https://redistogo.com/
|
|
||||||
|
|
||||||
## Adapters
|
|
||||||
|
|
||||||
Adapters are the interface to the service you want your hubot to run on, such
|
|
||||||
as Campfire or IRC. There are a number of third party adapters that the
|
|
||||||
community have contributed. Check [Hubot Adapters][hubot-adapters] for the
|
|
||||||
available ones.
|
|
||||||
|
|
||||||
If you would like to run a non-Campfire or shell adapter you will need to add
|
|
||||||
the adapter package as a dependency to the `package.json` file in the
|
|
||||||
`dependencies` section.
|
|
||||||
|
|
||||||
Once you've added the dependency with `npm install --save` to install it you
|
|
||||||
can then run hubot with the adapter.
|
|
||||||
|
|
||||||
% bin/hubot -a <adapter>
|
|
||||||
|
|
||||||
Where `<adapter>` is the name of your adapter without the `hubot-` prefix.
|
|
||||||
|
|
||||||
[hubot-adapters]: https://github.com/github/hubot/blob/master/docs/adapters.md
|
|
||||||
|
|
||||||
## Deployment
|
|
||||||
|
|
||||||
% heroku create --stack cedar
|
|
||||||
% git push heroku master
|
|
||||||
|
|
||||||
If your Heroku account has been verified you can run the following to enable
|
|
||||||
and add the Redis to Go addon to your app.
|
|
||||||
|
|
||||||
% heroku addons:add redistogo:nano
|
|
||||||
|
|
||||||
If you run into any problems, checkout Heroku's [docs][heroku-node-docs].
|
|
||||||
|
|
||||||
You'll need to edit the `Procfile` to set the name of your hubot.
|
|
||||||
|
|
||||||
More detailed documentation can be found on the [deploying hubot onto
|
|
||||||
Heroku][deploy-heroku] wiki page.
|
|
||||||
|
|
||||||
### Deploying to UNIX or Windows
|
|
||||||
|
|
||||||
If you would like to deploy to either a UNIX operating system or Windows.
|
|
||||||
Please check out the [deploying hubot onto UNIX][deploy-unix] and [deploying
|
|
||||||
hubot onto Windows][deploy-windows] wiki pages.
|
|
||||||
|
|
||||||
[heroku-node-docs]: http://devcenter.heroku.com/articles/node-js
|
|
||||||
[deploy-heroku]: https://github.com/github/hubot/blob/master/docs/deploying/heroku.md
|
|
||||||
[deploy-unix]: https://github.com/github/hubot/blob/master/docs/deploying/unix.md
|
|
||||||
[deploy-windows]: https://github.com/github/hubot/blob/master/docs/deploying/unix.md
|
|
||||||
|
|
||||||
## Campfire Variables
|
|
||||||
|
|
||||||
If you are using the Campfire adapter you will need to set some environment
|
|
||||||
variables. If not, refer to your adapter documentation for how to configure it,
|
|
||||||
links to the adapters can be found on [Hubot Adapters][hubot-adapters].
|
|
||||||
|
|
||||||
Create a separate Campfire user for your bot and get their token from the web
|
|
||||||
UI.
|
|
||||||
|
|
||||||
% heroku config:add HUBOT_CAMPFIRE_TOKEN="..."
|
|
||||||
|
|
||||||
Get the numeric IDs of the rooms you want the bot to join, comma delimited. If
|
|
||||||
you want the bot to connect to `https://mysubdomain.campfirenow.com/room/42`
|
|
||||||
and `https://mysubdomain.campfirenow.com/room/1024` then you'd add it like
|
|
||||||
this:
|
|
||||||
|
|
||||||
% heroku config:add HUBOT_CAMPFIRE_ROOMS="42,1024"
|
|
||||||
|
|
||||||
Add the subdomain hubot should connect to. If you web URL looks like
|
|
||||||
`http://mysubdomain.campfirenow.com` then you'd add it like this:
|
|
||||||
|
|
||||||
% heroku config:add HUBOT_CAMPFIRE_ACCOUNT="mysubdomain"
|
|
||||||
|
|
||||||
[hubot-adapters]: https://github.com/github/hubot/blob/master/docs/adapters.md
|
|
||||||
|
|
||||||
## Restart the bot
|
|
||||||
|
|
||||||
You may want to get comfortable with `heroku logs` and `heroku restart` if
|
|
||||||
you're having issues.
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user