Bokeh Server documentation is incomplete

[victorhooi]

I was trying to find info on the Bokeh server, and I noticed that the documentation appears to be missing several sections (i.e. headings are there, but no text):

http://bokeh.pydata.org/en/latest/docs/user_guide/server.html https://github.com/bokeh/bokeh/blob/71c3d1753aceb57fcd6a0a3cd97abafc0c6bfc3f/sphinx/source/docs/user_guide/server.rst

For example, the Streaming Data, Large Data, Widgets and Dashboards and Development Options sections are all completely empty (of content).

From what I can tell, the Bokeh server has been in Bokeh for a while, so I'm not sure if this is an intentional omission, or if the documentation is simply not complete yet?

[bryevdv]

They are simply incomplete at the moment, unfortunately. However, I have a tutorial to give in a few weeks so I will be working mostly on docs between now and then.

[victorhooi]

Aha, coolies, a tutorial and finished documentation would be awesome =).

(I'm trying to build a log parsing/plotting script, and there's really not enough to go on in the current docs to actually use Bokeh server).

I did try to poke at the examples, but wasn't able to get them working:

> python vector.py
Using saved session configuration for http://localhost:5006/
To override, pass 'load_from_config=False' to Session
Traceback (most recent call last):
  File "vector.py", line 206, in <module>
    show(vplot(p1,p2))  # open a browser
  File "/usr/local/lib/python2.7/site-packages/bokeh/io.py", line 432, in vplot
    _push_or_save(layout)
  File "/usr/local/lib/python2.7/site-packages/bokeh/io.py", line 394, in _push_or_save
    push()
  File "/usr/local/lib/python2.7/site-packages/bokeh/io.py", line 375, in push
    return session.store_document(document)
  File "/usr/local/lib/python2.7/site-packages/bokeh/session.py", line 584, in store_document
    self.push(*json_objs)
  File "/usr/local/lib/python2.7/site-packages/bokeh/session.py", line 526, in push
    self.post_json(url, data=data)
  File "/usr/local/lib/python2.7/site-packages/bokeh/session.py", line 368, in post_json
    return self.execute_json('post', url, headers=headers, **kwargs)
  File "/usr/local/lib/python2.7/site-packages/bokeh/session.py", line 336, in execute_json
    return get_json(resp)
  File "/usr/local/lib/python2.7/site-packages/bokeh/util/serialization.py", line 72, in get_json
    return response.json()
  File "/usr/local/lib/python2.7/site-packages/requests/models.py", line 776, in json
    return json.loads(self.text, **kwargs)
  File "/usr/local/Cellar/python/2.7.9/Frameworks/Python.framework/Versions/2.7/lib/python2.7/json/__init__.py", line 338, in loads
    return _default_decoder.decode(s)
  File "/usr/local/Cellar/python/2.7.9/Frameworks/Python.framework/Versions/2.7/lib/python2.7/json/decoder.py", line 366, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
  File "/usr/local/Cellar/python/2.7.9/Frameworks/Python.framework/Versions/2.7/lib/python2.7/json/decoder.py", line 384, in raw_decode
    raise ValueError("No JSON object could be decoded")
ValueError: No JSON object could be decoded

and the server:

> python bokeh-server
No handlers could be found for logger "bokeh.resources"

    Bokeh Server Configuration
    ==========================
    ==========================
    python version : 2.7.9
    bokeh version  : 0.9.0dev-c63a78c-11-g5bc0c55
    listening      : 127.0.0.1:5006
    backend        : memory
    python options : debug:OFF, verbose:OFF, filter-logs:OFF, multi-user:OFF
    js options     : splitjs:OFF, debugjs:OFF

/Users/victorhooi/code/bokeh/bokeh/server/blaze/__init__.py:21: UserWarning: could not import multiuser blaze server No module named blaze.  This is fine if you do not intend to use blaze capabilities in the bokeh server
  warnings.warn(msg)
