2016-01-19 16:21:45 +00:00
HackMD
2015-05-04 07:53:29 +00:00
===
2015-08-15 04:15:42 +00:00
[![Join the chat at https://gitter.im/hackmdio/hackmd ](https://badges.gitter.im/Join%20Chat.svg )](https://gitter.im/hackmdio/hackmd?utm_source=badge& utm_medium=badge& utm_campaign=pr-badge& utm_content=badge)
2016-10-04 10:05:30 +00:00
HackMD lets you create realtime collaborative markdown notes on all platforms.
Inspired by Hackpad, with more focus on speed and flexibility.
2016-10-03 02:33:30 +00:00
Still in the early stage, feel free to fork or contribute to HackMD.
2015-05-04 07:53:29 +00:00
2016-10-03 02:33:30 +00:00
Thanks for using! :smile:
2015-05-15 04:58:13 +00:00
2016-04-20 10:03:55 +00:00
[docker-hackmd ](https://github.com/hackmdio/docker-hackmd )
---
2016-10-04 08:41:26 +00:00
2016-10-04 10:05:30 +00:00
Before you go too far, here is the great docker repo for HackMD.
2016-10-03 02:33:30 +00:00
With docker, you can deploy a server in minutes without any downtime.
2016-04-20 10:03:55 +00:00
2016-10-14 11:28:54 +00:00
Heroku Deployment
---
You can quickly setup a sample heroku hackmd application by clicking the button below.
[![Deploy ](https://www.herokucdn.com/deploy/button.svg )](https://heroku.com/deploy)
2017-01-02 03:15:20 +00:00
[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.
Please run the migration tool if you're upgrading from the old version.
2016-04-20 10:03:55 +00:00
[migration-to-0.4.0 ](https://github.com/hackmdio/migration-to-0.4.0 )
---
2016-10-04 08:41:26 +00:00
2016-10-04 10:05:30 +00:00
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.
2016-04-20 10:03:55 +00:00
This tool is also used for official service.
2016-01-29 19:28:45 +00:00
Browsers Requirement
---
2016-10-04 08:41:26 +00:00
2016-10-31 07:32:36 +00:00
- Chrome >= 47, Chrome for Android >= 47
2016-01-29 19:28:45 +00:00
- Safari >= 9, iOS Safari >= 8.4
- Firefox >= 44
- IE >= 9, Edge >= 12
- Opera >= 34, Opera Mini not supported
- Android Browser >= 4.4
2015-09-27 06:45:21 +00:00
Prerequisite
2015-07-11 04:52:04 +00:00
---
2016-10-04 08:41:26 +00:00
2016-10-11 04:43:19 +00:00
- Node.js 4.x or up (test up to 6.7.0)
2016-10-15 16:53:33 +00:00
- Database (PostgreSQL, MySQL, MariaDB, SQLite, MSSQL) use charset `utf8`
2017-02-08 06:30:31 +00:00
- npm (and its dependencies, especially [uWebSockets ](https://github.com/uWebSockets/uWebSockets#nodejs-developers ), [node-gyp ](https://github.com/nodejs/node-gyp#installation ))
2015-07-11 04:52:04 +00:00
2015-09-27 06:45:21 +00:00
Get started
2015-06-01 10:04:25 +00:00
---
2016-10-04 08:41:26 +00:00
2015-09-27 06:45:21 +00:00
1. Download a release and unzip or clone into a directory
2016-12-11 02:31:51 +00:00
2. Enter the directory and type `bin/setup` , which will install npm dependencies and create configs. The setup script is written in Bash, you would need bash as a prerequisite.
2016-10-03 02:33:30 +00:00
3. Setup the configs, see more below
4. Setup environment variables which will overwrite the configs
2017-01-04 06:27:38 +00:00
5. Build front-end bundle by `npm run build` (use `npm run dev` if you are in development)
2016-10-15 06:35:31 +00:00
6. Run the server as you like (node, forever, pm2)
2015-06-01 10:04:25 +00:00
2016-06-14 14:57:54 +00:00
Upgrade guide
2016-06-01 16:13:01 +00:00
---
2016-10-04 08:41:26 +00:00
2016-06-14 19:30:19 +00:00
If you are upgrading HackMD from an older version, follow these steps:
2016-06-14 14:57:54 +00:00
2016-10-03 02:33:30 +00:00
1. Fully stop your old server first (important)
2. `git pull` or do whatever that updates the files
2016-12-11 02:31:51 +00:00
3. `npm install` to update dependencies
2017-01-14 07:27:24 +00:00
4. Build front-end bundle by `npm run build` (use `npm run dev` if you are in development)
2016-12-11 15:24:04 +00:00
5. Modify the file named `.sequelizerc` , change the value of the variable `url` with your db connection string
2016-10-03 02:33:30 +00:00
For example: `postgres://username:password@localhost:5432/hackmd`
2016-12-11 15:24:04 +00:00
6. Run `node_modules/.bin/sequelize db:migrate` , this step will migrate your db to the latest schema
7. Start your whole new server!
2016-06-01 16:13:01 +00:00
2015-07-01 16:10:20 +00:00
Structure
---
2016-10-04 08:41:26 +00:00
```text
2015-07-01 16:10:20 +00:00
hackmd/
2016-10-04 08:41:26 +00:00
├── tmp/ --- temporary files
├── docs/ --- document files
├── lib/ --- server libraries
└── public/ --- client files
├── css/ --- css styles
├── js/ --- js scripts
├── vendor/ --- vendor includes
└── views/ --- view templates
2015-07-01 16:10:20 +00:00
```
2015-09-15 08:49:23 +00:00
Configuration files
2015-06-01 10:04:25 +00:00
---
2016-10-04 08:41:26 +00:00
2016-10-03 02:33:30 +00:00
There are some configs you need to change in the files below
2016-10-04 08:41:26 +00:00
2015-05-15 04:58:13 +00:00
```
2017-01-14 07:24:31 +00:00
./config.json ----application settings
2015-05-15 04:58:13 +00:00
```
2016-04-20 10:03:55 +00:00
Environment variables (will overwrite other server configs)
2015-09-15 08:08:50 +00:00
---
2016-10-04 08:41:26 +00:00
2015-09-15 08:08:50 +00:00
| variables | example values | description |
| --------- | ------ | ----------- |
2016-10-03 02:33:30 +00:00
| NODE_ENV | `production` or `development` | set current environment (will apply corresponding settings in the `config.json` ) |
2016-04-20 10:03:55 +00:00
| DEBUG | `true` or `false` | set debug mode, show more logs |
2016-10-10 13:16:58 +00:00
| HMD_DOMAIN | `hackmd.io` | domain name |
| HMD_URL_PATH | `hackmd` | sub url path, like `www.example.com/<URL_PATH>` |
| HMD_PORT | `80` | web app port |
| HMD_ALLOW_ORIGIN | `localhost, hackmd.io` | domain name whitelist (use comma to separate) |
| HMD_PROTOCOL_USESSL | `true` or `false` | set to use ssl protocol for resources path (only applied when domain is set) |
| HMD_URL_ADDPORT | `true` or `false` | set to add port on callback url (port 80 or 443 won't applied) (only applied when domain is set) |
2016-10-23 14:27:02 +00:00
| HMD_USECDN | `true` or `false` | set to use CDN resources or not (default is `true` ) |
2016-12-21 13:36:54 +00:00
| HMD_ALLOW_ANONYMOUS | `true` or `false` | set to allow anonymous usage (default is `true` ) |
2016-12-16 07:38:05 +00:00
| HMD_ALLOW_FREEURL | `true` or `false` | set to allow new note by accessing not exist note url |
2017-02-10 02:49:45 +00:00
| HMD_DEFAULT_PERMISSION | `freely` , `editable` , `limited` , `locked` or `private` | set notes default permission (only applied on signed users) |
2016-12-22 13:20:43 +00:00
| HMD_DB_URL | `mysql://localhost:3306/database` | set the db url |
2016-10-10 13:16:58 +00:00
| HMD_FACEBOOK_CLIENTID | no example | Facebook API client id |
| HMD_FACEBOOK_CLIENTSECRET | no example | Facebook API client secret |
| HMD_TWITTER_CONSUMERKEY | no example | Twitter API consumer key |
| HMD_TWITTER_CONSUMERSECRET | no example | Twitter API consumer secret |
| HMD_GITHUB_CLIENTID | no example | GitHub API client id |
| HMD_GITHUB_CLIENTSECRET | no example | GitHub API client secret |
| 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_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 |
| HMD_GOOGLE_CLIENTSECRET | no example | Google API client secret |
2017-02-07 13:17:05 +00:00
| HMD_LDAP_URL | `ldap://example.com` | url of LDAP server |
2016-12-13 21:31:35 +00:00
| HMD_LDAP_BINDDN | no example | bindDn for LDAP access |
| HMD_LDAP_BINDCREDENTIALS | no example | bindCredentials for LDAP access |
2017-02-07 13:17:05 +00:00
| 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 |
2016-12-13 21:31:35 +00:00
| HMD_LDAP_SEARCHATTRIBUTES | no example | LDAP attributes to search with |
2017-02-07 13:17:05 +00:00
| 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 |
2016-10-10 13:16:58 +00:00
| HMD_IMGUR_CLIENTID | no example | Imgur API client id |
2017-01-12 03:25:58 +00:00
| HMD_EMAIL | `true` or `false` | set to allow email signin |
2017-01-12 16:51:40 +00:00
| HMD_ALLOW_EMAIL_REGISTER | `true` or `false` | set to allow email register (only applied when email is set, default is `true` ) |
2016-11-17 10:13:57 +00:00
| HMD_IMAGE_UPLOAD_TYPE | `imgur` , `s3` or `filesystem` | Where to upload image. For S3, see our [S3 Image Upload Guide ](docs/guides/s3-image-upload.md ) |
| HMD_S3_ACCESS_KEY_ID | no example | AWS access key id |
| HMD_S3_SECRET_ACCESS_KEY | no example | AWS secret key |
| HMD_S3_REGION | `ap-northeast-1` | AWS S3 region |
| HMD_S3_BUCKET | no example | AWS S3 bucket name |
2016-04-20 10:03:55 +00:00
2017-01-14 07:24:31 +00:00
Application settings `config.json`
2015-09-15 08:08:50 +00:00
---
2016-10-04 08:41:26 +00:00
2015-09-15 08:08:50 +00:00
| variables | example values | description |
| --------- | ------ | ----------- |
| debug | `true` or `false` | set debug mode, show more logs |
2016-04-20 10:03:55 +00:00
| domain | `localhost` | domain name |
| urlpath | `hackmd` | sub url path, like `www.example.com/<urlpath>` |
| port | `80` | web app port |
2015-09-15 08:08:50 +00:00
| alloworigin | `['localhost']` | domain name whitelist |
2016-04-20 10:03:55 +00:00
| usessl | `true` or `false` | set to use ssl server (if true will auto turn on `protocolusessl` ) |
2016-10-10 13:16:58 +00:00
| protocolusessl | `true` or `false` | set to use ssl protocol for resources path (only applied when domain is set) |
| urladdport | `true` or `false` | set to add port on callback url (port 80 or 443 won't applied) (only applied when domain is set) |
2016-10-23 14:27:02 +00:00
| usecdn | `true` or `false` | set to use CDN resources or not (default is `true` ) |
2016-12-21 13:36:54 +00:00
| allowanonymous | `true` or `false` | set to allow anonymous usage (default is `true` ) |
2016-12-16 07:38:05 +00:00
| allowfreeurl | `true` or `false` | set to allow new note by accessing not exist note url |
2017-02-10 02:49:45 +00:00
| defaultpermission | `freely` , `editable` , `limited` , `locked` or `private` | set notes default permission (only applied on signed users) |
2016-12-22 13:20:43 +00:00
| dburl | `mysql://localhost:3306/database` | set the db url, if set this variable then below db config won't be applied |
2016-04-20 10:03:55 +00:00
| db | `{ "dialect": "sqlite", "storage": "./db.hackmd.sqlite" }` | set the db configs, [see more here ](http://sequelize.readthedocs.org/en/latest/api/sequelize/ ) |
| sslkeypath | `./cert/client.key` | ssl key path (only need when you set usessl) |
| sslcertpath | `./cert/hackmd_io.crt` | ssl cert path (only need when you set usessl) |
| sslcapath | `['./cert/COMODORSAAddTrustCA.crt']` | ssl ca chain (only need when you set usessl) |
| dhparampath | `./cert/dhparam.pem` | ssl dhparam path (only need when you set usessl) |
| tmppath | `./tmp/` | temp directory path |
| defaultnotepath | `./public/default.md` | default note file path |
| docspath | `./public/docs` | docs directory path |
| indexpath | `./public/views/index.ejs` | index template file path |
| hackmdpath | `./public/views/hackmd.ejs` | hackmd template file path |
| errorpath | `./public/views/error.ejs` | error template file path |
| prettypath | `./public/views/pretty.ejs` | pretty template file path |
| slidepath | `./public/views/slide.hbs` | slide template file path |
2015-09-15 08:08:50 +00:00
| sessionname | `connect.sid` | cookie session name |
| sessionsecret | `secret` | cookie session secret |
| sessionlife | `14 * 24 * 60 * 60 * 1000` | cookie session life |
2016-04-20 10:03:55 +00:00
| staticcachetime | `1 * 24 * 60 * 60 * 1000` | static file cache time |
2015-09-15 08:08:50 +00:00
| heartbeatinterval | `5000` | socket.io heartbeat interval |
| heartbeattimeout | `10000` | socket.io heartbeat timeout |
| documentmaxlength | `100000` | note max length |
2017-01-12 03:25:58 +00:00
| email | `true` or `false` | set to allow email signin |
2017-01-12 16:51:40 +00:00
| allowemailregister | `true` or `false` | set to allow email register (only applied when email is set, default is `true` ) |
2016-11-17 10:13:57 +00:00
| imageUploadType | `imgur` (default), `s3` or `filesystem` | Where to upload image
| s3 | `{ "accessKeyId": "YOUR_S3_ACCESS_KEY_ID", "secretAccessKey": "YOUR_S3_ACCESS_KEY", "region": "YOUR_S3_REGION", "bucket": "YOUR_S3_BUCKET_NAME" }` | When `imageUploadType` be setted to `s3` , you would also need to setup this key, check our [S3 Image Upload Guide ](docs/guides/s3-image-upload.md ) |
2016-03-15 03:30:43 +00:00
Third-party integration api key settings
---
2016-10-04 08:41:26 +00:00
2016-10-10 13:16:58 +00:00
| service | settings location | description |
2016-03-15 03:30:43 +00:00
| ------- | --------- | ----------- |
2016-12-13 21:31:35 +00:00
| facebook, twitter, github, gitlab, dropbox, google, ldap | environment variables or `config.json` | for signin |
2016-10-10 13:16:58 +00:00
| imgur | environment variables or `config.json` | for image upload |
2017-01-14 07:24:31 +00:00
| google drive(`google/apiKey`, `google/clientID` ), dropbox(`dropbox/appKey`) | `config.json` | for export and import |
2016-04-23 10:58:24 +00:00
2016-07-05 15:16:02 +00:00
Third-party integration oauth callback urls
---
2016-10-04 08:41:26 +00:00
2016-07-05 15:16:02 +00:00
| service | callback url (after the server url) |
| ------- | --------- |
| facebook | `/auth/facebook/callback` |
| twitter | `/auth/twitter/callback` |
| github | `/auth/github/callback` |
| gitlab | `/auth/gitlab/callback` |
| dropbox | `/auth/dropbox/callback` |
| google | `/auth/google/callback` |
2015-09-15 08:49:23 +00:00
Operational Transformation
2015-06-01 10:04:25 +00:00
---
2016-10-04 08:41:26 +00:00
2016-10-04 10:05:30 +00:00
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.
2016-10-04 08:41:26 +00:00
See more at [http://operational-transformation.github.io/ ](http://operational-transformation.github.io/ )
2015-05-08 03:52:30 +00:00
2015-09-25 02:39:09 +00:00
**License under MIT.**