Re: Configuation files

[Tobias Oberstein]

Hi Tim,

Am 14.08.2014 15:47, schrieb tim.in...@gmail.com:
> Hi Tobias,
>
> I have my evaluation of crossbar.io working, to deliver dynamic
> information from a database to a webpage,
> largely by building on your examples and very little understanding on my
> part.

So the examples do already help;) Good to know ..

>
> One area that I need to understand better is the crossbar.io
> configuration file. Is there a 'user manual' for this
> that details everything that can go in this file, and what each keyword
> means?

Yes. It's not in a single page, but each option is discussed under the
respective documentation page.

http://crossbar.io/docs/Configuration-Overview/
http://crossbar.io/docs/WebSocket-Transports/

and so on.

> I have found many examples of different config. files and I recognise
> what a lot of the entries might mean,
> but there is ambiguity. It might help if each line were commented,
> explaining exactly what crossbar.io does
> with that line of information.

Yes, I agree, it would help if the examples configs would have comment
lines.

Unfortunately, JSON does not allow embedded comments;(

Which is the main reason we want to add YAML as an alternative config
format:

https://github.com/crossbario/crossbar/issues/99
http://en.wikipedia.org/wiki/Yaml

Let me see if I can add this in <1 hour;) Needs to be done anyway ..

Crossbar.io codebase is already prepared to support arbitrary config
formats (as long as they are as "capable" as JSON)

Cheers,
/Tobias


>
> For example, is there a list of "types", and for each "type" a list of
> associated entries ?
>
> Regards,
> Tim
>
> --
> You received this message because you are subscribed to the Google
> Groups "Crossbar" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to crossbario+...@googlegroups.com
> <mailto:crossbario+...@googlegroups.com>.
> To post to this group, send email to cross...@googlegroups.com
> <mailto:cross...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/crossbario/b9a43bc1-b48b-4f35-bbd7-66de9d6b9548%40googlegroups.com
> <https://groups.google.com/d/msgid/crossbario/b9a43bc1-b48b-4f35-bbd7-66de9d6b9548%40googlegroups.com?utm_medium=email&utm_source=footer>.
> For more options, visit https://groups.google.com/d/optout.

[Tobias Oberstein]

Hi Tim,

alright, Crossbar.io trunk now support YAML as an alternative
configuration format.

$ crossbar start
2014-08-14 17:41:43+0200 [Controller 4180] Log opened.
...
2014-08-14 17:41:43+0200 [Controller 4180] Starting from node
directory c:\Temp\.crossbar
2014-08-14 17:41:44+0200 [Controller 4180] Starting from local
configuration 'c:\Temp\.crossbar\config.yaml'

where "config.yaml" can contain comments


controller: {}
workers:
- realms:
- name: realm1
roles:
- name: anonymous
permissions:

# allow just anyone to do anything ..
- {call: true, publish: true, register: true, subscribe: true,
uri: '*'}
transports:
- endpoint: {port: 8080, type: tcp}
paths:
/: {directory: .., type: static}
ws: {type: websocket}
type: web

# we are just running a single worker of type "router"
type: router


===

Crossbar.io will do the following:

1. If no "--config" option is given, first check if there is a
CBDIR/config.json. If so, use that.
2. If not, check if there is CBDIR/config.yaml. If so use that.
3. If not, bail out

If "--config" is given, use that, and determine file type by file extension.

Means: it should behave "with least suprise".

===

Now I only need to learn YAML;) No clue, other than it's used widely.

Cheers,
/Tobias

Am 14.08.2014 15:47, schrieb tim.in...@gmail.com:
> Hi Tobias,
>
> I have my evaluation of crossbar.io working, to deliver dynamic
> information from a database to a webpage,
> largely by building on your examples and very little understanding on my
> part.
>

> One area that I need to understand better is the crossbar.io
> configuration file. Is there a 'user manual' for this
> that details everything that can go in this file, and what each keyword
> means?

> I have found many examples of different config. files and I recognise
> what a lot of the entries might mean,
> but there is ambiguity. It might help if each line were commented,
> explaining exactly what crossbar.io does
> with that line of information.
>

[tim.in...@gmail.com]

Hello Tobias,

Wow, that was fast !
I think supporting a config file that can contain comments (YAML) is a big step forward
in helping people to understand the configuration.

Here is some feedback on the documentation. This is going to sound negative but I mean
it to be constructive. If you can understand what I am finding difficult I hope you will be able
to add enough to the documentation to make it much easier for lots more people to understand
and use. I am beginning to fall in love with Crossbar.io, but not the documentation...

One of the biggest hurdles for me in using Crossbar.io is that I don't know what
it is capable of at the coding level, and I think that might be answered from the configuration documentation.
I've already looked at the documentation and often found more questions than answers.

