Hosting Outline, a notion competitor in 15 minutes (on clever cloud)
Published: 2023-08-24 09:28:17

## [Outline](https://www.getoutline.com/) 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](https://www.getoutline.com/pricing) !

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 :


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nnh9391s36lik4mavte9.gif)

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 :

```ini
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

```ini
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 :
```bash
openssl rand -hex 32
```

> The full list of environment variables are available here :
[https://github.com/outline/outline/blob/main/.env.sample](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).

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mp79kd70k0n5l4nd5c51.jpeg)

When you get informations, copy/paste in clever cloud environment variables (replace fire with relevant value):
```ini
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 :
```Dockerfile
FROM outlinewiki/outline:0.71.0
```

- clevercloud/post_build.sh
```shell
#!/bin/sh

yarn sequelize db:migrate
```

- .gitlab-ci.yml :
```yaml
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:
```json
{
  "Id": "Policy1587216857769",
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Stmt1587216727444",
      "Action": [
        "s3:GetObject"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:s3:::wiki-assets/*",
      "Principal": "*"
    }
  ]
}
```

- cors.xml:
```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 :

![Download s3 config](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/433ryw4hyqhhs06a00hg.jpeg)

- Add a Makefile to be able to simplify cors and policy management :
```Makefile
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](https://www.clever-cloud.com/doc/getting-started/cli/) 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.


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ykmrit7aami1qejbrsd5.png)

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

You should have now a running Outline :

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ro3lsfr0a7d82a76401b.png)

Enjoy !

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gymrd6zsbe1eelrzaggd.png)


## What about updating in future ?

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

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b927ijdaxktklc1rzk5m.png)

There is at some things to do :

- update Dockerfile image version with new version (check the version in [hub.docker.com](https://hub.docker.com/r/outlinewiki/outline/tags) before).
- you could have to run some additional migration script sometimes, check in [release page](https://github.com/outline/outline/releases) 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 !