Using Open Source Documentation /Wiki Software from Scratch

This article introduces an open source documentation/Wiki software, Outline, suitable for individual or team scenarios.

Before I show you how to deploy it, let’s talk about why I chose it.

Writing in the front

As a heavy user of Confluence and a former heavy user of EverNote, I felt compelled to share my thoughts on documentation, notes, and Wiki software. If you are only interested in deployment environments, skip to the sections below.

Why switch notes /Wiki software

Those of you who are familiar with me know that I am a heavy user of Confluence, and a lot of my personal data is stored on the private deployment instances. I also purchased an additional NUC to run the service at low cost, as well as many public or undisclosed optimization schemes. For more information about Confluence deployments and operations operations, check out the fluence section here.

However, before the official announcement, I will no longer sell authorization, only provide overseas online SaaS services, although my authorization will expire in 2022, but considering the long-term use, it is inevitable to take a rainy day to see if there is a better alternative.

Confluence license is about to expire

After trying out a number of SaaS solutions both at home and abroad, as well as some that support private deployment like Joplin, and some that are primarily local tools like Obsidian, I settled on Outline, which is less well known today.

Outline Daily use interface

Why did YOU choose Outline

I have been using this software for more than two months now, and I still “toss” and “hesitate” before confirming my choice.

There are three main factors influencing my choice of a new tool: first, the writing experience should be close to or better than Confluence, second, I can have absolute control over my input and feel comfortable using the tool for authoring and content management, and third, the overall cost of using the tool should be relatively low. This combination reduces the number of “finished products” to choose from:

Writing experience mainly decided by the tools of the editor response interaction ability, but is decided by this part, not just want to realize more and more routine, need before and after the combination, Confluence was iteration for more than ten years, did a comprehensive on the product experience, lead to switch to the new software, always feel where is short of some new software.
There is no lack of tools at home and abroad to provide SaaS solutions, some free, but also some cost higher than Confluence, or from the resource quota, or from the number of collaborative restrictions, within the budget to solve the problem is naturally the best, but tool manufacturers in order to “renew”, in order to continue to make profits to live, Or expand the number on the book to take more investment, rarely fully give the user data disposal rights to the user, and almost no data can be completely self-hosted management, which is related to the SaaS ecosystem model and the current severe payment environment, software and users are wary of each other, quite boring.
There are also some open source or closed source tool solutions with self-hosting capability at home and abroad, but these solutions started relatively early, and most of the product strategy is a reference to the earlier pure note-taking software like EverNote. There are still many differences between the product and Wiki products in content creation scenes and content management logic. I hate “ineffective hoarding” of material, especially if it’s the default logic of the software. “Knowledge base” tools are not enough to solve the “writing” and “gathering” needs, but also to solve the “use” problem.
How about using Confluence to create an editor that works with these types of BaaS services (many of which support private deployment)? Although it is a customized editor based on tinyMCE, the writing threshold is not high, but there are a lot of details related to product experience, from front to back, in other words, the workload is not completely in the front end. Maybe IN the future I’ll consider doing something different, but for now I want to focus on content as much as possible, not building wheels.
In addition, the annual authorization fee before Confluence is only 10 dollars, about 60 yuan, compared with the current cost of various products, or relatively low, if you consider long-term use, purchase a small host, container start up is done. (Compared with the same cloud host configuration resources are cheaper and more affordable)
As for the maintenance cost, Confluence maintenance cost is not low, but after a long time to maintain a number of instances, almost trample all kinds of pits, hand familiar, but also ok. If I choose the solution again, I will choose the tool with simple technology stack and open code first. If the code is not open, there needs to be a tool with clear specification on data storage.

After searching and trying various kinds of software, I focused on Outline, a software that aims to become a Wiki and knowledge base used by growth teams. Its intuitive advantages are as follows:

Outline is open source software written by Node. The database is Postgres 9.x +. Redis can be used as the cache and s3-compatible object storage protocol is used for some storage. Users are allowed to modify and privatized deployment at will, and all data is controlled by users themselves, as long as users do not launch the same cloud services as the official ones for commercial competition after transformation.
The runtime editor is very much like a lite version of Notion. The shortcuts and syntax markers used for writing are almost the same as those used for writing in Confluence, and there is almost no learning cost (except for a few shortcuts).
Floating cards similar to Obsidian Publish are provided in the software interface, which can quickly understand the outline of other contents in the tool without changing the context, thus saving the time of context switch.
Team collaboration and sharing are supported, but not mandatory, and are friendly for individual use scenarios, or for private use by small groups.
In addition, all article data can be exported directly (the default format is Markdown). Similarly, you can use the API or write your own gadget to quickly convert and import the entire site.

