Skip to content
Permalink
Browse files

striving for consistency across various docs

Signed-off-by: Claudius <opensource@amenthes.de>
  • Loading branch information...
ccoenen committed Mar 31, 2019
1 parent 74fdd26 commit 54edec89000aec94cae325be3d5c85442ac21adf
@@ -8,7 +8,6 @@ composer.lock
.idea/
Thumbs.db
npm-debug.log
hackmd_io
newrelic_agent.log
logs/
tmp/
@@ -6,7 +6,8 @@ CodiMD
[![version][github-version-badge]][github-release-page]
[![POEditor][poeditor-image]][poeditor-url]

CodiMD lets you create real-time collaborative markdown notes on all platforms.
CodiMD lets you create real-time collaborative markdown notes.

It is inspired by Hackpad, Etherpad and similar collaborative editors. This
project originated with the team at [HackMD](https://hackmd.io) and now forked
into its own organisation. [A longer writeup can be read in the history doc](docs/history.md).
@@ -16,13 +17,14 @@ into its own organisation. [A longer writeup can be read in the history doc](doc

## Community and Contributions

We welcome contributions! There's a lot to do. If you would like to report bugs
We welcome contributions! There's a lot to do. If you would like to report bugs,
the [issue tracker](github-issue-tracker) is the right place. If you want to
help translating, find us on [POEditor](poeditor-url). To get started developing,
take a look at the [docs/dev](docs/dev) directory. In any case: come talk to us,
we'll be delighted to help you with the first steps.

To stay up to date with your installation it's recommended to join our [Matrix channel][matrix.org-url] or subscribe to the [release feed][github-release-feed].
To stay up to date with our work it's recommended to join our
[Matrix channel][matrix.org-url] or subscribe to the [release feed][github-release-feed].


## Installation / Upgrading
@@ -1,4 +1,5 @@
# Configuration Using Config file
Configuration Using Config file
===

You can choose to configure CodiMD with either a config file or with
[environment variables](configuration-env-vars.md). The config file is processed
@@ -1,4 +1,5 @@
# Configuration Using Environment variables
Configuration Using Environment variables
===

You can choose to configure CodiMD with either a
[config file](configuration-config-file.md) or with environment variables.
@@ -1,12 +1,12 @@
# Developer Notes
Developer Notes
===

## Preparing for running the code

**Notice:** *If you're into [docker](../setup/docker.md) or [heroku](../setup/heroku.md),
there's extra documents for those!*
**Notice:** *There's [specialised instructions for docker](../setup/docker.md) or [heroku](../setup/heroku.md), if you prefer running code this way!*

1. Clone the repository (Cloning is the preferred way, but you can also download
and unzip a release)
1. Clone the repository with `git clone https://github.com/codimd/server.git codimd-server`
(cloning is the preferred way, but you can also download and unzip a release)
2. Enter the directory and run `bin/setup`, which will install npm dependencies
and create configs. The setup script is written in Bash, you would need bash
as a prerequisite.
@@ -1,6 +1,14 @@
## Operational Transformation
Operational Transformation
===

From 0.3.2, we started supporting operational transformation.
It makes concurrent editing safe and will not break up other users' operations.
Additionally, now can show other clients' selections.
See more at [http://operational-transformation.github.io/](http://operational-transformation.github.io/)

See more at [https://operational-transformation.github.io/](https://operational-transformation.github.io/)

And even more in this 2010 article series:

* https://drive.googleblog.com/2010/09/whats-different-about-new-google-docs_21.html
* https://drive.googleblog.com/2010/09/whats-different-about-new-google-docs_22.html
* https://drive.googleblog.com/2010/09/whats-different-about-new-google-docs.html
@@ -1,4 +1,11 @@
# Webpack Docs
Webpack
===

Webpack is a JavaScript build system for frontend code. You can find out all
about it on [the webpack website](https://webpack.js.org/).

Here's how we're using it:

## `webpack.common.js`
This file contains all common definition for chunks and plugins, that are needed by the whole app.

@@ -1,27 +1,24 @@
Authentication guide - GitHub
===

***Note:** This guide was written before the renaming. Just replace `HackMD` with `CodiMD` in your mind :smile: thanks!*
**Note:** *This guide was written before the renaming. Just replace `HackMD` with `CodiMD` in your mind :smile: thanks!*

1. Sign-in or sign-up for a GitHub account
2. Navigate to developer settings in your GitHub account [here](https://github.com/settings/developers) and select the "OAuth Apps" tab
3. Click on the **New OAuth App** button, to create a new OAuth App:
3. Click on the **New OAuth App** button, to create a new OAuth App:
![create-oauth-app](../../images/auth/create-oauth-app.png)

![create-oauth-app](../../images/auth/create-oauth-app.png)
4. Fill out the new OAuth application registration form, and click **Register Application**
![register-oauth-application-form](../../images/auth/register-oauth-application-form.png)

4. Fill out the new OAuth application registration form, and click **Register Application**
**Note:** *The callback URL is <your-codimd-url>/auth/github/callback*

![register-oauth-application-form](../../images/auth/register-oauth-application-form.png)
*Note: The callback URL is <your-hackmd-url>/auth/github/callback*
5. After successfully registering the application, you'll receive the Client ID and Client Secret for the application
![application-page](../../images/auth/application-page.png)
5. After successfully registering the application, you'll receive the Client ID and Client Secret for the application
![application-page](../../images/auth/application-page.png)

6. Add the Client ID and Client Secret to your config.json file or pass them as environment variables
* config.json:
````javascript
* `config.json`:
```js
{
"production": {
"github": {
@@ -30,9 +27,9 @@ Authentication guide - GitHub
}
}
}
````
```
* environment variables:
````
HMD_GITHUB_CLIENTID=3747d30eaccXXXXXXXXX
HMD_GITHUB_CLIENTSECRET=2a8e682948eee0c580XXXXXXXXXXXXXXXXXXXXXX
```sh
CMD_GITHUB_CLIENTID=3747d30eaccXXXXXXXXX
CMD_GITHUB_CLIENTSECRET=2a8e682948eee0c580XXXXXXXXXXXXXXXXXXXXXX
````
@@ -1,7 +1,7 @@
# GitLab (self-hosted)
GitLab (self-hosted)
===

***Note:** This guide was written before the renaming. Just replace `HackMD` with `CodiMD` in your mind :smile: thanks!*
**Note:** *This guide was written before the renaming. Just replace `HackMD` with `CodiMD` in your mind :smile: thanks!*

1. Sign in to your GitLab
2. Navigate to the application management page at `https://your.gitlab.domain/admin/applications` (admin permissions required)
@@ -18,7 +18,7 @@
6. In the `docker-compose.yml` add the following environment variables to `app:` `environment:`

```
- HMD_DOMAIN=your.hackmd.domain
- HMD_DOMAIN=your.codimd.domain
- HMD_URL_ADDPORT=443
- HMD_PROTOCOL_USESSL=true
- HMD_GITLAB_BASEURL=https://your.gitlab.domain
@@ -27,6 +27,6 @@
```

7. Run `docker-compose up -d` to apply your settings.
8. Sign in to your HackMD using your GitLab ID:
8. Sign in to your CodiMD using your GitLab ID:

![Sign in via GitLab](../../images/auth/gitlab-sign-in.png)
@@ -1,7 +1,6 @@
AD LDAP auth
===


To setup your CodiMD instance with Active Directory you need the following configs:

```
@@ -1,33 +1,29 @@
Authentication guide - Mattermost (self-hosted)
===

*Note: The Mattermost setup portion of this document is just a quick guide. See the [official documentation](https://docs.mattermost.com/developer/oauth-2-0-applications.html) for more details.*
**Note:** *The Mattermost setup portion of this document is just a quick guide. See the [official documentation](https://docs.mattermost.com/developer/oauth-2-0-applications.html) for more details.*

This guide uses the generic OAuth2 module for compatibility with Mattermost version 5.0 and above.

1. Sign-in with an administrator account to your Mattermost instance
2. Make sure **OAuth 2.0 Service Provider** is enabled in the Main Menu (menu button next to your username in the top left corner) --> System Console --> Custom Integrations menu, which you can find at `https://your.mattermost.domain/admin_console/integrations/custom`

![mattermost-enable-oauth2](../../images/auth/mattermost-enable-oauth2.png)
2. Make sure **OAuth 2.0 Service Provider** is enabled in the Main Menu (menu button next to your username in the top left corner) --> System Console --> Custom Integrations menu, which you can find at `https://your.mattermost.domain/admin_console/integrations/custom`
![mattermost-enable-oauth2](../../images/auth/mattermost-enable-oauth2.png)

3. Navigate to the OAuth integration settings through Main Menu --> Integrations --> OAuth 2.0 Applications, at `https://your.mattermost.domain/yourteam/integrations/oauth2-apps`
4. Click on the **Add OAuth 2.0 Application** button to add a new OAuth application

![mattermost-oauth-app-add](../../images/auth/mattermost-oauth-app-add.png)
4. Click on the **Add OAuth 2.0 Application** button to add a new OAuth application
![mattermost-oauth-app-add](../../images/auth/mattermost-oauth-app-add.png)

5. Fill out the form and click **Save**

![mattermost-oauth-app-form](../../images/auth/mattermost-oauth-app-form.png)
5. Fill out the form and click **Save**
![mattermost-oauth-app-form](../../images/auth/mattermost-oauth-app-form.png)

*Note: The callback URL is \<your-codimd-url\>/auth/oauth2/callback*

6. After saving the application, you'll receive the Client ID and Client Secret

![mattermost-oauth-app-done](../../images/auth/mattermost-oauth-app-done.png)
6. After saving the application, you'll receive the Client ID and Client Secret
![mattermost-oauth-app-done](../../images/auth/mattermost-oauth-app-done.png)

7. Add the Client ID and Client Secret to your config.json file or pass them as environment variables
* config.json:
````javascript
* `config.json`:
```javascript
{
"production": {
"oauth2": {
@@ -43,9 +39,9 @@ This guide uses the generic OAuth2 module for compatibility with Mattermost vers
}
}
}
````
```
* environment variables:
````
```sh
CMD_OAUTH2_BASEURL=https://your.mattermost.domain
CMD_OAUTH2_USER_PROFILE_URL=https://your.mattermost.domain/api/v4/users/me
CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=id
@@ -55,4 +51,4 @@ This guide uses the generic OAuth2 module for compatibility with Mattermost vers
CMD_OAUTH2_AUTHORIZATION_URL=https://your.mattermost.domain/oauth/authorize
CMD_OAUTH2_CLIENT_ID=ii4p1u3jz7dXXXXXXXXXXXXXXX
CMD_OAUTH2_CLIENT_SECRET=mqzzx6fydbXXXXXXXXXXXXXXXX
````
```
@@ -9,10 +9,10 @@ This guide uses the generic OAuth2 module for compatibility with Nextcloud 13 an

2. Navigate to the OAuth integration settings: Profile Icon (top right) --> Settings
Then choose Security Settings from the *Administration* part of the list - Don't confuse this with Personal Security Settings, where you would change your personal password!
At the top there's OAuth 2.0-Clients.
At the top there's OAuth 2.0-Clients.
![Where to find OAuth2 in Nextcloud](../../images/auth/nextcloud-oauth2-1-settings.png)

3. Add your CodiMD instance by giving it a *name* (perhaps CodiMD, but could be anything) and a *Redirection-URI*. The Redirection-URI will be `\<your-codimd-url\>/auth/oauth2/callback`. Click <kbd>Add</kbd>.
3. Add your CodiMD instance by giving it a *name* (perhaps CodiMD, but could be anything) and a *Redirection-URI*. The Redirection-URI will be `\<your-codimd-url\>/auth/oauth2/callback`. Click <kbd>Add</kbd>.
![Adding a client to Nextcloud](../../images/auth/nextcloud-oauth2-2-client-add.png)


@@ -1,40 +1,35 @@
Authentication guide - SAML (OneLogin)
===

***Note:** This guide was written before the renaming. Just replace `HackMD` with `CodiMD` in your mind :smile: thanks!*
**Note:** *This guide was written before the renaming. Just replace `HackMD` with `CodiMD` in your mind :smile: thanks!*

1. Sign-in or sign-up for an OneLogin account. (available free trial for 2 weeks)
2. Go to the administration page.
3. Select the **APPS** menu and click on the **Add Apps**.
3. Select the **APPS** menu and click on the **Add Apps**.
![onelogin-add-app](../../images/auth/onelogin-add-app.png)

![onelogin-add-app](../../images/auth/onelogin-add-app.png)
4. Find "SAML Test Connector (SP)" for template of settings and select it.
![onelogin-select-template](../../images/auth/onelogin-select-template.png)

4. Find "SAML Test Connector (SP)" for template of settings and select it.
![onelogin-select-template](../../images/auth/onelogin-select-template.png)
5. Edit display name and icons for OneLogin dashboard as you want, and click **SAVE**.
![onelogin-edit-app-name](../../images/auth/onelogin-edit-app-name.png)
5. Edit display name and icons for OneLogin dashboard as you want, and click **SAVE**.
![onelogin-edit-app-name](../../images/auth/onelogin-edit-app-name.png)

6. After that other tabs will appear, click the **Configuration**, and fill out the below items, and click **SAVE**.
* RelayState: The base URL of your hackmd, which is issuer. (last slash is not needed)
* ACS (Consumer) URL Validator: The callback URL of your hackmd. (serverurl + /auth/saml/callback)
* RelayState: The base URL of your CodiMD, which is issuer. (last slash is not needed)
* ACS (Consumer) URL Validator: The callback URL of your CodiMD. (serverurl + /auth/saml/callback)
* ACS (Consumer) URL: same as above.
* Login URL: login URL(SAML requester) of your hackmd. (serverurl + /auth/saml)
![onelogin-edit-sp-metadata](../../images/auth/onelogin-edit-sp-metadata.png)
* Login URL: login URL(SAML requester) of your CopiMD. (serverurl + /auth/saml)
![onelogin-edit-sp-metadata](../../images/auth/onelogin-edit-sp-metadata.png)

7. The registration is completed. Next, click **SSO** and copy or download the items below.
* X.509 Certificate: Click **View Details** and **DOWNLOAD** or copy the content of certificate ....(A)
* SAML 2.0 Endpoint (HTTP): Copy the URL ....(B)
![onelogin-copy-idp-metadata](../../images/auth/onelogin-copy-idp-metadata.png)
* SAML 2.0 Endpoint (HTTP): Copy the URL ....(B)
![onelogin-copy-idp-metadata](../../images/auth/onelogin-copy-idp-metadata.png)

8. In your hackmd server, create IdP certificate file from (A)
8. In your CodiMD server, create IdP certificate file from (A)
9. Add the IdP URL (B) and the Idp certificate file path to your config.json file or pass them as environment variables.
* config.json:
````javascript
* `config.json`:
```javascript
{
"production": {
"saml": {
@@ -43,12 +38,11 @@ Authentication guide - SAML (OneLogin)
}
}
}
````
```
* environment variables
````
HMD_SAML_IDPSSOURL=https://*******.onelogin.com/trust/saml2/http-post/sso/******
HMD_SAML_IDPCERT=/path/to/idp_cert.pem
````
10. Try sign-in with SAML from your hackmd sign-in button or OneLogin dashboard (like the screenshot below).
![onelogin-use-dashboard](../../images/auth/onelogin-use-dashboard.png)
```sh
CMD_SAML_IDPSSOURL=https://*******.onelogin.com/trust/saml2/http-post/sso/******
CMD_SAML_IDPCERT=/path/to/idp_cert.pem
```
10. Try sign-in with SAML from your CodiMD sign-in button or OneLogin dashboard (like the screenshot below).
![onelogin-use-dashboard](../../images/auth/onelogin-use-dashboard.png)
Oops, something went wrong.

0 comments on commit 54edec8

Please sign in to comment.
You can’t perform that action at this time.