Editing CommunityData:Etherpad

Our group typically takes real-time notes in [[:wikipedia:Etherpad|Etherpad]] which is a little like Google Docs but for text files and with color everywhere to see who is working where and who has written what. Our Etherpad server is: https://etherpad.communitydata.science/

To create a new page, just go to https://etherpad.communitydata.science/ and type in the name of the page. It's a good idea to make it unique/descriptive and to include a date. A good name might be <code>cdsc_cabal_meeting-20380119</code>. Etherpads are public webpages. You can choose a pagename that is random or might be difficult to guess but you cannot make one that is truly private.

== Semi Private Pads ==

You can make a semi-private one by including the word "private" in front of the pad name. For example, if you name your pad <code>private-cdsc_cabal_meeting-20380119</code> people will be asked for a username and password shared with the group. You can ask other folks in the group for the username or password or you can find by searching the [[CommunityData:Email#Email Lists|email list]] archives for the '''collective-XXXX@communitydata.science''' email lists.

== Backing up Etherpads ==

Etherpads should not be treated as long term storage. Although we have no plan to purge things from our own server, there's no promise that they will be kept across upgrades and server migrations either. As a result, we have a system to backup our Etherpads. It runs once a days and keeps a backup copy each day. We can use the backups to go back to any old copy of any Etherpad so you can safely blow away old text and know you will be able to get the archived text back if you need it.

That said, we need to register every Etherpad that we want backed up first. To do that, we need to first check out <code>cdsc-etherpads</code> repository from the [[CommunityData:Git|group Git repository]] with a line in your terminal like:

<syntaxhighlight lang='bash'>
git clone git@code.communitydata.science:cdsc-etherpads
</syntaxhighlight>

If you get a permission denied errors, follow the instructions on [[CommunityData:Git]] to get setup to use the CDSC git repository.

To start backing up a new Git repository, you should add a new line to the bottom of <code>ETHERPAD_URLS</code>. The lines should look like:

<syntaxhighlight lang='bash'>
http://etherpad.communitydata.science/p/cdsc_cabal_meeting-20380119 # meeting notes from the winter 2038 cabal meeting
</syntaxhighlight>

As you can see, comments following <code>#</code> are supported in the file. They are not required.

The complete workflow should look like:

<syntaxhighlight lang='bash'>
git clone git@code.communitydata.science:cdsc-etherpads
cd cdsc-etherpads
vim ETHERPAD_URLS # or whatever your preferred editor is!
##### EDIT TO ADD NEW URL #######
git add ETHERPAD_URLS
git commit -m 'added new cabal URL'
git push
</syntaxhighlight>

== Administration for Etherpad ==

To maintain Etherpad we need to update the git repository on our etherpad server (anhel). Every time we do this, we'll first run these commands:

<syntaxhighlight lang='bash'>
sudo -u etherpad bash              # get a shell as the etherpad user
cd ~etherpad/etherpad-lite         # change to the directory for the etherpad user
</syntaxhighlight>

=== Upgrading Etherpad to new upstream version ===

To upgrade "everything" it should be enough to do this (''after'' running the command above):

<syntaxhighlight lang='bash'>
git pull
</syntaxhighlight>

Then, run the following command ''as root'':

<syntaxhighlight lang='bash'>
systemctl restart etherpad
</syntaxhighlight>

=== Installing a plugin ===

If we wanted to install the <code>ep_comments_page</code> plugin we would (a) fun the first two commands above to get into the right directory (do ''not'' run these as root or from some other directory!) and then run the following command:

<syntaxhighlight lang='bash'>
npm install ep_comments_page
</syntaxhighlight>

Once, again, we will restart Etherpad running the following command as root:

<syntaxhighlight lang='bash'>
systemctl restart etherpad
</syntaxhighlight>