collector to record subset of environment
Discourse is a helpful client if you are a member of one or more Discourse boards. While it’s easy enough to go to a web interface, with the helpme client you can:
Let’s get started!
If you need to test this first, see the developer setup instructions at the bottom of the page. If not, continue reading to interact with an active discourse installation. If you haven’t yet, install the dependencies for the discourse client, either just for discourse (or for all clients).
pip install helpme[discourse] pip install helpme[all]
The discourse helper usage will vary depending on the version of the discourse installation you are working with. If you have an older version of discourse, you will need to ask an administrator to generate a token for you. If you have a more recent version, and if the installation allows users to do so, you will be allowed to generate your own. Proceed below to the section that best describes your use case.
If your discourse site will allow you to generate a token, you simply need to be logged into your browser when you first run helpme. This means that you should first run helpme locally (not in a cluster environment), and then export the token in any command line environments where you don’t have a browser.
Step 1. Log into your browser
Once logged in, you can simply walk through using the client (see section Usage and it will ask you to copy paste a token into your terminal from the browser. Once this is done, the token will be added to your helpme configuration file, in case you need to export it to another environment for use.
Step 2: Run the client
If you are using a recent version of discourse, the client will have you open a browser and copy paste a message into the terminal on first use. You will only have to do this once.
Moving to a cluster
The first time you use helpme on a cluster (when you’ve already generated a token)
you should export the
to your environment.
export HELPME_DISCOURSE_TOKEN=xxxxxxxxxxxxxxxxxxxxxx export HELPME_DISCOURSE_CLIENT_ID=helpme-arid-caramel-1234
You can find these variables in your helpme configuration file under “discourse”:
cat $HOME/.helpme/helpme.cfg ... [discourse] discourse_client_id = helpme-phat-chair-9993 helpme_discourse_token = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If you are using an older version of discourse and need an admin to generate a token for you, simply export that token as follows:
See admin token generation if you are an admin and need to generate one or more tokens for your users.
If you post to a single board or category often, you can set some defaults in your configuration file (and won’t be prompted by the client). These defaults include the discourse board, your username, and the category to post to. If you don’t set the board, you will provide it as an argument like this:
$ helpme discourse stage.neurostars.org
But let’s say, for example, that we always are going to be using neurostars! We would export this environment variable to set it as default:
By default, all boards will be prefixed with https. If you need to use http instead, then you need to specify this:
If you don’t set the board via the environment or command line, it will prompt you for it when you run the client.
Here is how to set the category. If it doesn’t exist, it won’t be used and will give you a warning message.
Finally, you can also set your username.
The response might look like this:
Please enter your choice [Y/N/y/n] : y https://stage.neurostars.org/t/who-knows-where-the-time-goes/22 [submit=>discourse]
And then browse to https://stage.neurostars.org/t/who-knows-where-the-time-goes/22 to see it.
discourse command will ask for help from a Discourse board, meaning posting to it.
This means we will do the following:
Let’s walk through a few examples. We can first ask for help for general discourse, and be prompted for the board and category. An example asciinema is here
You can provide optionally the discourse board url and the category (or none at all!) Any of these three things work:
# Just have it prompt you for everything $ helpme discourse # Provide the board $ helpme discourse http://127.0.0.1 # Provide the board and topic $ helpme discourse http://127.0.0.1 Uncategorized
And don’t forget you can set variables in the environment. The command line specifications above override environment settings.
$ helpme discourse [helpme|discourse] Hello Friend! I'll help you ask a question to a discourse board today. What is the URL of the board you want to post to? (e.g., https://neurostars.org): http://127.0.0.1 What category board do you want to post to? (e.g., Uncategorized): Uncategorized Please provide a meaningful title for your question or issue: WHY AM I A DINOSAUR Now please provide detail: It's just so distressing. Please help. Would you like to send a terminal recording? Please enter your choice [Y/N/y/n] : n Environment USER|TERM|SHELL|PATH|LD_LIBRARY_PATH|PWD|JAVA_HOME|LANG|HOME|DISPLAY Is this list ok to share? Please enter your choice [Y/N/y/n] : y http://127.0.0.1/t/why-am-i-a-dinosaur/37 [submit=>discourse]
If I said yes to the asciinema recording, it would also show the path of it, and if I need to do it again (to some other helper) I can supply the asciinema on the command line.
$ helpme github --asciinema /tmp/helpme.5hcz3w6v.json vsoch/helpme
And here is the post created above!
If your discourse installation doesn’t support users generating their own tokens, then have no fear! Your administrator can generate one for you. There are again two options, and the first is recommended.
Discourse supports creating tokens on a per user basis. If you are a board user and don’t have admin, you should contact your board admin to ask for a token to be generated for you. If you do have admin access, you can navigate to the Admin Settings –> Users panel:
Click on a user of interest, and navigate down to the “Permissions” section.
And then click “generate.” It will show a token.
All Users Token
You can also generate a single global token (giving access to all users) to authenticate with the API. This token would be more appropriate for applications that must act on behalf of all users, and likely not recommended for helpme.
If you want this level of token and have admin status (such as with the container deployment above) if you click on your user icon in the top right and then Settings, you will see a button for “admin” in the top right:
Then you can click on the API tag to generate your token!
Whichever method you choose, export the token to the environment. It will be found by the client when you start helpme.
Once you have exported your token, you can use the client. The token will be
found the first time you run the client, and cached in your
file. If you are interested in how this works, see the developer documentation.
You can also ask for help from within Python! Here is how you create the client:
from helpme.main import get_helper helper = get_helper('discourse')
If you exported the token, it will be found:
If not, you would see an error message and you should export it first! Then you run the client like this:
This isn’t the intended use of the client, but please open an issue if you want help doing this in Python (and more examples).
If you want to test this helper first, you can deploy Discourse via a container. If not, skip this entire section.
$ mkdir -p /tmp/discourse $ cd /tmp/discourse $ curl -sSL https://raw.githubusercontent.com/bitnami/bitnami-docker-discourse/master/docker-compose.yml > docker-compose.yml $ docker-compose up -d
You should be patient while the database migrates, you can check it’s status like:
$ docker-compose logs discourse discourse_1 | discourse_1 | Welcome to the Bitnami discourse container discourse_1 | Subscribe to project updates by watching https://github.com/bitnami/bitnami-docker-discourse discourse_1 | Submit issues and feature requests at https://github.com/bitnami/bitnami-docker-discourse/issues discourse_1 | discourse_1 | nami INFO Initializing postgresql-client discourse_1 | postgre INFO Trying to connect to PostgreSQL server discourse_1 | postgre INFO Found PostgreSQL server listening at postgresql:5432 discourse_1 | postgre INFO PostgreSQL server listening and working at postgresql:5432 discourse_1 | nami INFO postgresql-client successfully initialized discourse_1 | nami INFO Initializing discourse discourse_1 | discour INFO Patching Discourse... discourse_1 | postgre INFO Trying to connect to PostgreSQL server discourse_1 | postgre INFO Found PostgreSQL server listening at postgresql:5432 discourse_1 | postgre INFO PostgreSQL server listening and working at postgresql:5432 discourse_1 | discour INFO Migrating database...
Until that’s done, you are best to not restart the containers (it resulted in many errors for me). When the migration is done (this is what you will see)
discourse_1 | Started GET "/manifest.webmanifest" for 172.18.0.1 at 2018-12-04 17:00:27 +0000 discourse_1 | Processing by MetadataController#manifest as */* discourse_1 | Completed 200 OK in 15ms (Views: 0.3ms | ActiveRecord: 3.6ms)