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 one of my colleague.
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.
-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:
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:
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: firstname.lastname@example.org, 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
-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:
- First define user, password and database
- Use these credentials on the "### Outline Database part"
- Generate 2 different chain of at least 20 characters for the "SECRET_KEY" and "UTILS_SECRET" and paste them
- Paste your SMTP (optional, but mandatory for extracts)
- Add your main Outline URL
- Use your previously generated Slack credentials
- 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_USERNAMEemail@example.com - SMTP_PASSWORD=MyAmazingPassword123 - SMTP_FROM_EMAILfirstname.lastname@example.org - SMTP_REPLY_EMAILemail@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!