2015-04-10 12:17:18,981:INFO:tornado.access:200 GET /bokeh/userinfo/ (127.0.0.1) 5.45ms
2015-04-10 12:17:19,051:INFO:tornado.access:200 POST /bokeh/doc/ (127.0.0.1) 2.13ms
2015-04-10 12:17:19,056:INFO:tornado.access:200 GET /bokeh/getdocapikey/37620c15-2c62-4792-a9ae-0978331ded81 (127.0.0.1) 1.62ms
2015-04-10 12:17:19,128:INFO:tornado.access:200 POST /bokeh/bb/37620c15-2c62-4792-a9ae-0978331ded81/gc (127.0.0.1) 68.49ms
2015-04-10 12:17:19,134:INFO:tornado.access:200 GET /bokeh/bb/37620c15-2c62-4792-a9ae-0978331ded81/ (127.0.0.1) 3.04ms
2015-04-10 12:17:19,252:ERROR:bokeh.server:Exception on /bokeh/bb/37620c15-2c62-4792-a9ae-0978331ded81/bulkupsert [POST]
Traceback (most recent call last):
  File "/usr/local/lib/python2.7/site-packages/flask/app.py", line 1817, in wsgi_app
    response = self.full_dispatch_request()
  File "/usr/local/lib/python2.7/site-packages/flask/app.py", line 1477, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/usr/local/lib/python2.7/site-packages/flask/app.py", line 1381, in handle_user_exception
    reraise(exc_type, exc_value, tb)
  File "/usr/local/lib/python2.7/site-packages/flask/app.py", line 1475, in full_dispatch_request
    rv = self.dispatch_request()
  File "/usr/local/lib/python2.7/site-packages/flask/app.py", line 1461, in dispatch_request
    return self.view_functions[rule.endpoint](**req.view_args)
  File "/Users/victorhooi/code/bokeh/bokeh/server/views/bbauth.py", line 21, in wrapper
    return func(*args, **kwargs)
  File "/Users/victorhooi/code/bokeh/bokeh/server/views/backbone.py", line 64, in bulk_upsert
    clientdoc.load(*data, events='none', dirty=True)
  File "/Users/victorhooi/code/bokeh/bokeh/document.py", line 184, in load
    model = cls.load_json(obj_attrs)
  File "/Users/victorhooi/code/bokeh/bokeh/plot_object.py", line 177, in load_json
    instance.update(**attrs)
  File "/Users/victorhooi/code/bokeh/bokeh/plot_object.py", line 290, in update
    setattr(self, k, v)
  File "/Users/victorhooi/code/bokeh/bokeh/properties.py", line 326, in __setattr__
    (name, self.__class__.__name__, text, nice_join(matches)))
AttributeError: unexpected attribute 'sources' to DataRange1d, possible attributes are end, name, names, range_padding, renderers, session, start or tags
2015-04-10 12:17:19,261:ERROR:tornado.access:500 POST /bokeh/bb/37620c15-2c62-4792-a9ae-0978331ded81/bulkupsert (127.0.0.1) 34.78ms

Not sure if the Blaze error message is an issue.

[gene-telligent]

Out of curiosity -- what script were you trying to run with bokeh server? vector.py seems to be an example of file output.

[victorhooi]

@gene-telligent I'm running this script:

https://github.com/bokeh/bokeh/blob/9c4626835010e15480fe4f27e761d4df253afbf3/examples/plotting/server/vector.py

It's located in the examples directory, under the server directory - which is why I think it's meant to run with the Bokeh server.

[victorhooi]

@bryevdv I just saw 0.9.0 came out, with re-vamped docs =). Awesome stuff!

However, curious if there was any update on the Bokeh-server side of things, or if you were still giving that tutorial on bokeh-server?

[damianavila]

http://bokeh.pydata.org/en/latest/docs/user_guide/server.html#important-note

[bryevdv]

@victorhooi to expand a bit: I did not end up covering the server in the tutorial, and updating and expanding the rest of the user guide pretty much consumed all my time. Work is currently underway (as in, a budget has been allocated to fund extra experienced dev help, in the short term) to split off the server into it's own pip/conda package, improve the deployment story, make feature improvements, and add to the docs. But that efforts was not started in time to make it into this release, unfortunately. Long term, this is an area where, frankly, we really need help and new contributors.

[victorhooi]

@bryevdv Sure, I appreciate the update.

Good news to hear budget has been allocated for bokeh-server development, definitely looking forward to cool things from you guys.

Is there a separate place/repo/blog we should look to, for news on bokeh-server in the near future?

[Frikster]

Hi, any update on when the following sections might be completed? Reading the posts I can see that it is indevelopment but I'm wondering whether we're talking months or years before these sections will see a public release:

Downsampling with Server Reacting to User Interactions Building Bokeh Applications Deploying for Production

In the meantime, without these tutorials, can anyone point me to my best bet if I want to create an app that has an image where the user clicks a pixel and then an updated image appears? (Doing seed-based correlation analysis)

[birdsarah]

@Frikster, did you see this update from @bryevdv https://groups.google.com/a/continuum.io/d/msg/bokeh/LORmlhbVqR0/ryzcsF0tDgAJ