For example, I look in a configuration file and see "type": "container"...
so I look at the documentation here http://crossbar.io/docs/,
click on the container configuration link and find all the documentation - great.
I look back at the configuration file and see an entry "components": [
inside the container, but when I try and look up "components" under the
"container configuration" I don't find anything.
There is a link to "router components" under "router configuration" but its
unclear if that is valid also for container components.

In summary, its great to have demos and example configuration files giving a tantalising
glimpse of what might be possible and then frustrating when you can't find documentation
 that covers the items in those examples/config.

BR, Tim

[Tobias Oberstein]

Hi Tim,

Am 15.08.2014 16:26, schrieb tim.in...@gmail.com:
> Hello Tobias,
>
> Wow, that was fast !
> I think supporting a config file that can contain comments (YAML) is a
> big step forward
> in helping people to understand the configuration.

Do you think it would make sense to rewrite the examples (app templates)
and docs to YAML format while adding comments?

I mean, there might be a downside: JSON can be read probably by anyone.
YAML might not be readable to all.

>
> Here is some feedback on the documentation. This is going to sound
> negative but I mean
> it to be constructive. If you can understand what I am finding difficult

No, this is great! Don't hold back with critics .. it's not about "being
inpolite" .. we need to improve on this.

> I hope you will be able
> to add enough to the documentation to make it much easier for lots more
> people to understand
> and use. I am beginning to fall in love with Crossbar.io, but not the
> documentation...

I see. Lot's of feedback we got is like this: "this is awesome. but you
guys can't explain things, and the docs suck". I totally agree.

We don't have marketing pros or technical writers on the team. No
excuse, but that's a fact. Guess we need help with that.

>
> One of the biggest hurdles for me in using Crossbar.io is that I don't
> know what
> it is capable of at the coding level, and I think that might be answered
> from the configuration documentation.
> I've already looked at the documentation and often found more questions
> than answers.

Not good.

>
> For example, I look in a configuration file and see "type": "container"...
> so I look at the documentation here http://crossbar.io/docs/,
> click on the container configuration link and find all the documentation
> - great.
> I look back at the configuration file and see an entry "components": [
> inside the container, but when I try and look up "components" under the
> "container configuration" I don't find anything.
> There is a link to "router components" under "router configuration" but its
> unclear if that is valid also for container components.

Yes. Confusing. Incomplete. I've opened

https://github.com/crossbario/crossbar/issues/106

to track that specific issue.

>
> In summary, its great to have demos and example configuration files
> giving a tantalising
> glimpse of what might be possible and then frustrating when you can't
> find documentation
> that covers the items in those examples/config.

That sounds like you would welcome having YAML configs with extensive
comments inside? Probably even backlinks into the docs?

Thanks for feedback!
/Tobias

>
> BR, Tim

>
>
> --
> You received this message because you are subscribed to the Google

> Groups "Autobahn" group.

> To unsubscribe from this group and stop receiving emails from it, send

> an email to autobahnws+...@googlegroups.com
> <mailto:autobahnws+...@googlegroups.com>.
> To post to this group, send email to autob...@googlegroups.com
> <mailto:autob...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/autobahnws/70de0b1e-4618-4176-9da9-4068413cba4a%40googlegroups.com
> <https://groups.google.com/d/msgid/autobahnws/70de0b1e-4618-4176-9da9-4068413cba4a%40googlegroups.com?utm_medium=email&utm_source=footer>.

[tim.in...@gmail.com]

Hi Tobias,

Re-writing all the config files in YAML sounds a lot of work, and I'm not sure that is necessary.
Sure it would be great to have verbose comments in the config. files, explaining all the details, and
links back to the documentation, but that sounds a monumental job.
Another way would be to make sure that all the demos have multiple references to the documentation
so its easy to get to the documentation no matter where you find the demo (github, tavendo, http://crossbar.io, etc),
and then make sure that everything in every demo has documentation to explain it.

I would say that as you add a new demo, much more important than the demo itself is having the documentation
in place first explaining how the demo works and any new configuration elements the demo introduces.

Also, in trying to understand Crossbar.io I am having to learn or understand a lot of other support stuff that Crossbar.io
builds on (Autobahn, WAMP, WebSocket, Twisted(whatever that is), etc). It would be good to have a picture of how all this fits together,
and perhaps, in particular, explain what each of these adds to the equation.
The problem for people like me is that we can see from the demos that Crossbar.io is incredible, but the learning curve
with all these new modules at times seems steeper than vertical !

For quite a long time I couldn't figure this out.
WebSocket I understood right way because it adds native support for the bi-direction comms that has been sadly missing from browsers
for so long.
I think I now have a clear picture that WAMP is an implementation of WebSocket, and that Autobahn is an implementation of WAMP,
and that Crossbar.io adds to Autobahn features like polyglot and a built in static web server(brilliant idea!).

Cheers,
Tim

[tim.in...@gmail.com]

Tobias,

Have you thought about an FAQ for Autobahn and Crossbar.io? That could be another resource
that helps explain what both of these are all about as well as how to configure them.

Tim

[Alexander Gödde]

Hi!

Thanks for your suggestions - this is the kind of feedback we're looking for. We've added your points in an issue for Crossbar (#017).

We're working on a tutorial that explains a simple but functional JavaScript application in detail - and we'd like to roll that out for the other languages we support for Autobahn.

Regarding the FAQs - it would be a great help to us if you could list some of the specific questions that you had when you started working with WAMP / Autobahn / Crossbar. We'd then definitely try to answer these as part of our FAQ.

Regards,

Alex

[Tobias Oberstein]

FAQ: good idea. We are collection suggestions for improving docs here: https://github.com/crossbario/crossbar/issues/107

Am Samstag, 16. August 2014 20:57:48 UTC+2 schrieb tim.in...@gmail.com:

[tim.in...@gmail.com]

Hello Tobias and Alexander,

I will try and add questions here: https://github.com/crossbario/crossbar/issues/107

It strikes me now that perhaps my biggest challenge was trying to deal with many new things all at once
(Websocket, WAMP, Crossbar.io, Autobahn, Twisted, Python, HTML, CSS, javascript, etc). I have many years experience with C and C++, but have
never looked at Python(my head has been yanked out of the sand and my eyes are now wide open!) and
the differences from C make a lot of new things very challenging, even though there is a lot of similarity too; The devil
is in the detail.
Of course, this is my problem not yours, but if your examples had lots of explanation it would help people like me to try out
Crossbar.io quicker and with less pain and to persevere with it. There were times when I thought the time investment
was getting too much for such slow progress, but I'm glad now I carried on. Things are becoming more clear, and I have
a great, but simple, application thanks to Crossbar.io.

Perhaps one of the things to cover in your tutorial is which things a newcomer needs to learn a bit more about and what
they can safely ignore for now. When I first started, I looked at the Crossbar.io demos, liked what I saw, and realised
this was exactly what I needed to transfer data out of a Firebird database, dynamically and triggered by database activity, and
across to a remote web browser for display, so I immediately started about modifying the crossbar.io pubsub demo
to perform some tests. This is where the learning curve went near vertical. I didn't know where to start ! I didn't know
which modules I needed to consider editing first, WAMP, Twisted, Autobahn, or Crossbar.io.

I know now, for example, that I didn't need to initially worry about WAMP, or Twisted but I did need to understand
the difference between Autobahn and Crossbar.io or, at least, what each of these does.
I know now (I think) that Autobahn, built on top of Websockets, WAMP and Twisted, basically implements
the websockets protocol (and much more) and allows me to pass data from the database to the web browser
without worrying about the transport etc.
Crossbar.io allows multiple applications to run on potentially any number of different
machines and talk to each other using the Autobahn support.
Crossbar.io also supports a simple web-server for static pages, so I don't have to have a separate web-server.
But the boundaries between Autobahn and Crossbar.io are still a very grey area to me.
If you asked me what exactly Crossbar.io does that Autobahn does not I would struggle to answer.
I think the answer is that my Python applications would be written on top of AutobahnPython, and that
Crossbar.io is responsible for starting those applications (as referred to by the Crossbar configuration file),
supports applications to be written in a number of other languages, is responsible for running a web-server,
is responsible for passing configuration information from the configuration file to the Autobahn derived
application (eg name of communications realm).
Is any of that right ?

I think the tutorial could add a lot of help if it explains everything in detail. For example, in the Python file
hello.py for the pubsub demo it might be helpful to add comments at each of the import statements.
Some examples...
1.
## Import just the sleep class from the Python module Autobahn
## Autobahn itself is derived from the 'util' class in the Twisted module
from autobahn.twisted.util import sleep

2.
## AppSession is the main application class and is derived from the Autobahn class ApplicationSession
## This class provides access to the communication mechanisms that can be used by your applications
## to communicate over transport mechanisms such as websockets.
class AppSession(ApplicationSession)

3.
Give detailed information about the call to subscribe, saying what each of the parameters is, what type
they are and what information they can take. eg what can the topic string be or consist of.
Why is the demo topic 'com.example.onhello' and why are there periods in this string. What is there
significance?

4.
yield self.publish('com.example.oncounter', counter)
yield sleep(1)
Why is the yield keyword used in these statements. Is that critical or optional and what is its significance ?

5.
What can the application do in the ApplicationSession derived class, are there any limitations
or special requirements ?

A lot of the answers to the questions posed above are probably documented elsewhere but having all
the information in one place is of great benefit to the newcomer, otherwise finding the correct documentation
from many different sources and pulling it all together can be daunting, possibly overwhelming for some.

Hope this helps !

Cheers,
Tim

[tim.in...@gmail.com]

BTW, Your answers to this thread..
crossbar.io: reasons why onJoin() might not be called?
Answer quite a lot of questions. By going through the sample config file that Scott provided
and adding comments about specific parts together with your other answers you have disclosed
a lot more helpful information.

Why not take all the questions posed in this googlegroup and add them to an FAQ on the crossbar.io
documentation site ?

Tim

[Alexander Gödde]

Hi Tim!

Thanks for the continued feedback!

I added your remarks about more comments in code to https://github.com/crossbario/crossbar/issues/107

Generally: The more specific a request for documentation, the more likely we'll be to fulfill it. And anything added to the above issue will not get lost in the noise of the mailing list.

I can sympathize with your feelings: I only started out in programming a few years back, and I haven't fully lost the sense of being overwhelmed whenever I start with some new technology.

I can't say much about the Python demos, but for the JavaScript side, I'm working on a tutorial which tries to do what you're talking about: going over a simple Autobahn/Crossbar application and explaining every single line of code that related to our technologies. 

If you're also working with JavaScript, I'd be very much interested in your feedback about this once it's up. It's easy to lose sight of what people starting out in a technology will see as problematic when you've been working with something for so long.

Regards,

Alex

[tim.in...@gmail.com]

Hi Alex,

Firstly let me say thanks so much to both of you  for your great support, Autobahn and crossbar.io
have huge potential. My imagination is running wild with thoughts on different application areas that they could benefit.

I am mainly working with Python, but I am also working a little bit, out of necessity, with javascript, but only
to subscribe to the pubsub messages, pickup a string of data and display it to a few elements in a web page.

For me the Javascript side of things was not the difficult part. I could clearly see the statements there to subscribe
to messages and was able to pickup new data and forward it without much fuss.

The more challenging part was trying to separate all the components in the backend, and in particular the Python/
Autobahn/Crossbar mix.

Let me know when you have the tutorial ready and I'll let you have any comments I can. Of course
I am not on the same part of the learning curve that I was once, thankfully !

Thanks
Tim

[Roger Erens]

I'd like to thank Tim for bringing this up!

I'm still in the phase of having difficulty to create a mental map of crossbar.io and autobahn|python, and deciding which examples/demos to look at next.

I see the documentation improving, great to see where it's going, Alexander and Tobias. I can't believe you only use 24 hours in a day...

This list pointed me to KnockoutJS, which has a very nice interactive tutorial, I'd recommend it to others. I'm curious to see what Alexander comes up with...

And a suggestion for web-presenting the comments that Tim wants sprinkled spuriously in code: separated in such a way that both the code and the comments look less daunting by means of pycco:

http://fitzgen.github.io/pycco/

Finally (this could be only me of course): even though the hello template is very simple, it's still 4 concepts being introduced/shown at once. With all the other new stuff Tim already mentioned that newbies need to wrap their head around, I'd say that 1 babystep at a time is enough. Maybe have even simpler hello1, hello2, hello3, and hello4 templates available before bringing up the 'grand finale' of combining PubSub, and RPC both ways, all together :-). This way you'll give a newbie 5 opportunities to get a feeling of accomplishment when he get's the 'Aha'-erlebnis and starts feeling confident about the code and the output rolling over the console.

Cheers,

Roger

Op donderdag 4 september 2014 15:39:04 UTC+2 schreef tim.in...@gmail.com:

[tim.in...@gmail.com]

The more I think about the Crossbar.io/Autobahn/Python mix the more clear the

picture is becoming. The fog is slowly clearing as I think about and understand a little better what is involved in

achieving a simple pubsub demo where, essentially and conceptually, data is pushed from

a simple Web Server to an HTML page displayed in a Web Browser; This happens automatically, as new

data becomes available at the Web Server, and does not require intervention by a person(eg pressing the browser refresh button)

sat in front of the Web Browser. The problem in trying to understand

the Crossbar.io/Autobahn/Python mix is that to achieve the above goal requires a staggering amount

of complexity for something that sounds so simple. Complexity

that is hidden away inside Crossbar.io/Autobahn, together with many other software layers,

and us newbies need to identify what we can safely ignore and where to focus.

Writing this entry is helping me understand Autobahn and Crossbar.io and hopefully others will

correct my mistakes and thereby help clarify many things for other newbies.

First there is the concept of pubsub, pushing data into a pipe at the server end and that data dropping

out the other end of the pipe into our lap, our browser lap. This simple concept is immediately complicated

by one of the amazing autobahn features that lets any number of clients subscribe to the data published

by the server; Autobahn effectively adds a new ‘pipe’ between the server and each subscribed client and

copies the data out to each client. So in the simple pubsub demo, the data at the server end can be displayed

in any number of web browsers, without the server knowing how many browsers are watching or how

to route the information to them. The data routing is all taken care of by Autobahn.

At Coastform we are experimenting with Autobahn/Crossbar.io to offer access control features.

In a simple example the data is the name of a user who has just walked through a security door, together with

the time of access and a pathname to a photograph of the person. This data is extracted from an

event-driven firebird database by a simple Python script and pushed across to the waiting web browsers

by Autobahn, in near real time. Somebody scans their tag at a door reader and within a fraction of a second

their name and picture are displayed in a remote web browser(s) perhaps located at the entry door or

perhaps at a security desk elsewhere in the building. What a fantastic result ! And all with a few lines

of Python code plus a little more HTML and Javascript. All thanks to the supporting framework provided

by Autobahn, Crossbar.io, and the many other layers they are built on.

One critical development in all of this, that slipped in under my radar until just recently, is webSockets.

WebSockets essentially add native HTML support for bi-directional communication between web server and

browser, so the server can deliver data over to the browser as it becomes available rather than waiting

for a user to refresh their web page. Although many other solutions have been created to allow

similar bi-directional comms, these are typically convoluted. WebSockets are a much, much cleaner solution.

It is something that has been sadly lacking in HTML for way too long. Web browsers have become very

sophisticated graphics rendering engines over recent years, capable of formatting data and graphics presentation

any which way desired, and remote from the data source, but until the introduction of webSockets it has

been difficult to tap into that powerful display. With Autobahn and Crossbar.io making it easy to use

webSockets, they have opened up a new universe of opportunity and will change the way many applications

are written to display data and graphics. Finally there is an easy way to exploit the powerful features of web browsers.

Hardware products no longer need to have a dedicated user interface;

The user interface can run on a smartphone, tablet, or any other device capable of running a modern Web browser.

Many applications no longer need to include complicated code

to format data and display graphics, they can use the sophisticated rendering engine built-in to modern

browsers. Networked device and apps do not need to solve the problem of offering a remote user interface or transmitting data

long distances to be displayed on remote terminals; Autobahn and Crossbar.io handle all of that, freeing products

and applications to focus much more on things specific to them. Wow! What flexibility and power!

What does Crossbar.io do? Hmmm, a lot! I think that’s part of the problem trying to understand where

it fits in. I think another hurdle in the way of understanding is that the authors of Crossbar.io have added

a very powerful feature that enables a single command to start any number of client or server application

components, as well as crossbar itself, and have used this feature in many of the examples/demos, so a newbie

has to dig deeper and understand a lot more to try and figure out what is going on.

All the necessary information is held neatly in a single (JSON)configuration file, but that introduces another hurdle

in the learning process. A newbie tries to dig a little to see what is going on and finds a JSON file, whatever that is,

and then encounters a list of apparently disjoint string pairs...

I think a better place for a newbie to start would be Autobahn because it is the thing offering an easy

way to use webSockets (via another layer called WAMP). It also includes a basic WAMP router, something

that is necessary to actually get the data to the right destination. ie Autobahn includes everything needed

to see a simple PubSub demo in operation. You can clearly see an example broken down into three components:

router, backend(or server), and frontend(or user interface). You can start these components separately too,

so there is less black magic to worry about.

Once you can see these components, the delightful simplicity of the system becomes apparent. The communication

is limited and directed using a couple of strings, which can be anything you like(I think),

to define a realm and topics. The realm is simply a way of ring fencing those speakers and listeners that want to talk about the

same things (topics). A topic is just a way of tagging or identifying a specific bit of information, such as a person’s name.

The backend and frontend components can be just a few lines of code, communicating using nothing more than

a few string identifiers to couple them together, with the coupling performed by Autobahn and its router. Amazing.

Maybe the Crossbar.io demos page should point newbies at the Autobahn demos first ?
Maybe the demos should all start out as Autobahn demos that are tweaked to show where

Crossbar adds more?
 ie each demo could have an Autobahn variant, so the boundaries between

components is clear and easily identified, and a crossbar.io variant which allows the advanced features of Crossbar.io

to be equally easily identified and tested. As I said

earlier Crossbar.io uses a single (JSON) configuration file to pull together all the configuration information

for a communicating application components, no matter how many of them there are. Application

components can be referenced in the configuration file, in which case Crossbar will automatically start them.

Furthermore, if an application component is written as a Python script, the main class (or entry point) can be referenced in the

configuration file, in which case Crossbar will start the Python script at your specified entry point.

Crossbar.io does much more than offer this convenience though. It includes a more advanced WAMP router than

Autobahn, one that supports authorisation and authentication, so the components you write can communicate

securely but without the need to write security code.

It includes a Web Server for static pages. We use this with our simple access control example to deliver the HTML, CSS

and javascript files across to the browser for formatting and displaying the name and photo of the person walking

through the security door. This feature alone is fantastic, it means we don’t have to install and run yet another application

(web server).

And, much more that I don't understand yet...

WAMP, Autobahn, Crossbar.io, etc are all open-source, BTW. I can't find enough superlatives for that !

Tim

[Alexander Gödde]

Hi Tim!

Thanks for your feedback. WAMP / Autobahn / Crossbar can certainly be a lot to take in - and we're working on making things easier. External perspective is something we urgently need here - and that's what you're providing. There are some points we'll keep in mind when working on the documentation.

Specifically:

I'm working on a tutorial for a very simple application which shows all the basics necessary, but no more than that.

If I understand you right, then it would have been useful to you when starting out if such a tutorial

* first gave an overview of the basic concepts that underlie the application (e.g. all app components connect to a WAMP router, WAMP does RPC + PubSub, with some small diagrams for the patterns)

* then explained the code bit by bit

* hinted at advanced points, but made it clear what the minimum scope for getting an application to run is, and that this is fully covered in the tutorial

Is this the type of information you think would be useful to have?

Regarding having the demos use Autobahn instead of Crossbar: 

I used to share you point of view here. 

But then, installing Crossbar has gotten easier (even on Windows we're down to a single manual dependency install beyond Python and pip), and if all you care about is getting the demos to run, then `crossbar start` isn't more complex than running a demo server script. There is more complexity under the hood, but the user doesn't need to come in contact with this immediately.

Plus Crossbar can do things that make working with demos easy, e.g. create the demo files + a configuration to run it via a single shell command. 

In the end, Crossbar is the core of what we're doing and where we want to go, and we want to lead people towards using it. 

Still, whenever revising the documentation, we'll keep in mind that people shouldn't be pushed in at the deep end - especially with Crossbar! 

Regards,

Alex

[Roger Erens]

Maybe it could be helpful if there could be some additional templates. I don't find the hello template minimal, as it has three peers (WAMP router, front-end HTML5 client, back-end in <your-favorite-language>), of which the front-end and back-end clients play each four possible (non-router) roles: Callee, Caller, Publisher, and Subscriber.

I think there's room in the 'Crossbar.io Template Universum' to have next to the

crossbar init

default that creates just a WAMP router, a set of

crossbar init callee:<language>

crossbar init caller:<language>

crossbar init publisher:<language>

crossbar init subscriber:<language>

templates. I think it would help newcomers to focus on one concept at a time. For those who think these baby steps are too tiny, there's the hello:<language> template to get started with.

If you'd like me to create a Pull Request for those templates, /me ('worrelsik') would be happy to get some help on #autobahn to get started on them.

Op vrijdag 5 september 2014 16:40:52 UTC+2 schreef tim.in...@gmail.com:

[Alexander Gödde]

Hello Roger!

 

I see what you mean with making things easier – it’s certainly a bit less to get your head around if there’s a single role implemented per client in a template. And when I first had a look at your suggestion, I immediately thought that this would be great for getting started with mixed language deployments beyond the JS + Python that we mostly cover.

 

The problem I see is that while each of these templates yields a single role, this means that none of them actually produce anything working. You get a Crossbar instance where something subscribes, but never receives an event, publishes but nobody receives, registers but is never called, and, worst of all, calls but only gets an error message.

 

The roles really only make sense in pairs – so maybe

 

pubsub:<language>

rpc:<language>

 

would be a simplification that makes sense. This would reduce the initial cognitive load while still fulfilling the central requirement that templates should produce working applications (however reduced in functionality they may be). It would not, however, do anything immediately for getting started with polyglot projects. For that we’d need something different from the present templating system which basically just copies file content. Something to think about, but I guess presently out of scope.

 

The other concern is not present, but future: How many templates should there be? When does the present simple list that Crossbar outputs in the shell when you do `crossbar templates` become unmanageable?

 

There’s need for discussion on this before we go ahead with adding what at present would be ten more templates.

 

Let me know what you think.

 

If we go ahead, then I’ll gladly get back to your offer of creating the templates (and thank you for offering in the first place!)

 

Regards,

 

Alex

--
You received this message because you are subscribed to the Google Groups "Autobahn" group.
To unsubscribe from this group and stop receiving emails from it, send an email to autobahnws+...@googlegroups.com.
To post to this group, send email to autob...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/autobahnws/e3b91139-7c96-4434-aae3-b7dbf58ee86c%40googlegroups.com.

[Roger Erens]

Hi Alexander,

I had not thought of requiring the usage of the templates to create a working constellation; I was thinking in (Lego) building blocks: to obtain something working, you'd need to invoke 'crossbar init <client:language>' three times in a row. This could be explained in the documents.

For the option of the paired-clients templates, I'd like to suggest to have each member of the pair performing just one role, either Caller or Callee, and either Publisher or Subscriber.

To keep the number of choices not overwhelming, maybe the templating process should become interactive?

In the first step, let the user choose which building block or which pair,

and in the second step, let the user choose the language.

Maybe a next choice could be whether or not to include a router (providing a sane default, whatever that may be, so beginners won't feel lost).

A final choice might be to have a basic example, or one with bells and whistles like hello or votes.

Of course it should be possible to indicate the interactive choices with some arguments, e.g.

crossbar init --template pubsub:python [--including-router [--hello-demo]]

and

crossbar templates

would list on just 1 line

pubsub:<language> where <language> can be one of 'python', 'js', 'cpp', 'erlang', 'browser'?

and lines with

pusher

default

demos

After which people could start to combine.

Maybe that could provide both for students like me (starting with small blocks building something larger) and other students who like to have everything but the kitchen sink and start cutting out the stuff they don't need.

Roger

Op maandag 15 september 2014 12:00:00 UTC+2 schreef Alexander Gödde:

[Alexander Gödde]

Hi Roger!

 

The idea behind the templates really is to give you a working application to hack on. You do the `init`, start crossbar, do a test run and then start modifying things to your needs. Having this as just example code somewhere opens up the possibility of making mistakes in getting things to run – even a relatively simple process can have hidden depths when you don’t yet have an understanding for the full picture.

 

The templates are not meant to provide sample code snippets per se. You could use them for that, as you suggest, but then you’d have a lot of overhead (repeat use of the command line, snippets in different directories). Code samples are better kept somewhere with easy access to all of them. This is currently the Autobahn|Python repository (https://github.com/tavendo/AutobahnPython/tree/master/examples/twisted/wamp), which is, admittedly, a bit hidden. They’re linked from the respective language documentations (e.g. for JS: http://autobahn.ws/js/examples_overview.html).

 

We have giving more context to the examples within the repository on our to-do list, i.e. add a brief readme to each with a very brief explanation of what this does and probably links to resources which are relevant (e.g. a section in the API documentation).

 

Once you’ve cloned the repository, you can just browse the code snippets in your editor of choice, and directly copy & paste them.

Anyway, that’s the workflow as we’ve intended it.

 

Could you maybe give me some input how, in your opinion, we might better communicate this?

 

I feel that at this point investing the time in making things clearer in the documentation makes more sense than putting effort in changing the templating process.

To view this discussion on the web visit https://groups.google.com/d/msgid/autobahnws/e13a3225-5f34-452f-85c1-c318f30e33d1%40googlegroups.com.

[Tobias Oberstein]

Hi Roger,

> I had not thought of requiring the usage of the templates to create a
> working constellation; I was thinking in (Lego) building blocks: to
> obtain something working, you'd need to invoke 'crossbar init
> <client:language>' three times in a row. This could be explained in the
> documents.

The application templates should generate complete, left-contained,
working applications.

As I understand the idea you suggest, that would go more into the
direction of either

- an interactive wizard, that is asking questions ("add publish snippet"
Y/N; "add C++ client" Y/N)

https://github.com/crossbario/crossbar/issues/131

or a simple collection of code snippets to look up. Added an issue for
that as well:

https://github.com/crossbario/crossbar/issues/130

Should you have ideas / suggestsions regarding above, pls do so on the
issues, as this will steer the discussion more quickly to actual
implementation ..

===

I agree with Alex that it doesn't make sense to split up the application
templates into 4 distinct one's (for the 4 interactions), since none of
those will be working as is.

We might have 2 templates (PubSub and RPC) instead of 1 (PubSub + RPC),
but honestly I don't feel that would signifiantly lower the entry bar.
The existing code is already next to trivial from a mere code point of view.

Probably is more about explaining the concepts itself that we could
improve .. do you have ideas how we could do that?

Cheers,
/Tobias

> *Von:*autob...@googlegroups.com <javascript:>
> [mailto:autob...@googlegroups.com <javascript:>] *Im Auftrag von
> *Roger Erens
> *Gesendet:* Sonntag, 14. September 2014 23:22
> *An:* cross...@googlegroups.com <javascript:>
> *Cc:* autob...@googlegroups.com <javascript:>
> *Betreff:* Re: Configuation files

> <http://crossbar.io> variant which allows the advanced features of

> send an email to autobahnws+...@googlegroups.com <javascript:>.

> To post to this group, send email to autob...@googlegroups.com

> <javascript:>.

> To view this discussion on the web visit
> https://groups.google.com/d/msgid/autobahnws/e3b91139-7c96-4434-aae3-b7dbf58ee86c%40googlegroups.com

> <https://groups.google.com/d/msgid/autobahnws/e3b91139-7c96-4434-aae3-b7dbf58ee86c%40googlegroups.com?utm_medium=email&utm_source=footer>.

> For more options, visit https://groups.google.com/d/optout

> <https://groups.google.com/d/optout>.

>
> --
> You received this message because you are subscribed to the Google
> Groups "Autobahn" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to autobahnws+...@googlegroups.com

> <mailto:autobahnws+...@googlegroups.com>.

> To post to this group, send email to autob...@googlegroups.com

> <mailto:autob...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/autobahnws/e13a3225-5f34-452f-85c1-c318f30e33d1%40googlegroups.com
> <https://groups.google.com/d/msgid/autobahnws/e13a3225-5f34-452f-85c1-c318f30e33d1%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Roger Erens]

Hi Alexander,

I'm really fine with your reasoning to provide a working example with the templating system.

Until yesterday evening, I was trying to find out how to get an application component that can be run apart from a router; all templates include a router, right? So only after reading further down the page

http://crossbar.io/docs/Python-Application-Components/

I found some (unfortunately outdated) example of a separate router and component. These examples could use some pictures from the architecture document :-)

I had been wondering whether I should try to dissect a Crossbar demo-app or the hello app, or work my way through the Autobahn[JS site.... Probably much the same feeling lost as what Tim also described earlier in this thread.

At the end of the 'Getting started with <language>' page, I'd have welcomed a 'What now?' section like in the 'Quick Start' page pointing to the Python Application Components page. And that page could then suggest to study the crossbar demo-template and/or the AutobahnPython WAMP examples, possibly in conjunction with the Configuration documentation pages.

Sort of laying out a trail of documents for people to work through, in stead dumping a whole mountain of docs in front of them.

Maybe you can also pin a permanent thread on top of the Google Groups with some questions soliciting for suggestions to improve the documentation/learning experience (see kivy-users group).

On Tue, Sep 16, 2014 at 11:44 AM, Alexander Gödde <alexande...@googlemail.com> wrote:

Hi Roger!

 

The idea behind the templates really is to give you a working application to hack on. You do the `init`, start crossbar, do a test run and then start modifying things to your needs.

... 

[Roger Erens]

Hi Tobias,

I agree, the code looks very simple; you've convinced me that the templates better create a working app.

Maybe it's the output of the clients in the browser-consoles that was at first overwhelming and making it difficult to grasp the pubsub and RPC ideas. I think that's where my preference stems from to see 1 client performing only 1 role.

Also, I was looking for a template that would create an Application Component without a router (one of the scenarios you advocate), but if that would be explained more explicitly in the docs, that would be fine with me, too, of course. No need to pollute the templates list just for my sake...

Cheers,

Roger

an email to autobahnws+unsubscribe@googlegroups.com
<mailto:autobahnws+unsub...@googlegroups.com>.

To post to this group, send email to autob...@googlegroups.com

<mailto:autobahnws@googlegroups.com>.

To view this discussion on the web visit
https://groups.google.com/d/msgid/autobahnws/e13a3225-5f34-452f-85c1-c318f30e33d1%40googlegroups.com
<https://groups.google.com/d/msgid/autobahnws/e13a3225-5f34-452f-85c1-c318f30e33d1%40googlegroups.com?utm_medium=email&utm_source=footer>.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "Autobahn" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/autobahnws/adVxOcyKx-E/unsubscribe.
To unsubscribe from this group and all its topics, send an email to autobahnws+unsubscribe@googlegroups.com.
To post to this group, send email to autob...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/autobahnws/54181018.5080201%40gmail.com.

[Tobias Oberstein]

Am 16.09.2014 13:39, schrieb Roger Erens:
> Hi Alexander,
>
> I'm really fine with your reasoning to provide a working example with
> the templating system.
>
> Until yesterday evening, I was trying to find out how to get an
> application component that can be run apart from a router; all templates
> include a router, right? So only after reading further down the page

A router is always required for running a WAMP based application.

The hello:python example (and all others) will therefor start 1 worker
process with a router, and a 2nd worker process running the example
component.

> http://crossbar.io/docs/Python-Application-Components/
> I found some (unfortunately outdated) example of a separate router and
> component. These examples could use some pictures from the architecture
> document :-)

I have updated above Wiki page. The app template _does_ start separate
worker processes for a router and a container with the example Python
application component.

>
> I had been wondering whether I should try to dissect a Crossbar demo-app
> or the hello app, or work my way through the Autobahn[JS site....
> Probably much the same feeling lost as what Tim also described earlier
> in this thread.
>
> At the end of the 'Getting started with <language>' page, I'd have
> welcomed a 'What now?' section like in the 'Quick Start' page pointing
> to the Python Application Components page. And that page could then
> suggest to study the crossbar demo-template and/or the AutobahnPython
> WAMP examples, possibly in conjunction with the Configuration
> documentation pages.
> Sort of laying out a trail of documents for people to work through, in
> stead dumping a whole mountain of docs in front of them.
>
> Maybe you can also pin a permanent thread on top of the Google Groups
> with some questions soliciting for suggestions to improve the
> documentation/learning experience (see kivy-users group).

Good idea! We'll do that.

>
> On Tue, Sep 16, 2014 at 11:44 AM, Alexander Gödde
> <alexande...@googlemail.com

> <mailto:alexande...@googlemail.com>> wrote:
>
> Hi Roger!____
>
> __ __

>
> The idea behind the templates really is to give you a working
> application to hack on. You do the `init`, start crossbar, do a test
> run and then start modifying things to your needs.
>
> ...
>

> --
> You received this message because you are subscribed to the Google
> Groups "Autobahn" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to autobahnws+...@googlegroups.com

> <mailto:autobahnws+...@googlegroups.com>.

> To post to this group, send email to autob...@googlegroups.com

> <mailto:autob...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/autobahnws/CAMTMGpqJTwwNdB3%2Bzv9XZs8QAMnw63qXjBp%2BNHMn%3DMEu_disWw%40mail.gmail.com
> <https://groups.google.com/d/msgid/autobahnws/CAMTMGpqJTwwNdB3%2Bzv9XZs8QAMnw63qXjBp%2BNHMn%3DMEu_disWw%40mail.gmail.com?utm_medium=email&utm_source=footer>.

[Roger Erens]

On Wed, Sep 17, 2014 at 10:40 AM, Tobias Oberstein <tobias.o...@gmail.com> wrote:

Am 16.09.2014 13:39, schrieb Roger Erens:

Hi Alexander,

I'm really fine with your reasoning to provide a working example with
the templating system.

Until yesterday evening, I was trying to find out how to get an
application component that can be run apart from a router; all templates
include a router, right? So only after reading further down the page

A router is always required for running a WAMP based application.

Sorry, I wasn't precise: I did not mean running an Application Component without a router, but running apart from a router that is already running in another crossbar node.

 

The hello:python example (and all others) will therefor start 1 worker process with a router, and a 2nd worker process running the example component.

http://crossbar.io/docs/Python-Application-Components/
I found some (unfortunately outdated) example of a separate router and
component. These examples could use some pictures from the architecture
document :-)

I have updated above Wiki page. The app template _does_ start separate worker processes for a router and a container with the example Python application component.

OK, I'll wait for the changes to propagate on the wiki and make use of them.

Currently, you have listed 3 use cases on it:

1) Router with Application Session

2) Router and Application Process

3) Router and Application Nodes

I did not check 1) and 2); I wanted to get started with 3).

