Hosting Outline, a notion competitor in 15 minutes (on clever cloud)

Outline is a simple, fast and sweet Wiki software, I recommend, this is an open source projet, the community is reactive and even the SaaS platform pricing is really honest !

But if you do need to host your own version of outline or you have to save money, here is a small tutorial for you. This is done with clever cloud but I'm pretty sure it'll almost works as is for Digital Ocean or any other cool cloud provider.

Start by creating a clever cloud application and its redis, postgres and cellar addons :

In your clevercloud project page, configure first the domain name, for example wiki.your-fire-name.com. add the following environnment variables and replace every 🔥 (emoji) with relevant values :

AWS_ACCESS_KEY_ID="equal to the CELLAR_ADDON_KEY_ID"
AWS_REGION="us-east-1"
AWS_S3_ACCELERATE_URL="https://wiki-assets.cellar-c2.services.clever-cloud.com"

I make a stop here to explane why I've needed to use AWS_S3_ACCELERATE_URL; it's (for now) a necessary workaround to be able to read properly in the s3. Please @see https://github.com/outline/outline/issues/5352#issuecomment-1562192005 first and try without this hack before, it could be solved when you'll try

AWS_S3_FORCE_PATH_STYLE="false"
AWS_S3_UPLOAD_BUCKET_NAME="wiki-assets"
AWS_S3_UPLOAD_BUCKET_URL="https://wiki-assets.cellar-c2.services.clever-cloud.com"
AWS_S3_UPLOAD_MAX_SIZE="26214400"
AWS_SECRET_ACCESS_KEY="equal to the CELLAR_ADDON_KEY_SECRET"
CC_DOCKER_EXPOSED_HTTP_PORT="3000"
DATABASE_URL="postgresql://🔥:🔥@🔥-postgresql.services.clever-cloud.com:6849/🔥"
DEFAULT_LANGUAGE="fr_FR"
ENABLE_UPDATES="true"
FORCE_HTTPS="true"
PORT="3000"
RATE_LIMITER_DURATION_WINDOW="60"
RATE_LIMITER_ENABLED="true"
RATE_LIMITER_REQUESTS="1000"
REDIS_URL="redis://:🔥@🔥.clvrcld.net:🔥/13"
SECRET_KEY="🔥"
SMTP_FROM_EMAIL="wiki@🔥.com"
SMTP_HOST="in-v3.mailjet.com or any other"
SMTP_PASSWORD="🔥"
SMTP_PORT="465"
SMTP_REPLY_EMAIL="noreply@🔥.com"
SMTP_SECURE="true"
SMTP_USERNAME="🔥"
URL="https://wiki.🔥.com"
UTILS_SECRET="🔥"

For UTILS_SECRET and SECRET_KEY, generate them with :

openssl rand -hex 32

The full list of environment variables are available here :
https://github.com/outline/outline/blob/main/.env.sample

(optional) Login with Slack

If you use slack, it can be usefull to log in outline with. Create a slack app https://api.slack.com/apps with Oauth (OAuth & Permissions).

When you get informations, copy/paste in clever cloud environment variables (replace fire with relevant value):

SLACK_APP_ID="🔥"
SLACK_CLIENT_ID="🔥.🔥"
SLACK_CLIENT_SECRET="🔥"
SLACK_VERIFICATION_TOKEN="🔥"

Then create a project on gitlab for example with the following files :

• Dockerfile :

FROM outlinewiki/outline:0.71.0

• clevercloud/post_build.sh

#!/bin/sh

yarn sequelize db:migrate

• .gitlab-ci.yml :

image: docker/compose:latest

stages:
  - deploy

deploy:
  stage: deploy
  image:
    name: clevercloud/clever-tools:latest
    entrypoint: ['/bin/sh', '-c']
  script:
    - clever login --secret $CLEVER_SECRET --token $CLEVER_TOKEN
    - clever deploy -a $CI_ENVIRONMENT_NAME --force
  environment:
    name: prod
    url: https://wiki.🔥.com
  only:
    - main

• policy.json:

{
  "Id": "Policy1587216857769",
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Stmt1587216727444",
      "Action": [
        "s3:GetObject"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:s3:::wiki-assets/*",
      "Principal": "*"
    }
  ]
}

• cors.xml:

<CORSConfiguration>
    <CORSRule>
        <AllowedOrigin>https://wiki.🔥.com</AllowedOrigin>
        <AllowedMethod>PUT</AllowedMethod>
        <AllowedMethod>POST</AllowedMethod>
        <AllowedMethod>DELETE</AllowedMethod>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <MaxAgeSeconds>3600</MaxAgeSeconds>
    </CORSRule>
</CORSConfiguration>

• Download prefilled config file .s3config in cellar addon information page (on clevercloud) and add it too to the project :

• Add a Makefile to be able to simplify cors and policy management :

DOCKER = docker
RUN_S3CMD = $(DOCKER) run --rm -v $(PWD):/app d3fk/s3cmd --config /app/.s3cfg

S3_BUCKET_NAME=wiki-assets
s3_help:
    @$(RUN_S3CMD) --help
S3_CORS_FILE=cors.xml
s3_infocors:
    @$(RUN_S3CMD) info s3://$(S3_BUCKET_NAME)
s3_setcors:
    @$(RUN_S3CMD) setcors /app/$(S3_CORS_FILE) s3://$(S3_BUCKET_NAME)
S3_POLICY_FILE=policy.json
s3_setpolicy:
    @$(RUN_S3CMD) setpolicy /app/$(S3_POLICY_FILE) s3://$(S3_BUCKET_NAME)

• Run the following command to set a valid policy and cors:

make s3_setpolicy s3_setcors

you could need to install make first

Tada ! The code is ready.

Add the $CLEVER_SECRET and $CLEVER_TOKEN variables

On your gitlab repository or group (Settings > Ci/CD / Variables). To generate them, install clever-tools locally, run clever login command and copy/paste your credentials.

Commit + push your code (to the **main** branch as it's expected in .gitlab-ci.yml otherwhise nothing will happen).

Wait some seconds, a deploy job should have been run in Gitlab and you should be able to see something happen in clevercloud side.

Lazy nerd ? Follow logs directly in your terminal, with clever logs command.

You should have now a running Outline :

Enjoy !

What about updating in future ?

I suggest you watch the repository to be notified on next releases :

There is at some things to do :

• update Dockerfile image version with new version (check the version in hub.docker.com before).
• you could have to run some additional migration script sometimes, check in release page and use clevercloud/post_build.sh file.

Do it as soon as possible to avoid too big changes especially because project is still under zero version system, it remains risky !