Documentation fail



  • I spent the last 3 days trying to set up a bloated over-engineered rails app on my new FreeBSD server. No, it's Gitlab, not Discourse.

    One last step remained: configuring GitLab to send notification emails using my external email provider.

    Of course, it'd be too much to ask for something sane such as a "send test email" command or GUI screen. Instead, I've been manipulating my dummy user accounts. I would trigger an email, then browse through these gigantic sideqik logs, searching for the tiny one-word error message. This is, by the way, all I'd ever get, because something like SMTP convo logs are forever lost inside the bowels of this beast of an application.

    Anyway, gitlab basically pointed me to the official rails documentation for their ActionMailer class. Here it is, in all its glory:

    Hmm, should I use :plain or :login style authentication? It seems someone went a bit crazy with copy/paste there.

    But whichever I picked, it didn't matter. I kept getting "connection refused" type cryptic messages.

    Until I finally found the correct setting:

      ActionMailer::Base.smtp_settings = {
        #...
        authentication: :login,
        tls: true
      }
    

    I found this in a random comment to a random github issue. There's ZERO mention of the tls switch in the official rails documentation.

    Also note that this is about the most common type of configuration for non-business users. If you want to use your gmail address to send notifications, you'll need this magic switch. Better hope that random issue sticks around for a long time.

    Well done, Rails documentation. Well done.


  • Discourse touched me in a no-no place

    @cartman82 said:

    Well done, Rails documentation. Well done.

    Did you email them to see if pull requests are accepted?

    I keep wanting to learn Ruby, but every time I think about it I hear stories like this.



  • @FrostCat said:

    Did you email them to see if pull requests are accepted?

    I could have done that, or I could have came here and posted this rant.

    Which do you think will be more fondly remembered by future generations?



  • Rails isn't Ruby in all fairness to Ruby


  • :belt_onion:

    I recently installed the the community version on Ubuntu. All I had to setup was in a single configuration file, and it took 30 minutes (mostly googling). I used GMail for the notifications.



  • @cartman82 said:

    I have a suggestion for what to do with md5.



  • @dse said:

    I recently installed the the community version on Ubuntu. All I had to setup was in a single configuration file, and it took 30 minutes (mostly googling). I used GMail for the notifications.

    Since they don't have an official support for FreeBDS, I had to install it from git sources, using half-complete docs and outdated blog posts. The biggest hurdle turned out to be when I compiled an older version of one of their 1000 services, which then swallowed errors in a silent obtuse way.


  • :belt_onion:

    @cartman82 said:

    FreeBDS

    @cartman82 said:

    The biggest hurdle turned out to be when I compiled an older version of one of their 1000 services, which then swallowed errors in a silent obtuse way.

    Worse than no documentation is obsolete ones, sorry FreeBDSM hipster.



  • One day the world will see the truth and cast off the shackles of linux tyranny.



  • Umm...I hate to disillusion anyone, but base64 encoding of the password is specified by RFC 2554.

    Naturally, it is still used; I couldn't even easily find a place that says it is deprecated.

    Sometimes it's not good to look too closely at the underpinnings of the internet...



  • @CoyneTheDup said:

    Umm...I hate to disillusion anyone, but base64 encoding of the password is specified by RFC 2554.

    Naturally, it is still used; I couldn't even easily find a place that says it is deprecated.

    Sometimes it's not good to look too closely at the underpinnings of the internet...

    Haven't even thought about that. What's the fucking point?


  • :belt_onion:

    @cartman82 said:

    Haven't even thought about that. What's the fucking point?

    To support authentication mechanisms with payloads that don't fit within the syntax restrictions of SMTP.

    Now the "login" mechanism is pretty WTF, but it was first.


  • Winner of the 2016 Presidential Election

    Gitlab is a serious WTF to set up and use. I'm not even remotely surprised at all that you're having issues...


  • Winner of the 2016 Presidential Election

    Trust me, the support for obscure distributions like Ubuntu is only marginally better...


  • Discourse touched me in a no-no place

    @sloosecannon said:

    Gitlab is a serious WTF to set up and use.

    We use it. I don't know what it's like to set up (though I can believe this thread completely) but to use it is sometimes annoying because it hides features behind icons and you've got to hover over them and guess from the tooltip as to what they do. Unless you have a wide enough screen. Showing the content in the centre is prioritised very strongly over showing things you might use to work with the current project. Still, it works not too bad as a we-can-do-github-too pseudo-clone.

    The API is… well, very obviously just the “whatever we'd show you in the UI, but in JSON” that you expect from a Rails app. Sometimes that's nice, and sometimes that's horrible. There are some boneheaded bits in the issue handling and in the branch tracking; there might be elsewhere too, but I've not drilled in depth into all that.


  • Winner of the 2016 Presidential Election

    IMO Gogs is much better, even though it's kinda incomplete and definitely still in a beta version. It was much simpler to set up and works quite well. My only concern (apart from it being beta, of course) is that I have no idea how well it scales.

    CC @Ben_Lubar because it's written in Go



  • @sloosecannon said:

    I have no idea how well it scales.

    Does it matter how well a server that's used by 1 person scales?



  • @cartman82 said:

    note that this is about the most common type of configuration

    If you send an email without using TLS to a gmail.com address, the recipient gets a warning icon on the email.


  • Winner of the 2016 Presidential Election

    Well no, but the use case for a github clone is likely to include "Usable by more than one person".

    FWIW, unless there's something really bad about how Go scales, I suspect it will scale much better than GitLab, given their performance on the same hardware. GitLab took a good 5+ seconds on pretty much every page, Gogs takes less than a second


  • Discourse touched me in a no-no place

    @sloosecannon said:

    the use case for a github clone is likely to include "Usable by more than one person".

    For sure. We're using it for our undergraduate teaching. That's about as production as a university gets.

    @sloosecannon said:

    GitLab took a good 5+ seconds on pretty much every page

    Sounds like a problem (which could include mere under-resourcing; Ruby-on-Rails is fearsomely resource hungry). We're not seeing things anywhere close to that slow in our production deployment.



  • @sloosecannon said:

    unless there's something really bad about how Go scales

    Unless you do something stupid like spawning a goroutine for each pixel of a map of Earth, it should scale pretty well for you.


  • Grade A Premium Asshole

    @dse said:

    Worse than no documentation is obsolete ones, sorry FreeBDSM hipster.

    I've been trying to explain this extremely simple concept to higher-ups at my company for years now. They're convinced that it's better to publish something than nothing at all, likely because publishing that something covers their own asses in case their own higher-ups would and ask why a certain guide isn't published. "Oh, I'm sorry Mr. Boss Man, I thought the published thing was up to date. I'll go annoy the already overworked tech writer who told me a thousand times that the guide is not in a publishable state." Fuck.

    And then they wonder why our customers, instead of opening our customer portal and looking through official documentation, just use google and find solutions to their problems in random forum threads and blogs and call our support when that fails. It blows my mind.



  • @dkf said:

    mere under-resourcing

    I remember having a local testing install of Discourse and having to restart it every so often because it would grow to use up the entire system's physical memory and swap while idle. So if you can manage to give Ruby on Rails infinite memory and CPU time, it might work.


  • Winner of the 2016 Presidential Election

    @dkf said:

    which could include mere under-resourcing

    Oh I'm sure it's that. The server I was running it on was not exactly what you'd call over-provisioned.

    Still though, Gogs runs really nicely on the same hardware...



  • 22 replies already and not a single blakeyrant about Git?


  • Discourse touched me in a no-no place

    @ben_lubar said:

    Discourse

    @ben_lubar said:

    infinite memory and CPU time, it might work

    I remain doubtful…


  • Winner of the 2016 Presidential Election

    He hasn't gotten as far as using the application yet! :laughing:


  • Winner of the 2016 Presidential Election

    @FrostCat said:

    I keep wanting to learn Ruby

    onyx@dev1:~$ irb
    irb(main):001:0> "Hello"*3
    => "HelloHelloHello"
    irb(main):002:0> nope!
    NoMethodError: undefined method `nope!' for main:Object
            from (irb):2
            from /usr/bin/irb:11:in `<main>'
    irb(main):002:0> ^C
    irb(main):002:0> ^C
    irb(main):002:0> ^C
    irb(main):002:0> ^C
    irb(main):002:0> ^C
    irb(main):002:0> ^C
    irb(main):002:0> ^C
    irb(main):002:0> ^C
    irb(main):003:0> exit
    

    Yeah... let me know if you get further...

    :tropical_drink:



  • @cartman82 said:

    ActionMailer class

    That thing craps all over the discologs.



  • Base64 is fine, but it shouldn't be confused with encryption. Even md5 shouldn't be used for encryption unless you're using it for your "mom & pops" cookery blog website.


Log in to reply
 

Looks like your connection to What the Daily WTF? was lost, please wait while we try to reconnect.