diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/dev/webpack.md | 26 | ||||
| -rw-r--r-- | docs/guides/auth/gitlab-self-hosted.md | 6 | ||||
| -rw-r--r-- | docs/guides/auth/ldap-AD.md | 42 | ||||
| -rw-r--r-- | docs/guides/auth/nextcloud.md | 52 | ||||
| -rw-r--r-- | docs/guides/images/auth/nextcloud-oauth2-1-settings.png | bin | 0 -> 47047 bytes | |||
| -rw-r--r-- | docs/guides/images/auth/nextcloud-oauth2-2-client-add.png | bin | 0 -> 11684 bytes | |||
| -rw-r--r-- | docs/guides/images/auth/nextcloud-oauth2-3-clientid-secret.png | bin | 0 -> 13428 bytes | |||
| -rw-r--r-- | docs/guides/migrate-etherpad.md | 131 |
8 files changed, 254 insertions, 3 deletions
diff --git a/docs/dev/webpack.md b/docs/dev/webpack.md new file mode 100644 index 00000000..7b391f3a --- /dev/null +++ b/docs/dev/webpack.md @@ -0,0 +1,26 @@ +# Webpack Docs +## `webpack.common.js` +This file contains all common definition for chunks and plugins, that are needed by the whole app. + +**TODO:** Document which entry points are used for what. + +## `webpack.htmlexport.js` +Separate config for the "save as html" feature. +Packs all CSS from `public/js/htmlExport.js` to `build/html.min.css`. +This file is then downloaded by client-side JS and used to create the HTML. +See `exportToHTML()` in `public/js/extra.js`. + + +## `webpack.dev.js` +The development config uses both common configs, enables development mode and enables "cheap" source maps (lines only). +If you need more detailed source maps while developing, you might want to use the `source-maps` option. +See https://webpack.js.org/configuration/devtool/ for details. + +## `webpack.prod.js` +The production config uses both common configs and enables production mode. +This automatically enables various optimizations (e.g. UglifyJS). See https://webpack.js.org/concepts/mode/ for details. + +For the global app config, the name of the emitted chunks is changed to include the content hash. +See https://webpack.js.org/guides/caching/ on why this is a good idea. + +For the HTML export config, CSS minification is enabled. diff --git a/docs/guides/auth/gitlab-self-hosted.md b/docs/guides/auth/gitlab-self-hosted.md index 89bc996f..60f62616 100644 --- a/docs/guides/auth/gitlab-self-hosted.md +++ b/docs/guides/auth/gitlab-self-hosted.md @@ -7,12 +7,12 @@ 2. Navigate to the application management page at `https://your.gitlab.domain/admin/applications` (admin permissions required) 3. Click **New application** to create a new application and fill out the registration form: - + 4. Click **Submit** 5. In the list of applications select **HackMD**. Leave that site open to copy the application ID and secret in the next step. - + 6. In the `docker-compose.yml` add the following environment variables to `app:` `environment:` @@ -29,4 +29,4 @@ 7. Run `docker-compose up -d` to apply your settings. 8. Sign in to your HackMD using your GitLab ID: - + diff --git a/docs/guides/auth/ldap-AD.md b/docs/guides/auth/ldap-AD.md new file mode 100644 index 00000000..77521db3 --- /dev/null +++ b/docs/guides/auth/ldap-AD.md @@ -0,0 +1,42 @@ +AD LDAP auth +=== + + +To setup your CodiMD instance with Active Directory you need the following configs: + +``` +CMD_LDAP_URL=ldap://internal.example.com +CMD_LDAP_BINDDN=cn=binduser,cn=Users,dc=internal,dc=example,dc=com +CMD_LDAP_BINDCREDENTIALS=<super secret password> +CMD_LDAP_SEARCHBASE=dc=internal,dc=example,dc=com +CMD_LDAP_SEARCHFILTER=(&(objectcategory=person)(objectclass=user)(|(sAMAccountName={{username}})(mail={{username}}))) +CMD_LDAP_USERIDFIELD=sAMAccountName +CMD_LDAP_PROVIDERNAME=Example Inc AD +``` + + +`CMD_LDAP_BINDDN` is either the `distinguishedName` or the `userPrincipalName`. *This can cause "username/password is invalid" when either this value or the password from `CMD_LDAP_BINDCREDENTIALS` are incorrect.* + +`CMD_LDAP_SEARCHFILTER` matches on all users and uses either the email address or the `sAMAccountName` (usually the login name you also use to login to Windows). + +*Only using `sAMAccountName` looks like this:* `(&(objectcategory=person)(objectclass=user)(sAMAccountName={{username}}))` + +`CMD_LDAP_USERIDFIELD` says we want to use `sAMAccountName` as unique identifier for the account itself. + +`CMD_LDAP_PROVIDERNAME` just the name written above the username and password field on the login page. + + +Same in json: + +```json +"ldap": { + "url": "ldap://internal.example.com", + "bindDn": "cn=binduser,cn=Users,dc=internal,dc=example,dc=com", + "bindCredentials": "<super secret password>", + "searchBase": "dc=internal,dc=example,dc=com", + "searchFilter": "(&(objectcategory=person)(objectclass=user)(|(sAMAccountName={{username}})(mail={{username}})))", + "useridField": "sAMAccountName", +}, +``` + +More details and example: https://www.npmjs.com/package/passport-ldapauth diff --git a/docs/guides/auth/nextcloud.md b/docs/guides/auth/nextcloud.md new file mode 100644 index 00000000..108772dd --- /dev/null +++ b/docs/guides/auth/nextcloud.md @@ -0,0 +1,52 @@ +Authentication guide - Nextcloud (self-hosted) +=== + +*This has been constructed using the [Nextcloud OAuth2 Documentation](https://docs.nextcloud.com/server/14/admin_manual/configuration_server/oauth2.html?highlight=oauth2) combined with [this issue comment on the nextcloud bugtracker](https://github.com/nextcloud/server/issues/5694#issuecomment-314761326).* + +This guide uses the generic OAuth2 module for compatibility with Nextcloud 13 and above (this guide has been tested successfully with Nextcloud 14). + +1. Sign-in with an administrator account to your Nextcloud server + +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. +  + +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>. +  + + +4. You'll now see a line containing a *client identifier* and a *Secret*. +  + +5. That's it for Nextcloud, the rest is configured in your CodiMD `config.json` or via the `CMD_` environment variables! + +6. Add the Client ID and Client Secret to your `config.json` file or pass them as environment variables. Make sure you also replace `<your-nextcloud-domain>` with the right domain name. + * `config.json`: + ```javascript + { + "production": { + "oauth2": { + "clientID": "ii4p1u3jz7dXXXXXXXXXXXXXXX", + "clientSecret": "mqzzx6fydbXXXXXXXXXXXXXXXX", + "authorizationURL": "https://<your-nextcloud-domain>/apps/oauth2/authorize", + "tokenURL": "https://<your-nextcloud-domain>/apps/oauth2/api/v1/token", + "userProfileURL": "https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json", + "userProfileUsernameAttr": "ocs.data.id", + "userProfileDisplayNameAttr": "ocs.data.display-name", + "userProfileEmailAttr": "ocs.data.email" + } + } + } + ``` + * environment variables: + ```sh + CMD_OAUTH2_CLIENT_ID=ii4p1u3jz7dXXXXXXXXXXXXXXX + CMD_OAUTH2_CLIENT_SECRET=mqzzx6fydbXXXXXXXXXXXXXXXX + CMD_OAUTH2_AUTHORIZATION_URL=https://<your-nextcloud-domain>/apps/oauth2/authorize + CMD_OAUTH2_TOKEN_URL=https://<your-nextcloud-domain>/apps/oauth2/api/v1/token + CMD_OAUTH2_USER_PROFILE_URL=https://<your-nextcloud-domain>/ocs/v2.php/cloud/user?format=json + CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=ocs.data.id + CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=ocs.data.display-name + CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=ocs.data.email + ``` diff --git a/docs/guides/images/auth/nextcloud-oauth2-1-settings.png b/docs/guides/images/auth/nextcloud-oauth2-1-settings.png Binary files differnew file mode 100644 index 00000000..82652a54 --- /dev/null +++ b/docs/guides/images/auth/nextcloud-oauth2-1-settings.png diff --git a/docs/guides/images/auth/nextcloud-oauth2-2-client-add.png b/docs/guides/images/auth/nextcloud-oauth2-2-client-add.png Binary files differnew file mode 100644 index 00000000..7909fa62 --- /dev/null +++ b/docs/guides/images/auth/nextcloud-oauth2-2-client-add.png diff --git a/docs/guides/images/auth/nextcloud-oauth2-3-clientid-secret.png b/docs/guides/images/auth/nextcloud-oauth2-3-clientid-secret.png Binary files differnew file mode 100644 index 00000000..b05513d1 --- /dev/null +++ b/docs/guides/images/auth/nextcloud-oauth2-3-clientid-secret.png diff --git a/docs/guides/migrate-etherpad.md b/docs/guides/migrate-etherpad.md new file mode 100644 index 00000000..c3783c89 --- /dev/null +++ b/docs/guides/migrate-etherpad.md @@ -0,0 +1,131 @@ +Pad migration guide from etherpad-lite +=== + +The goal of this migration is to do a "dumb" import from all the pads in Etherpad, to notes in +CodiMD. In particular, the url locations of the pads in Etherpad will be lost. Furthermore, any +metadata in Etherpad, such as revisions, author data and also formatted text will not be migrated +to CodiMD (only the plain text contents). + +Note that this guide is not really meant as a support guide. I migrated my own Etherpad to CodiMD, +and it turned out to be quite easy in my opinion. In this guide I share my experience. Stuff may +require some creativity to work properly in your case. When I wrote this guide, I was using +[Etherpad 1.7.0] and [CodiMD 1.2.1]. Good luck! + +[Etherpad 1.7.0]: https://github.com/ether/etherpad-lite/tree/1.7.0 +[CodiMD 1.2.1]: https://github.com/hackmdio/codimd/tree/1.2.1 + +## 0. Requirements + +- `curl` +- running Etherpad server +- running CodiMD server +- [codimd-cli] + +[codimd-cli]: https://github.com/hackmdio/codimd-cli/blob/master/bin/codimd + +## 1. Retrieve the list of pads + +First, compose a list of all the pads that you want to have migrated from your Etherpad. Other than +the admin interface, Etherpad does not have a dedicated function to dump a list of all the pads. +However, the Etherpad wiki explains how to list all the pads by [talking directly to the +database][howtolistallpads]. + +You will end up with a file containing a pad name on each line: + +``` +date-ideas +groceries +london +weddingchecklist +(...) +``` + +[howtolistallpads]: https://github.com/ether/etherpad-lite/wiki/How-to-list-all-pads/49701ecdcbe07aea7ad27ffa23aed0d99c2e17db + +## 2. Run the migration + +Download [codimd-cli] and put the script in the same directory as the file containing the pad names. +Add to this directory the file listed below, I called it `migrate-etherpad.sh`. Modify at least the +configuration settings `ETHERPAD_SERVER` and `CODIMD_SERVER`. + +```shell +#!/bin/sh + +# migrate-etherpad.sh +# +# Description: Migrate pads from etherpad to codimd +# Author: Daan Sprenkels <hello@dsprenkels.com> + +# This script uses the codimd command line script[1] to import a list of pads from +# [1]: https://github.com/hackmdio/codimd-cli/blob/master/bin/codimd + +# The base url to where etherpad is hosted +ETHERPAD_SERVER="https://etherpad.example.com" + +# The base url where codimd is hosted +CODIMD_SERVER="https://codimd.example.com" + +# Write a list of pads and the urls which they were migrated to +REDIRECTS_FILE="redirects.txt" + + +# Fail if not called correctly +if (( $# != 1 )); then + echo "Usage: $0 PAD_NAMES_FILE" + exit 2 +fi + +# Do the migration +for PAD_NAME in $1; do + # Download the pad + PAD_FILE="$(mktemp)" + curl "$ETHERPAD_SERVER/p/$PAD_NAME/export/txt" >"$PAD_FILE" + + # Import the pad into codimd + OUTPUT="$(./codimd import "$PAD_FILE")" + echo "$PAD_NAME -> $OUTPUT" >>"$REDIRECTS_FILE" +done +``` + +Call this file like this: + +```shell +./migrate-etherpad.sh pad_names.txt +``` + +This will download all the pads in `pad_names.txt` and put them on CodiMD. They will get assigned +random ids, so you won't be able to find them. The script will save the mappings to a file though +(in my case `redirects.txt`). You can use this file to redirect your users when they visit your +etherpad using a `301 Permanent Redirect` status code (see the next section). + +## 3. Setup redirects (optional) + +I got a `redirects.txt` file that looked a bit like this: + +``` +date-ideas -> Found. Redirecting to https://codimd.example.com/mPt0KfiKSBOTQ3mNcdfn +groceries -> Found. Redirecting to https://codimd.example.com/UukqgwLfhYyUUtARlcJ2_y +london -> Found. Redirecting to https://codimd.example.com/_d3wa-BE8t4Swv5w7O2_9R +weddingchecklist -> Found. Redirecting to https://codimd.example.com/XcQGqlBjl0u40wfT0N8TzQ +(...) +``` + +Using some `sed` magic, I changed it to an nginx config snippet: + +``` +location = /p/date-ideas { + return 301 https://codimd.example.com/mPt0M1KfiKSBOTQ3mNcdfn; +} +location = /p/groceries { + return 301 https://codimd.example.com/UukqgwLfhYyUUtARlcJ2_y; +} +location = /p/london { + return 301 https://codimd.example.com/_d3wa-BE8t4Swv5w7O2_9R; +} +location = /p/weddingchecklist { + return 301 https://codimd.example.com/XcQGqlBjl0u40wfT0N8TzQ; +} +``` + +I put this file into my `etherpad.example.com` nginx config, such that all the users would be +redirected accordingly. |
