Journey to get Outline running on Heroku

How do you organize all the random bits of knowledge that you pick up here and there and might need it later?

At first, you might start with just writing it down randomly on your Notes app, but the more you write, the more you'll realize that searching through it all is kinda difficult - after all, you're writing all this down to read later when you need it!

And for that, code snippets exist, but they're rather inflexible, bulky, and often, limited to your local machine - which is probably fine for most use cases, but as I started taking on more projects and needed to record increasingly diverse "bits" of knowledge, I realized I needed this on more than one machine.

That's where wikis come in. And how do you choose between the many open-source wikis out there? For me, as I was using this just for myself, ease of installation and low costs (of running the machine and maintaining it) were the two key factors. And for that, I specifically looked out for wikis that supported deploying to Heroku (free-tier, of course).

Turns out, there aren't many.

And even for Outline (which I ended up choosing), you don't see the "deploy to Heroku" button anywhere on the site, on the GitHub repo, or anywhere on the (nonexistent) documentation.

I literally had to Google "outline wiki deploy heroku", which is probably how you got here, too (keen readers may have already realized the fact that deploying Outline to Heroku probably isn't easy given that there's a whole article about it).

It eventually led to this PR that a kind soul made, which adds support for "deploy to Heroku" as we know it by adding app.json. But as the PR clearly shows, the authors have vested interest in making sure running Outline on your own is as difficult as possible.

So to save you some time, here's some tricks to actually deploying it to Heroku (that I found out after much trial and error, because none of this is ever documented):

1. There's no "Heroku button". The authors literally didn't want you to be able to deploy easily, so you'll have to dig thru to get your button elsewhere.
2. You must use the full https:// when referring to your URL. Using ${appname}.herokuapp.com in any of your installation steps will render it unusable!
3. The app.json is misleading in some places. For example, SLACK_APP_ID and SLACK_VERIFICATION_TOKEN are required environment variable, and yet when you actually go through the Heroku setup process, it seems like you don't need them, not to mention it's literally not mentioned anywhere in the docs!

And once you get it installed, your job is only halfway done, because you're going to need to set up an identity provider. Your options are Google or Slack, but be warned: your average Google account won't work - only accounts that are tied to an organization will suffice.

I only had personal Google accounts, so I had to resort to Slack integration (you can set it up at api.slack.com/apps).

But it only gets worse. If you managed to figure out which Slack environment variables are required through trial-and-error (answer: all of them!), you'll still need to enable "Sign in with Slack".

Beneath the surface, it's your standard OAuth sign-in flow. A few tips:

1. You don't need "OAuth Access Token". I know, it sounds important. It's not.
2. You need to provide a redirect URL. But it's not documented, so you need to extrapolate from the "local install" example in the Outline repo's Readme and figure out that the path you're looking for is /auth/slack.callback.
3. But wait! You need to provide a full URL. And if you just provide ${appname}.herokuapp.com/auth/slack.callback, it seems to work. But when you actually click the "Sign in with Slack" button, it redirects literally endlessly with no apparent error message. So you need to append the https:// to the redirect URL.

So are you done? Actually, no. And unfortunately, this is where our journey ends, because after configuring all this crap correctly by trial-and-error (because there's literally no documentation for any of this), and you click the "Sign in with Slack" button for the final time, crossing your fingers and hoping that it works this time, it'll just spew out a Authentication failed - we were unable to sign you in at this time. Please try again.

No specific errors. No instructions. Just a "hey it doesn't work" message.

And no matter how many times you try again (as the error message tells you to), you'll find that it just doesn't work. It just spits out a cryptic message at you, with no details at all.

Back to Googling our error - and this time, we're led to this issue. And once you read the responses and the linked source code, you'll realize it's a cookie error with nginx, which apparently has a "fix".

(And as a side note, it annoys me to no end that one of the maintainers is like "just go read the server logs lol" when there's literally nothing on the server logs. Seriously. Check your Heroku logs. There's nothing. Nada. Zip.)

They seemed to be very eager to just close the issue as soon as possible without even investigating the underlying (silent) errors, but here's the thing: Heroku provides an nginx-based reverse proxy for you.

That means you can't configure it and "solve" it like they suggest.

You're literally SOL. There's literally nothing you can do.

So, in conclusion:

• Outline docs suck, or they would, if any existed in the first place.
• The authors are hellbent on making your life miserable if you dare to try to host it on your own.
• Deploying to Heroku is "technically" possible, but Slack integration just straight up won't work.
• I'm going thru the list again and picking a different wiki, because screw this. Just pick literally anything else. This is seriously not worth it.

And, all of this brings to question open-source software maintainers' motives when they stand to profit from making their software inaccessible. In general, is there anything users can do aside from "just" forking? How can we encourage authors to incorporate changes that will make their software more accessible, or should we in the first place? Etc.