README.md 6.72 KB
Newer Older
John McLear's avatar
John McLear committed
1 2
### This project is looking for a new project lead.  If you wish to help steer Etherpad forward please email contact@etherpad.org

John McLear's avatar
John McLear committed
3 4 5
[![Deps](https://david-dm.org/ether/etherpad-lite.svg?branch=develop)](https://david-dm.org/ether/etherpad-lite)
[![NSP Status](https://nodesecurity.io/orgs/etherpad/projects/635f6185-35c6-4ed7-931a-0bc62758ece7/badge)](https://nodesecurity.io/orgs/etherpad/projects/635f6185-35c6-4ed7-931a-0bc62758ece7)

6
# A really-real time collaborative word processor for the web
John McLear's avatar
John McLear committed
7
![Demo Etherpad Animated Jif](https://i.imgur.com/zYrGkg3.gif "Etherpad in action on PrimaryPad")
Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
8

Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
9
# About
John McLear's avatar
John McLear committed
10 11 12
Etherpad is a really-real time collaborative editor scalable to thousands of simultanious real time users.  Unlike all other collaborative tools Etherpad provides full fidelity data export and portability making it fully GDPR compliant.  

**[Try it out](http://beta.etherpad.org)**
John McLear's avatar
John McLear committed
13

John McLear's avatar
John McLear committed
14
# Installation
John McLear's avatar
John McLear committed
15

John McLear's avatar
John McLear committed
16 17 18 19
## Uber-Quick Ubuntu
```
curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -
sudo apt-get install -y nodejs
John McLear's avatar
John McLear committed
20
git clone https://github.com/ether/etherpad-lite.git && cd etherpad-lite && bin/run.sh
John McLear's avatar
John McLear committed
21
```
John McLear's avatar
John McLear committed
22

John McLear's avatar
John McLear committed
23 24 25 26 27
## GNU/Linux and other UNIX-like systems
You'll need gzip, git, curl, libssl develop libraries, python and gcc.  
- *For Debian/Ubuntu*: `apt install gzip git curl python libssl-dev pkg-config build-essential`  
- *For Fedora/CentOS*: `yum install gzip git curl python openssl-devel && yum groupinstall "Development Tools"`
- *For FreeBSD*: `portinstall node, npm, curl, git (optional)`
John McLear's avatar
John McLear committed
28

John McLear's avatar
John McLear committed
29
Additionally, you'll need [node.js](https://nodejs.org) installed, Ideally the latest stable version, we recommend installing/compiling nodejs from source (avoiding apt).
30

John McLear's avatar
John McLear committed
31
**As any user (we recommend creating a separate user called etherpad):**
Marcel Klehr's avatar
Marcel Klehr committed
32

John McLear's avatar
John McLear committed
33 34
1. Move to a folder where you want to install Etherpad. Clone the git repository `git clone git://github.com/ether/etherpad-lite.git`
2. Change into the new directory containing the cloned source code `cd etherpad-lite`
35

John McLear's avatar
John McLear committed
36
Now, run `bin/run.sh` and open <http://127.0.0.1:9001> in your browser. 
Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
37

John McLear's avatar
John McLear committed
38
Update to the latest version with `git pull origin`. The next start with bin/run.sh will update the dependencies.
39

John McLear's avatar
John McLear committed
40
[Next steps](#next-steps).
41

Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
42
## Windows
43

44 45 46
### Prebuilt windows package
This package works out of the box on any windows machine, but it's not very useful for developing purposes...

47
1. [Download the latest windows package](http://etherpad.org/#download)
48 49 50 51 52
2. Extract the folder

Now, run `start.bat` and open <http://localhost:9001> in your browser. You like it? [Next steps](#next-steps).

### Fancy install
53
You'll need [node.js](https://nodejs.org) and (optionally, though recommended) git.
54 55

1. Grab the source, either
Marcel Klehr's avatar
Marcel Klehr committed
56 57
  - download <https://github.com/ether/etherpad-lite/zipball/master>
  - or `git clone https://github.com/ether/etherpad-lite.git` (for this you need git, obviously)
58 59 60 61 62 63
2. start `bin\installOnWindows.bat`

Now, run `start.bat` and open <http://localhost:9001> in your browser.

Update to the latest version with `git pull origin`, then run `bin\installOnWindows.bat`, again.

64 65 66 67 68 69
If cloning to a subdirectory within another project, you may need to do the following:

1. Start the server manually (e.g. `node/node_modules/ep_etherpad-lite/node/server.js]`)
2. Edit the db `filename` in `settings.json` to the relative directory with the file (e.g. `application/lib/etherpad-lite/var/dirty.db`)
3. Add auto-generated files to the main project `.gitignore`

70
# Next Steps
Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
71

72
## Tweak the settings
John McLear's avatar
John McLear committed
73
You can initially modify the settings in `settings.json`. (If you need to handle multiple settings files, you can pass the path to a settings file to `bin/run.sh` using the `-s|--settings` option. This allows you to run multiple Etherpad instances from the same installation.)  Once you have access to your /admin section settings can be modified through the web browser.
74

John McLear's avatar
John McLear committed
75
You should use a dedicated database such as "mysql", if you are planning on using etherpad-in a production environment, since the "dirtyDB" database driver is only for testing and/or development purposes.
76

77 78
## Plugins and themes

79
Etherpad is very customizable through plugins. Instructions for installing themes and plugins can be found in [the plugin wiki article](https://github.com/ether/etherpad-lite/wiki/Available-Plugins).
80

81
## Helpful resources
John McLear's avatar
John McLear committed
82
The [wiki](https://github.com/ether/etherpad-lite/wiki) is your one-stop resource for Tutorials and How-to's.
83

84
Documentation can be found in `doc/`.
Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
85

86
# Development
87

88
## Things you should know
89
Understand [git](https://training.github.com/) and watch this [video on getting started with Etherpad Development](https://youtu.be/67-Q26YH97E).
Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
90

91
If you're new to node.js, start with Ryan Dahl's [Introduction to Node.js](https://youtu.be/jo_B4LTHi3I).
92

John McLear's avatar
John McLear committed
93
You can debug Etherpad using `bin/debugRun.sh`.
94

johnyma22's avatar
johnyma22 committed
95
If you want to find out how Etherpad's `Easysync` works (the library that makes it really realtime), start with this [PDF](https://github.com/ether/etherpad-lite/raw/master/doc/easysync/easysync-full-description.pdf) (complex, but worth reading).
Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
96

John McLear's avatar
John McLear committed
97
## Contributing
98
Read our [**Developer Guidelines**](https://github.com/ether/etherpad-lite/blob/master/CONTRIBUTING.md)
Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
99

100
# Get in touch
John McLear's avatar
John McLear committed
101 102
[mailinglist](https://groups.google.com/group/etherpad-lite-dev)
[#etherpad-lite-dev freenode IRC](https://webchat.freenode.net?channels=#etherpad-lite-dev)!
booo's avatar
booo committed
103

John McLear's avatar
John McLear committed
104 105
# Languages
Etherpad is written in JavaScript on both the server and client so it's easy for developers to maintain and add new features.
Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
106

John McLear's avatar
John McLear committed
107 108 109 110 111
# HTTP API
Etherpad is designed to be easily embeddable and provides a [HTTP API](https://github.com/ether/etherpad-lite/wiki/HTTP-API)
that allows your web application to manage pads, users and groups. It is recommended to use the [available client implementations](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries) in order to interact with this API. 

# jQuery plugin 
112
There is a [jQuery plugin](https://github.com/ether/etherpad-lite-jquery-plugin) that helps you to embed Pads into your website.
John McLear's avatar
John McLear committed
113 114 115 116 117 118 119 120 121

# Plugin Framework
Etherpad offers a plugin framework, allowing you to easily add your own features.  By default your Etherpad is extremely light-weight and it's up to you to customize your experience.  Once you have Etherpad installed you should visit the plugin page and take control.

# Translations / Localizations  (i18n / l10n)
Etherpad comes with translations into all languages thanks to the team at TranslateWiki.

# FAQ
Visit the **[FAQ](https://github.com/ether/etherpad-lite/wiki/FAQ)**.
Peter 'Pita' Martischka's avatar
Peter 'Pita' Martischka committed
122

123
# Donate!
124
* [Flattr](https://flattr.com/thing/71378/Etherpad-Foundation)
125
* Paypal - Press the donate button on [etherpad.org](http://etherpad.org)
Alexey Pyltsyn's avatar
Alexey Pyltsyn committed
126
* [Bitcoin](https://coinbase.com/checkouts/1e572bf8a82e4663499f7f1f66c2d15a)
John McLear's avatar
John McLear committed
127

John McLear's avatar
John McLear committed
128 129
All donations go to the Etherpad foundation which is part of Software Freedom Conservency

John McLear's avatar
John McLear committed
130
# License
johnyma22's avatar
johnyma22 committed
131
[Apache License v2](http://www.apache.org/licenses/LICENSE-2.0.html)