Of course, software is in a period of rapid iteration and has its drawbacks. Personally, I think the main reason for these problems is that Slack ecosystem has solved and supplemented these problems. Stripped from Slack ecosystem, product logic naturally needs to be adjusted and functions naturally need to be supplemented:

Before, the software was heavily bound to Slack ecosystem, and many functions were deeply bound to Slack. Private deployment once only supported login authorization using Slack and GitHub OAuth. Maintainers are currently working on authentication related ISSUE#1945, and we should see substantial changes (in team usage scenarios) in the next few releases.
The software’s previous support for self-hosting has not been so friendly and there has been a lot of discussion among community members under ISSUE#1881. With the efforts of the community and the authors, it is expected that there will be qualitative changes in the next release. I’ve already made an “early release” mirror based on these changes, so you don’t need to wait for the official release to get a taste of it.
Comment is not supported at present, officials are working on it. ISSUE#457
The attachment management function is also missing at present, which is planned to be addressed in the next two versions. ISSUE#859 but there are a number of solutions, and I’ll go through them in a later article and talk about the simplest way.
, etc.

There are many problems, but they may not be the most important for individual and small team use, and there are many low-cost solutions.

Next, let’s talk about how to quickly and easily deploy the software privately.

Use containers for private deployment

Earlier, I submitted sample code on GitHub: github.com/soulteary/d… In order to reduce configuration complexity, Traefik is also used as a service gateway in this example. If you are not familiar with Traefik, you can read the previous section of “Easier Traefik 2 Usage” and some examples of Traefik in action to further your understanding.

In a Traefik service-ready environment, we were able to get Outline running in just a few steps.

Step 1: Download the sample code

First, download the sample code locally.

git clone https://github.com/soulteary/docker-outline.git
Copy the code

If you are experiencing network problems during the download, you can use the image address:

git clone https://github.com.cnpmjs.org/soulteary/docker-outline.git
Copy the code

Step 2: Create your profile

Make a copy of your config file, call it.env, and change the things you “care about” :

cp .env.example .env
Copy the code

I personally recommend modifying the following configuration:

For all domain name related configurations, use your own domain name instead.

DOCKER_MINIO_HOSTNAME=file.lab.com
DOCKER_MINIO_ADMIN_DOMAIN=file-admin.lab.com
SSO_SERVER_DOMAIN=sso.lab.com
DOCKER_ATTACHMENT_HOSTNAME=attachment.lab.com
DOCKER_OUTLINE_HOSTNAME=docs.lab.com
Copy the code

You can manually generate a copy of the key configuration by referring to the link or generation method in the comments. If you are running on a private network, it is not a problem if you do not modify it.

# Select `Lowercase a-z and numbers` and 16-bit string length https://onlinerandomtools.com/generate-random-string
MINIO_ROOT_USER=6m2lx2ffmbr9ikod
# Select `Lowercase a-z and numbers` and 64-bit string length https://onlinerandomtools.com/generate-random-string
MINIO_ROOT_PASSWORD=2k78fpraq7rs5xlrti5p6cvb767a691h3jqi47ihbu75cx23twkzpok86sf1aw1e
MINIO_REGION_NAME=cn-homelab-1

DOCKER_POSTGRES_PASS=qTj5kwUEetmN

# You can use online tools to regenerate: https://www.uuidgenerator.net/
SSO_CLIENT_ID=b8c40013-cc03-4bc5-b3a5-6a31046fa415
SSO_CLIENT_SECRET=26272010-37d9-4bea-a58e-6b0a382d7626 

# Execute in the CLI `htpasswd -nb user pass`
DOCKER_ATTACHMENT_BASIC_AUTH=user:$apr1$8wC8avYf$Nhn0oTAvNjdw8FPROokGN.

# `openssl rand -hex 32`
OUTLINE_SECRET_KEY=64074328631d7ce618f554694ff7e83e820b9f7e14b13e4317893fed18e0b3c3
OUTLINE_UTILS_SECRET=04d7572e983ee6adfd77f8c77b61be8236a9e459fc9c1b7032ec278345638bcc
Copy the code

If you want to log in using your own username instead of the default SSO username, you need to modify the following configuration to avoid the login being intercepted by Outline.

OIDC_ALLOWED_DOMAINS=company.ltd
Copy the code

I have mentioned in soulteary/ Docker-Sso-Server that the default user account and mailbox used for SSO are as follows:

User:username.
Password:password
Email address:[email protected]

If you want to customize the generation of your information, you can use the license agreement online generation tool to generate your license file.

Step 3: Start the application

According to your actual situation, create a virtual network card belonging to Outline, so that various applications can communicate with each other independently. If you have already created this network card, then you can skip here and continue to see how to start the application.

docker network create outline
Copy the code

Docker-compose then selects various application configurations using Docker-compose and launches various services required by the application with one click:

docker-compose -f docker-compose.postgres.yml -f docker-compose.redis.yml -f docker-compose.minio.yml -f docker-compose.attachment.yml -f docker-compose.sso.yml -f docker-compose.outline.yml up -d
Copy the code

Once the command is executed, you should see something like the following:

Creating outline_minio    ... done
Creating outline-postgres ... done
Creating outline-redis    ... done
Creating linx-server      ... done
Creating outline          ... done
Creating sso-server       ... done
Copy the code

However, we cannot use Outline at this point. There are some initialization operations that need to be done after the service is first started, but rest assured, these operations are automated. Just wait a moment for the service to be ready to start.

We can check the health of the service by using the following command.

docker-compose -f docker-compose.postgres.yml -f docker-compose.redis.yml -f docker-compose.minio.yml -f docker-compose.attachment.yml -f docker-compose.sso.yml -f docker-compose.outline.yml ps   
Copy the code

When you see log content like the following (the service status shows HEALTHY), we can access the domain name we set in the configuration in the browser and use Outline. (In this case, I set the domain name to docs.lab.com)

      Name                    Command                  State        Ports  
---------------------------------------------------------------------------
linx-server        /usr/local/bin/linx-server ...   Up (healthy)   8080/tcp
outline            docker-entrypoint.sh sh -c ...   Up (healthy)   3000/tcp
outline-postgres   docker-entrypoint.sh postgres    Up (healthy)   5432/tcp
outline-redis      docker-entrypoint.sh redis ...   Up (healthy)   6379/tcp
outline_minio      /usr/bin/docker-entrypoint ...   Up (healthy)   9000/tcp
sso-server         docker-entrypoint.sh ./main      Up (healthy)   80/tcp   
Copy the code

Not surprisingly, you should see something like the following.

Outline Initial interface

Since the SSO login service is used, we continue to talk about the first use of Outline.

Use Outline briefly

After the service is running properly, open Outline in your browser, click the login with MySSO button, and the page will be redirected to the SSO service running locally.

The default SSO login screen

In Step 2: Create your Profile, I mentioned how to customize the username and password, as well as the default username and password. We log in using the set account password and will be led to the OTP tool setup interface.

Set up the OTP tool

You can use any tool you are familiar with or like to complete OTP binding by scanning the QR code or establishing the key. When you log in to the application for the first time in the future, SSO service will not only ask you for your account password, but also confirm with you the OTP code generated in real time. Thus enhancing the security of your local account login and the application data access security behind it.

I’m using Google’s Google Authenticator here, but it’s ok if you use Microsoft’s or a third party’s. After all, it’s a generic protocol and you can parse anything, even “web”, as long as it works for you.

After the configuration is complete, click the blue “OK” button and you will be asked to enter the first OTP code.

Validate the OTP code for the first time

Because it took too long to use the first time and the parameters used for authentication expired, we might be redirected to the Outline’s home page. At this time, we can safely click “continue with MySSO” again and wait for a moment to see the “real Outline”.

The default Outline content screen

Software interface is very simple, function distribution is relatively clear, I believe that without too much introduction, you can directly begin to explore, I believe that no one can resist the “out of the box” fun, so the basic use part, I will not do the first to expand, their own exploration out of the gameplay is the “most fragrant”.

However, I guess there must be “English bitter hands” among the users. Currently, the Chinese in Outline is ready. It is recommended to click the “Settings” link in the left sidebar to enter the setting page and switch the language to Chinese. Two months ago, I updated part of the official translation, and now most of the content is in Chinese. If there are any missing fish, please feel free to contact me.

Adjusting the Language Configuration

In addition, if you want to customize the default app name “Wiki”, you can change the “team” name in the Settings screen to update the content.

Update the team name

The last

Although WE talked about this article about Outline in the group as early as the end of July, considering the data security and stable operation, it has been delayed until now. After full use and verification, the pit should be finished this month.

In the next Outline, I will talk about how to carry out more detailed configuration.

–EOF

We have a little group of hundreds of people who like to do things.

In the case of no advertisement, we will talk about software and hardware, HomeLab and programming problems together, and also share some information of technical salon irregularly in the group.

Like to toss small partners welcome to scan code to add friends. (To add friends, please note your real name, source and purpose, otherwise it will not be approved)

All this stuff about getting into groups

If you think the content is still practical, welcome to share it with your friends. Thank you.

This article is published under a SIGNATURE 4.0 International (CC BY 4.0) license. Signature 4.0 International (CC BY 4.0)

Author: Su Yang

Creation time: sep 05, 2021 statistical word count: 8223 words reading time: 17 minutes to read this article links: soulteary.com/2021/09/05/…