Attention
The initial guide stopped working as of version v0.72.0 due to PR#5742 which removed the variables from the .env file. I’ve updated this article to include the new way of enabling these features – but kept the old text.
A few days ago I discovered a nice Notion alternative called “Outline“. It seemed to provide a nice feature set while also being self-hosted. The setup was somewhat cumbersome, as it needs an S3 Object storage, auth provider, postgres DB and Redis server. After setting up Keycloak for auth and MinIO for S3 Object storage I was ready to go.
But there was one thing missing I knew from Notion—multiple workspaces and switching between them. The UI looked like it supported context switching, though no “Create New Workspace” can be found. Digging through the web demo I found the function. The hosted version seems to support it while the self-hosted doesn’t weird. After looking through Outline’s Github issues I discovered someone complaining about a semi-working “Create workspace” button.
Configuration options to get Outline working
Most configuration is done using the .env file. One option which caused the semi-working button to show up was DEPLOYMENT=hosted. And I was able to confirm this aforementioned behaviour. Indeed a “Create Workspace”-button showed up. Creating a new Workspace, however, caused weird behaviour where I was trapped in the new Workspace, unable to switch.
Looking through the source code there was another interesting option SUBDOMAINS_ENABLED=true. Huh, I wonder what this does I thought while flicking it on.
Upon visiting the outline subdomain I was greeted with a redirect to a subdomain <workspace>.outline.domain.tld. This felt like the final stretch. I made a new certificate for *.outline subdomains and set up nginx to point them to the application as well.
And boom – I got a “hosted-only” feature working on a self-hosted instance.
Cool – but how to enable these features?
Before version v0.72.0 these features could be enabled by changing variables in the .env file. As of PR#5742 this no longer works and code modification is required.
There are two points in the source code where the system decides whether or not it is running a “cloud-hosted” environment. We need to modify the code, to make it think that we always run in such a hosted env.
Begin by modifying the file “app/utils/isCloudHosted.ts” where you need to replace these lines:
const isCloudHosted = [
"https://app.getoutline.com",
"https://app.outline.dev",
"https://app.outline.dev:3000",
].includes(env.URL);with this single line:
const isCloudHosted = true;Next edit the file “server/env.ts”, where you replace:
public get isCloudHosted() {
return [
"https://app.getoutline.com",
"https://app.outline.dev",
"https://app.outline.dev:3000",
].includes(this.URL);
}with this simple bit:
public get isCloudHosted() {
return true;
}These are all the steps necessary in order to get these hosted features back.
After that you have to run yarn build.
(This is really important and more a note for future me…)
Cool – but how do I do it? – The old (and broken) way
First, add these lines to your configuration:
DEPLOYMENT=hosted
SUBDOMAINS_ENABLED=trueNow make sure you have SSL certificates for the subdomain you want to use. In my case *.outline.domain.tld. You can use certbot with the cloudflare-dns-challenge plugin to request fitting certificates.
Next, you need to configure your nginx webserver to properly handle the new request.
This is the config I’m using. This might not be perfect for your installation but should probably also work.
I hope this helps someone out there and saves them at least a little time!
Recent Comments