diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 70 |
1 files changed, 50 insertions, 20 deletions
@@ -8,8 +8,8 @@ HackMD [![version][github-version-badge]][github-release-page] -HackMD lets you create realtime collaborative markdown notes on all platforms. -Inspired by Hackpad, with more focus on speed and flexibility. +HackMD lets you create realtime collaborative markdown notes on all platforms. +Inspired by Hackpad, with more focus on speed and flexibility. Still in the early stage, feel free to fork or contribute to HackMD. Thanks for using! :smile: @@ -41,11 +41,11 @@ Thanks for using! :smile: # Browsers Requirement -- Chrome >= 47, Chrome for Android >= 47 -- Safari >= 9, iOS Safari >= 8.4 -- Firefox >= 44 -- IE >= 9, Edge >= 12 -- Opera >= 34, Opera Mini not supported +-  Chrome >= 47, Chrome for Android >= 47 +-  Safari >= 9, iOS Safari >= 8.4 +-  Firefox >= 44 +-  IE >= 9, Edge >= 12 +-  Opera >= 34, Opera Mini not supported - Android Browser >= 4.4 # Installation @@ -74,11 +74,26 @@ You can quickly setup a sample heroku hackmd application by clicking the button [](https://heroku.com/deploy) ## HackMD by docker container +[](http://play-with-docker.com?stack=https://github.com/hackmdio/docker-hackmd/raw/master/docker-compose.yml&stack_name=hackmd) -[docker-hackmd](https://github.com/hackmdio/docker-hackmd) -Before you go too far, here is the great docker repo for HackMD. -With docker, you can deploy a server in minutes without any downtime. +**Debian-based version:** + +[](https://microbadger.com/images/hackmdio/hackmd "Get your own version badge on microbadger.com") [](https://microbadger.com/images/hackmdio/hackmd "Get your own image badge on microbadger.com") + + +**Alpine-based version:** + +[](https://microbadger.com/images/hackmdio/hackmd:latest-alpine "Get your own version badge on microbadger.com") [](https://microbadger.com/images/hackmdio/hackmd:latest-alpine "Get your own image badge on microbadger.com") + +The easiest way to setup HackMD using docker are using the following three commands: + +```console +git clone https://github.com/hackmdio/docker-hackmd.git +cd docker-hackmd +docker-compose up +``` +Read more about it in the [docker repository…](https://github.com/hackmdio/docker-hackmd) # Upgrade @@ -97,13 +112,13 @@ If you are upgrading HackMD from an older version, follow these steps: * [migration-to-0.5.0](https://github.com/hackmdio/migration-to-0.5.0) -We don't use LZString to compress socket.io data and DB data after version 0.5.0. +We don't use LZString to compress socket.io data and DB data after version 0.5.0. Please run the migration tool if you're upgrading from the old version. * [migration-to-0.4.0](https://github.com/hackmdio/migration-to-0.4.0) -We've dropped MongoDB after version 0.4.0. -So here is the migration tool for you to transfer the old DB data to the new DB. +We've dropped MongoDB after version 0.4.0. +So here is the migration tool for you to transfer the old DB data to the new DB. This tool is also used for official service. # Configuration @@ -141,6 +156,9 @@ There are some configs you need to change in the files below | HMD_GITLAB_BASEURL | no example | GitLab authentication endpoint, set to use other endpoint than GitLab.com (optional) | | HMD_GITLAB_CLIENTID | no example | GitLab API client id | | HMD_GITLAB_CLIENTSECRET | no example | GitLab API client secret | +| HMD_MATTERMOST_BASEURL | no example | Mattermost authentication endpoint | +| HMD_MATTERMOST_CLIENTID | no example | Mattermost API client id | +| HMD_MATTERMOST_CLIENTSECRET | no example | Mattermost API client secret | | HMD_DROPBOX_CLIENTID | no example | Dropbox API client id | | HMD_DROPBOX_CLIENTSECRET | no example | Dropbox API client secret | | HMD_GOOGLE_CLIENTID | no example | Google API client id | @@ -151,9 +169,19 @@ There are some configs you need to change in the files below | HMD_LDAP_TOKENSECRET | `supersecretkey` | secret used for generating access/refresh tokens | | HMD_LDAP_SEARCHBASE | `o=users,dc=example,dc=com` | LDAP directory to begin search from | | HMD_LDAP_SEARCHFILTER | `(uid={{username}})` | LDAP filter to search with | -| HMD_LDAP_SEARCHATTRIBUTES | no example | LDAP attributes to search with | +| HMD_LDAP_SEARCHATTRIBUTES | `displayName, mail` | LDAP attributes to search with (use comma to separate) | | HMD_LDAP_TLS_CA | `server-cert.pem, root.pem` | Root CA for LDAP TLS in PEM format (use comma to separate) | | HMD_LDAP_PROVIDERNAME | `My institution` | Optional name to be displayed at login form indicating the LDAP provider | +| HMD_SAML_IDPSSOURL | `https://idp.example.com/sso` | authentication endpoint of IdP. for details, see [guide](docs/guides/auth.md#saml-onelogin). | +| HMD_SAML_IDPCERT | `/path/to/cert.pem` | certificate file path of IdP in PEM format | +| HMD_SAML_ISSUER | no example | identity of the service provider (optional, default: serverurl)" | +| HMD_SAML_IDENTIFIERFORMAT | no example | name identifier format (optional, default: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`) | +| HMD_SAML_GROUPATTRIBUTE | `memberOf` | attribute name for group list (optional) | +| HMD_SAML_REQUIREDGROUPS | `Hackmd-users` | group names that allowed (use vertical bar to separate) (optional) | +| HMD_SAML_EXTERNALGROUPS | `Temporary-staff` | group names that not allowed (use vertical bar to separate) (optional) | +| HMD_SAML_ATTRIBUTE_ID | `sAMAccountName` | attribute map for `id` (optional, default: NameID of SAML response) | +| HMD_SAML_ATTRIBUTE_USERNAME | `mailNickname` | attribute map for `username` (optional, default: NameID of SAML response) | +| HMD_SAML_ATTRIBUTE_EMAIL | `mail` | attribute map for `email` (optional, default: NameID of SAML response if `HMD_SAML_IDENTIFIERFORMAT` is default) | | HMD_IMGUR_CLIENTID | no example | Imgur API client id | | HMD_EMAIL | `true` or `false` | set to allow email signin | | HMD_ALLOW_PDF_EXPORT | `true` or `false` | Enable or disable PDF exports | @@ -216,8 +244,8 @@ There are some configs you need to change in the files below | service | settings location | description | | ------- | --------- | ----------- | -| facebook, twitter, github, gitlab, dropbox, google, ldap | environment variables or `config.json` | for signin | -| imgur | environment variables or `config.json` | for image upload | +| facebook, twitter, github, gitlab, mattermost, dropbox, google, ldap, saml | environment variables or `config.json` | for signin | +| imgur, s3 | environment variables or `config.json` | for image upload | | google drive(`google/apiKey`, `google/clientID`), dropbox(`dropbox/appKey`) | `config.json` | for export and import | ## Third-party integration oauth callback urls @@ -228,8 +256,10 @@ There are some configs you need to change in the files below | twitter | `/auth/twitter/callback` | | github | `/auth/github/callback` | | gitlab | `/auth/gitlab/callback` | +| mattermost | `/auth/mattermost/callback` | | dropbox | `/auth/dropbox/callback` | | google | `/auth/google/callback` | +| saml | `/auth/saml/callback` | # Developer Notes @@ -249,16 +279,16 @@ hackmd/ ## 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. +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/) # License -**License under MIT.** +**License under AGPL.** [gitter-image]: https://badges.gitter.im/Join%20Chat.svg [gitter-url]: https://gitter.im/hackmdio/hackmd?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge |