How to deploy your own internal Wiki with Outline in self-hosted version?

Since Atlassian has announced the end of sales for Confluence Server version (which is a self-hosted version of Confluence), I was looking for a similar software. Then, thanks to my colleague Vincent, I've found Outline.

As soon as you're starting working on professional projects, even in IT, you will have to create documentations about specific parts of your project. There isn't any basic and modern software, except Outline.

Outline is inspired from Notion.so, which is pretty similar. The main difference here is that, Outline can be self-hosted (even if they're offering an SaaS product).
As you can see on the screenshot, Outline is simple, minimalist, and makes you want to use it!

However, as a complete team of developers is working on it, the self-hosted version is so complex to deploy, and I think that's done on purpose to push forward people to buy the SaaS version. I haven't found any other documentation which explained that, except one outdated script.

Prerequisite:
-have a compute cloud instance (VPS, dedicated, instance, etc) and root permissions
-have an active Scaleway account or any S3 provider
-have a created bucket on any supported provider
-have a subdomain or complete domain available

Step 1: Login and prepare your environment

First, let's update and upgrade packages installed on your instance.

apt-get update -y && apt-get upgrade -y

After, let's install Docker and Docker Compose.

apt-get install docker.io -y 
apt-get install docker-compose -y
# On Ubuntu 20.04

If you're using another OS, have a look at official Docker and Docker compose documentations available here.

Now, let's add an A record pointing to our instance. Once it's done, verify it, as below:

If your A record returns a valid IPv4 instance, you're ready!

Step 2: Install and configure Nginx Proxy Manager

Now, we will have to install and configure a reverse proxy. Here I will use Nginx Proxy Manager which is the easiest way to install and configure a reverse proxy, with a WebUI etc. But keep in mind that you can use any reverse proxy software, like Traefik for example.

Let's create a dedicated directory.

mkdir npm
cd npm

And we will create the docker-compose file:

nano docker-compose.yml

Then, paste the following content:

version: '3'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    environment:
      DB_MYSQL_HOST: "db"
      DB_MYSQL_PORT: 3306
      DB_MYSQL_USER: "npm"
      DB_MYSQL_PASSWORD: "npm"
      DB_MYSQL_NAME: "npm"
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
  db:
    image: 'jc21/mariadb-aria:latest'
    environment:
      MYSQL_ROOT_PASSWORD: 'npm'
      MYSQL_DATABASE: 'npm'
      MYSQL_USER: 'npm'
      MYSQL_PASSWORD: 'npm'
    volumes:
      - ./data/mysql:/var/lib/mysql

Then, let's go and deploy it:

docker-compose up -d

To be sure, verify that containers are correctly deployed with:

docker ps

Then, you will have the following output:

You can try to access to your Nginx Proxy Manager via:
http://YourIPv4:81 or http://YourARecord.tld:81

And you will find this WebUI:

Now, login with: admin@example.com, and with the password: changeme.
Once logged, click on "Proxy" then "Proxy Host", and click on "Add Proxy Host".

Fill in the different fields, as below:
-Domain Names: your A record
-Scheme: http
-Forward Hostname/IP: outline_outline_1
-Forward Port: 3000

You will understand later why we're using these settings.

Now, we will add an SSL certificate powered by Let's Encypt and force SSL traffic.
On the "SSL certificate" dropdown select "Request a new SSL certificate", and tick both "Force SSL" & "I Agree to the Let's Encrypt ToS".

At this point, we've correctly deployed our reverse proxy, and our infrastructure is ready to be configured with a basic outline setup.

Step 3: Prepare the Outline specific environment

First, you will have to deploy an S3 (Object Storage) bucket. You can do that, with any S3 compliant provider: AWS, Digital Ocean, Scaleway, Alibaba Cloud, and many other ones.

In this case, I will create a bucket on Scaleway Elements, called "outline-tuto".
If you need further help with bucket creation, have a look at the official Scaleway Elements documentation page available here.

Now, we have to get Slack settings, as Outline needs Slack third party auth.

Let's go to: https://api.slack.com/apps
Once it's done, you will be able to follow a basic app creation flow.
Then, go back to the app page, and click on the selected app.

Then scroll down to "App Credentials" and you will see this:

Then, write down, and copy/paste following credentials:
App ID, Client ID, and client Secret.

Step 4: Configure our docker-compose file

Now, let's create a specific directory for our Outline files.

mkdir outline
cd outline

Now, edit our docker-compose file:

nano docker-compose.yml
  1. First define user, password and database
  2. Use these credentials on the "### Outline Database part"
  3. Generate 2 different chain of at least 20 characters for the "SECRET_KEY" and "UTILS_SECRET" and paste them
  4. Paste your SMTP (optional, but mandatory for extracts)
  5. Add your main Outline URL
  6. Use your previously generated Slack credentials
  7. Use your previously generated S3 bucket credentials

You may get a docker-compose.yml file like this one:

version: "3"
services:
  redis:
    image: redis
    restart: always
  postgres:
    image: postgres
    environment:
      POSTGRES_USER: outline
      POSTGRES_PASSWORD: MyAmazingPassword123
      POSTGRES_DB: outline
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: always
  outline:
    image: outlinewiki/outline:latest
    command: sh -c "yarn sequelize:migrate --env production-ssl-disabled && yarn start"
    environment:
      ########## Outline Database
      - DATABASE_URL=postgres://outline:MyAmazingPassword123@postgres:5432/outline
      - DATABASE_URL_TEST=postgres://outline:MyAmazingPassword123@postgres:5432/outline-test
      - REDIS_URL=redis://redis:6379
      - SECRET_KEY=23e5c418cd23eeed318f5a1f977d86d0c05fee5e89ad6ff889b2063661cf143f
      - UTILS_SECRET=7f25f96d414ebbfe4ba95859973028df84faaa3ead297a45ee4d0b1c4c88fafa
      ########## Outline mail settings
      - SMTP_HOST=smtpserver.example.com
      - SMTP_PORT=25
      - SMTP_USERNAME=outline@example.com
      - SMTP_PASSWORD=MyAmazingPassword123
      - SMTP_FROM_EMAIL=outline@example.com
      - SMTP_REPLY_EMAIL=outline@example.com
      ########## Outline Default URL
      - URL=https://yourarecord.tld
      ########## Outline Slack settings
      - SLACK_APP_ID=SLACKAPPIDGoesHere  
      - SLACK_KEY=SlackKeyGoesHere
      - SLACK_SECRET=SlackSecret goes here
      ########## Outline S3 Provider credentials
      - AWS_ACCESS_KEY_ID=ScwAccessKeyGoesHere
      - AWS_SECRET_ACCESS_KEY=ScwSecretAccessKeyGoesHere
      - AWS_REGION=fr-par
      - AWS_S3_UPLOAD_BUCKET_URL=https://s3.fr-par.scw.cloud
      - AWS_S3_UPLOAD_BUCKET_NAME=your-bucket-name
      - AWS_S3_UPLOAD_MAX_SIZE=26214400
      - AWS_S3_FORCE_PATH_STYLE=true
      - AWS_S3_ACL=private
      - PGSSLMODE=disable
    restart: always
    depends_on:
      - postgres
      - redis
    networks:
      default:
volumes:
  pgdata:

Then, save the docker-compose file. Now, you can perform:

docker-compose up -d

Then, you will be able to access to your Outline installation as expected.

You will be asked to log in with your Slack account, and you will be able to enjoy your fresh new Outline installation.

Congratulations, you've successfully deployed your own internal Wiki with Outline in self-hosted version!


Permalink: https://tomjorge.me/how-to-deploy-your-own-internal-wiki-with-outline-in-self-hosted-version/