So I created a router-only directory and filled it with 'crossbar init'.

I created a sibling component-only directory and filled it 'crossbar init --template hello:python'.

Then replacing hello.py by the timeservice.py you mention in the top of that page, and got the frontend.js and frontend.html from the

https://github.com/tavendo/AutobahnPython/tree/master/examples/twisted/wamp/basic/rpc/timeservice github pages.

In this component-only directory I also removed the router-entry from .crossbar/config.json and fiddled to the best of my ability with the remainder to make timeservice.py used i.s.o. hello.py.

In the router-only directory .crossbar/config.json was changed to make the '/' path direct to the sibling directory's html file.

Starting the router-only node looked OK.

Starting the component-only node did not register the timeservice RPC.

Only after commenting out the __init__ and onConnect functions in timeservice.py (since hello.py does not have these either), the RPC function got registered.

Now browsing to localhost:8080 got me the I am being called;) message in the console of the component-only host.

Thanks for your software!

Next step for me will be using multiple component nodes next to a router, .e.g timeservice-Amsterdam.py and timeservice-Athens.py.

[Tobias Oberstein]

3) yes, you already got it: you can run Crossbar nodes which only run components .. which then connect to a router external to the former Crossbar node

Sent from Mobile (Google Nexus 5)

--
You received this message because you are subscribed to the Google Groups "Autobahn" group.

To unsubscribe from this group and stop receiving emails from it, send an email to autobahnws+...@googlegroups.com.
To post to this group, send email to autob...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/autobahnws/CAMTMGpom_Yfj4hrdLcH771S4X_tZwbcAH4R47%3D0VNnGYaNNDMA%40mail.gmail.com.