[bryevdv]

FYI there is an entirely new tornado and websocket-based server on master, to land in 0.11 in December. This new server is simpler, easier to use and deploy and write apps for, more robust and scalable. It will arrive with extensive documentation and examples/demos.

[Frikster]

@bryevdv Any word on whether 0.11 will be done before the new year?

I would like to get my project off the ground in January. Still, sadly, finding that impossible without the missing docs. Currently using R shiny. Not good since everyone at work uses Python.

[bryevdv]

0.11 will be released on January 6 (with docs)

Edit: as an aid to prioritization @Frikster can you let us know what topics you'd be interested in seeing?

[Frikster]

Hi, sadly I went off for holidays in the last 2 weeks so I doubt my input will help at this late stage. Documentation still being released today? I've reread most of the documentation already available and am eagerly clicking the refresh button every now and again :P

I think using R Shiny's tutorials as a standard to compare against is a good idea: http://shiny.rstudio.com/tutorial/. Their tutorials have an excellent hands on approach. I'dbe very happy if I saw a Bokeh tutorial in lessons in a similar way R Shiny structures theirs. Another web application framework with great documentation I've had great success with is Adam Hajari's Spyre: https://github.com/adamhajari/spyre

Let's get specific. Three key things come to mind that these docs do really well that Bokeh severely lacks (please do read # 3):

1) A clear cut way of distinguishing Input vs Output (Spyre) or in the case of R Shiny, server and ui. I suppose for Bokeh that would involve Document and User and how the two interact. See here https://github.com/adamhajari/spyre/blob/master/README.md and then: https://github.com/adamhajari/spyre/blob/master/docs/source/inputs.rst https://github.com/adamhajari/spyre/blob/master/docs/source/outputs.rst Also check out the tutorial given last year in Seattle. The charts showing how the different components interact was very very useful in lightening the learning curve for me https://github.com/adamhajari/spyre/blob/master/tutorial/pydata2015_seattle/pydata2015_seattle.ipynb

For R Shiny, they did a great job in the following lessons of delineating server from ui http://shiny.rstudio.com/tutorial/lesson4/ http://shiny.rstudio.com/tutorial/lesson5/ http://shiny.rstudio.com/tutorial/lesson6/ In lesson 5, I really again appreciated that they used images to clearly highlight which elements are being run during the life cycle of the app

2) Perhaps most importantly, step by step instructions on how to get an app online via different sample mediums. http://shiny.rstudio.com/tutorial/lesson7/ And here are step by step instructions for getting an app online at shinyapps.io: http://shiny.rstudio.com/articles/shinyapps.html

Likewise, Adam suggests using Heroku or pythonanywhere at the end of his talk in Seattle and sure enough he provides step by step instruction for getting a Spyre app online using Heroku: http://adamhajari.github.io/2015/04/21/deploying-a-spyre-app-on-heroku.html

3) This one is absolutely crucial to me and sadly it doesn't seem like Spyre as these capabilities: I need an upload button. Or some method by which a user can visit my website application, let the app look at their local data and then see an outputted Bokeh plot or chart that they can additionally manipulate using widgets. R Shiny has a great file upload widget in this regard: http://shiny.rstudio.com/gallery/upload-file.html

It would be really great if there would be some way to give the app read and write privileges to some local files on a user's device (that the user picks), although I imagine the security issues and work required to get around them while maintaining security, are non-trivial. I don't have any experience in this area so all I can say is if the app can manipulate gigabyte-large files on some user's device without them having to be uploaded, I'd be on cloud 9.

[bryevdv]

@Frikster

Hi, sadly I went off for holidays in the last 2 weeks so I doubt my input will help at this late stage. Documentation still being released today? I've reread most of the documentation already available and am eagerly clicking the refresh button every now and again :P

We can and will be updating, refreshing, and re-deoploying the 0.11 docs even after the release, so your input is extremely valuable. There is currently much, much more documentation on the new server (guidance for proxies, load balancers, process managers, architecture notes, use-case descriptions, and many more examples) than the old server ever had, but we are not done yet. We've all been working furiously the last few weeks, but we all have human limits as well. :)

A clear cut way of distinguishing Input vs Output (Spyre) or in the case of R Shiny, server and ui.

I agree, and our next big focus is improved and auto-layout, and I expect this work will largely address the things you are saying here.

Perhaps most importantly, step by step instructions on how to get an app online via different sample mediums.

@birdsarah has specifically expressed interest in an end-to-end Heroku process that can be used out off the box. I look forward to this, again it's just a matter of hours in the day times number of people available.

This one is absolutely crucial to me and sadly it doesn't seem like Spyre as these capabilities: I need an upload button

This is interesting, my first answer is there is nothing preventing you from writing an app that does this, but that many apps would not need this. So it's not clear to me that it should be "built in" tho we'd certainly like to make it as simple and easy as possible!

It would be really great if there would be some way to give the app read and write privileges to some local files on a user's device

The example app here goes in that direction:

https://github.com/bokeh/bokeh-demos/tree/master/happiness

We will have a video demo/tutorial and walkthrough of this demo soon.

I apologize for the brief reply, I'll write more later but I am literally dead on my feet right now. :) These kinds of observations are extremely valuable and I would love to engage you more for help or at least ideas to improve our docs and examples.

[damianavila]

These kinds of observations are extremely valuable and I would love to engage you more for help or at least ideas to improve our docs and examples.

I want to emphasize that... many thanks to come up with concrete proposals to improve our docs. That help us a lot. Thanks again @Frikster

[Frikster]

There is currently much, much more documentation on the new server (guidance for proxies, load >balancers, process managers, architecture notes, use-case descriptions, and many more examples) >than the old server ever had, but we are not done yet.

I must clearly have been looking in the wrong direction! The documentation I've been looking are these two: http://bokeh.pydata.org/en/0.10.0/docs/user_guide/server.html http://bokeh.pydata.org/en/0.8.1/docs/user_guide/server.html I haven't seen them change here. Could you direct me to where I might get more of the best notes? I intend to be as up to date as possible.

This is interesting, my first answer is there is nothing preventing you from writing an app that does >this, but that many apps would not need this. So it's not clear to me that it should be "built in" tho >we'd certainly like to make it as simple and easy as possible!

I'm approaching this as a junior data scientist and in my experience thus far every project I've worked on typically involves designing a web app such that third parties can insert their own data and use the app for the app to visualize their own data.

This is the most recent problem I am working on. I need to create a web-based app such that any user can come to the website with their csv and leave happy with a bokeh plot and/or chart.

I'll take your word of experience though. As such, I have started looking at the happiness app. I'm actually having trouble running it. I'll report my issue soon over at it's repo (or hopefully I'll solve it)

[bryevdv]

I must clearly have been looking in the wrong direction!

Yes, you are looking at old versions of the documentation (one quite old, 0.8.1 is at least a year or so ago). The latest documentation is always at:

http://bokeh.pydata.org/en/latest/

In particular the new server is covered in these sections:

http://bokeh.pydata.org/en/latest/docs/user_guide/server.html http://bokeh.pydata.org/en/latest/docs/user_guide/cli.html

with more additional developer-oriented architecture notes here:

http://bokeh.pydata.org/en/latest/docs/dev_guide/server.html

Additionally there is a new live server app example gallery with links to the source code here:

http://demo.bokehplots.com

This site is a WIP and we will be polishing and adding to it in the coming weeks.

This is the most recent problem I am working on. I need to create a web-based app such that any user can come to the website with their csv and leave happy with a bokeh plot and/or chart.

This sounds like a great application. If there's anything about this that you can share at the end of the day (just a link to tweet out, or even a code example contribution) it would be a great service to the Bokeh community. (But I understand that is often not possible)

As such, I have started looking at the happiness app. I'm actually having trouble running it. I'll report my issue soon over at it's repo (or hopefully I'll solve it)

If you run into issues with this please start a separate issue, and ping @birdsarah

[Frikster]

@bryevdv EDIT: This is from the new docs. Realized too late my question isn't really in keeping with the issue so I deleted it

Lifecycle Hooks Sometimes it is desirable to have code execute at specific times in a server or session lifetime. For instance, if you are using a Bokeh Server along side a Django server, you would need to call django.setup() once, as each Bokeh server started, to initialize the Django properly for use by Bokeh application code.

It would be helpful if one of your example apps utilized these lifecycle hooks. https://github.com/bokeh/bokeh/tree/master/examples/app

[bryevdv]

There's more docs to add, but I'd like to make individual issues for further additions (this original issue is itself quite old and refers to no-longer-relevant things at the top)

[e-pet]

Just a quick side note: It seems to me that the old docs are higher ranked by google. At least for me, googleing, e.g., "bokeh server downsampling" leads me to the 0.10 docs. Additionally, these don't indicate at all that they're outdated - maybe you could make that more obvious somehow to prevent many people from looking at the old docs!

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.